dca_interface  6.3.4
List of all members | Public Member Functions | Static Public Member Functions
dca::DcaInstance Class Reference
DCA Base Package

#include <base_classes.h>

Inheritance diagram for dca::DcaInstance:

Detailed Description

Encapsulates the init and deinit of the DCA API.

When developing an application using the DCA, the first step is to instanciate a DcaInstance object.
Without a DcaInstance object you will not be able to call any other DCA functions, or create any other DCA classes.
The DcaInstance allows the creation of a License, used to instanciate other packages, for example classification or toolbox packages.
Whenever you want to use a classfication package that requires access to a signature database, you will need to create a DbConnection object. This object can be used as an input parameter for the classification package creation functions.
Use getCategoriesInfo() to return a CategoriesInfo object for one of the DCA internal category types.
See also
InitData, License, DbConnection, DcaInstance, CategoriesInfo, Getting started

Definition at line 314 of file base_classes.h.

Public Member Functions

FunctionResult setDefaultProxySettings (const ProxySettings &newProxySettings)
 Sets default proxy settings for all locations where proxy settings are used. More...
 
License createLicense (const LicenseData &licData, const ProxySettings &proxySettings=ProxySettings(), LogLevel aLogLevel=LOG_Initial) const
 Creates a License object using the given LicenseData. More...
 
DbConnection createDbConnection (const License &aLicense, const DbConnectionData &dbcData, const ProxySettings &proxySettings=ProxySettings(), LogLevel aLogLevel=LOG_Initial) const
 Creates a DbConnection object using the given DbConnectionData. More...
 
CategoriesInfo getCategoriesInfo (DCA_CATEGORIES_INFO_TYPE categoryType) const
 Returns the DCA internal categories, groups and locales. More...
 
VersionInfoResults getVersionInfo () const
 Returns enumerable version information about all currently loaded modules.

 
bool signal (unsigned int signal) const
 Cancels functions which could potentially take a long time to return, such as DcaInstance::schedule(). More...
 
FunctionResult schedule (ScheduleEventSubscriberIntf *pScheduleEventSubscriber=NULL) const
 Invokes scheduled tasks, e.g. Database updates and processes that can take a long time. More...
 

Static Public Member Functions

static DcaInstance create (const InitData &initData)
 Creates a DcaInstance, starts up the DCA API and initializes the required main module. More...
 

Member Function Documentation

◆ create()

static DcaInstance dca::DcaInstance::create ( const InitData &  initData)
static

Creates a DcaInstance, starts up the DCA API and initializes the required main module.

This is the first function to call when using the DCA API

The provided initData must specifiy the directories in which the DCA redist packages have been installed.

If the creation fails, a ExDca exception will be thrown.

If the DcaInstance is deleted (e.g. by going out of scope) the DCA API will be automatically shut down. After that point no more DCA functions are available. Any DCA classes created using DcaInstance must not be used.

Parameters
[in]initDataMust be set up with the redist installation directories of the DCA
Returns
The DCA instance that will be used as a factory for License, DbConnection and other classes.
Exceptions
ExDca- One of the following error may occur (using ExDca::getReturnCode() in your catch-handler)
Remarks
Do not use more than one DcaInstance for e.g. classification calls, updates, or anything else - only a single instance is currently supported.
For restarting the DCA session you can temporarily create a second DcaInstance and use that instance to create new instances of other DCA modules, e.g. license, classification modules, updates and then switch to that new DcaInstance and the new other DCA modules afterwards and then destroy the old DcaInstance alongside with the old instances of e.g. license module, update module, ...
See also
DCA Error Handling, ExDca, InitData

◆ setDefaultProxySettings()

FunctionResult dca::DcaInstance::setDefaultProxySettings ( const ProxySettings &  newProxySettings)

Sets default proxy settings for all locations where proxy settings are used.

You can set up default proxy settings on a DcaInstance. These will be used in other functions if there are no other special proxy settings provided e.g. for a remote DbConnection or License.
Special proxy settings will always overwrite the default proxy settings.
Parameters
[in]newProxySettingsWill be used as defaults for all newly created classes that supports proxy settings
Returns
Returns DCA_SUCCESS on success or
Note
Once you set default proxy settings they will be used for all subsequently created classes.
Previously created classes which require proxy settings (e.g. a DbConnection) will use the old proxy settings, or none if there no special settings were provided.

◆ createLicense()

License dca::DcaInstance::createLicense ( const LicenseData &  licData,
const ProxySettings &  proxySettings = ProxySettings(),
LogLevel  aLogLevel = LOG_Initial 
) const

Creates a License object using the given LicenseData.

Parameters
[in]licDataA LicenseData object, initialized with valid license data.
[in]proxySettingsIf provided uses the proxySettings for all License requests (HTTPS-connections)
[in]aLogLevelIf provided set the log level of the created license.
Returns
An initialized License object or (in case of an error) an ExDca exception will be thrown.
Exceptions
ExDca- One of the following error codes (available by using ExDca::getReturnCode() in your catch-handler)
Note
During this call, a connection will be made to the IBM license server to verify and update your license status.
See also
LicenseData, ProxySettings, Set up a license object

◆ createDbConnection()

DbConnection dca::DcaInstance::createDbConnection ( const License &  aLicense,
const DbConnectionData &  dbcData,
const ProxySettings &  proxySettings = ProxySettings(),
LogLevel  aLogLevel = LOG_Initial 
) const

Creates a DbConnection object using the given DbConnectionData.

Parameters
[in]aLicenseA License correctly set up by a previous call to createLicense() function
[in]dbcDataA DbConnectionData object, correctly set up depending on the type of DbConnection to create
[in]proxySettingsIf provided uses the proxySettings for remote database requests (HTTP-connections)
[in]aLogLevelIf provided set the log level of the created db connection.
Returns
A DbConnection object that can be used for other creation functions.
Exceptions
ExDca- One of the following error codes (available by using ExDca::getReturnCode() in your catch-handler)
  • DCA Generic Error Codes
  • ERR_INVALID_DATABASE - An attempt to connect to a local/custom database was not successful.
See also
DbConnectionData, ProxySettings

◆ getCategoriesInfo()

CategoriesInfo dca::DcaInstance::getCategoriesInfo ( DCA_CATEGORIES_INFO_TYPE  categoryType) const

Returns the DCA internal categories, groups and locales.

Parameters
[in]categoryTypeCan be one of
  • DCA_CAT_INFO_TYPE_MAIL
  • DCA_CAT_INFO_TYPE_TEXT
  • DCA_CAT_INFO_TYPE_URL
Returns
The currently used internal CategoriesInfo for the given categoryType.
Exceptions
ExDca- One of the following error codes (available by using ExDca::getReturnCode() in your catch-handler)
  • DCA Generic Error Codes
  • ERR_INVALID_FOLDER - The folder of DCA init directory was not found or is incomplete
  • ERR_INVALID_XML_FILES - The xml files of the DCA init directory are missing or corrupt
See also
CategoriesInfo

◆ signal()

bool dca::DcaInstance::signal ( unsigned int  signal) const

Cancels functions which could potentially take a long time to return, such as DcaInstance::schedule().

Call signal as reaction to a console or signal handler trap.
If you want to ensure a fast shutdown (whenever a terminate, abort or other signal arrives), you should call the signal function.
Some functions react on this call and quit immediately, returning ERR_SIG_ABORT_DETECTED (see DCA Generic Error Codes) return code.
Parameters
[in]signalThis is the translation for the DCA, and currently only DCA_SIG_ABORT is defined. Any other signal value will be ignored
Returns
true if all signal related classes have been successfully called and have aknowledged receipt of the signal, false otherwise, or the DCA_SIG_ABORT was not provided as as the signal.
Exceptions
none

◆ schedule()

FunctionResult dca::DcaInstance::schedule ( ScheduleEventSubscriberIntf *  pScheduleEventSubscriber = NULL) const

Invokes scheduled tasks, e.g. Database updates and processes that can take a long time.

Use a dedicated thread to call this function.
The database update mechanism used for local signature databases requires the use of schedule().
The function UpdateModule::performUpdate() only downloads updates of a limited size. the schedule function downloads complete databases and performs other time consuming operations.
The scheduled tasks work in conjunction with the update tasks. The performUpdate method of the UpdateModule must also be called using a dedicated thread.

If schedule() fails it is no longer recommended to restart the application. Instead you should keep calling the update and schedule functions on a regular basis because schedule errors are either tied to an SDK issue or tied to something out of SDK control (e.g. download problems, network connectivity issues, incorrect update files). In both cases an SDK restart won't help but e.g. update file issues might get resolved when we publish new updates.

Parameters
[in]pScheduleEventSubscriberAn optional pointer to an implementation of ScheduleEventSubscriberIntf. Set this parameter if you wish to receive notifications relating to schedule events.
Returns
If all succeeds it returns DCA_SUCCESS else it may return
See also
UpdateModule::performUpdate
The documentation for this class was generated from the following file:
Generated by   doxygen 1.8.18