dca::DcaInstance Class Reference
[DCA Base Package]

#include <base_classes.h>

List of all members.


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.
License createLicense (const LicenseData &licData, const ProxySettings &proxySettings=ProxySettings(), LogLevel aLogLevel=LOG_Initial) const
 Creates a License object using the given LicenseData.
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.
CategoriesInfo getCategoriesInfo (DCA_CATEGORIES_INFO_TYPE categoryType) const
 Returns the DCA internal categories, groups and locales.
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().
FunctionResult schedule (ScheduleEventSubscriberIntf *pScheduleEventSubscriber=NULL) const
 Invokes scheduled tasks, e.g. Database updates and processes that can take a long time.

Static Public Member Functions

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

Member Function Documentation

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] initData Must 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
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] newProxySettings Will 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.
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] licData A LicenseData object, initialized with valid license data.
[in] proxySettings If provided uses the proxySettings for all License requests (HTTPS-connections)
[in] aLogLevel If 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
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] aLicense A License correctly set up by a previous call to createLicense() function
[in] dbcData A DbConnectionData object, correctly set up depending on the type of DbConnection to create
[in] proxySettings If provided uses the proxySettings for remote database requests (HTTP-connections)
[in] aLogLevel If 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
CategoriesInfo dca::DcaInstance::getCategoriesInfo ( DCA_CATEGORIES_INFO_TYPE  categoryType  )  const

Returns the DCA internal categories, groups and locales.

Parameters:
[in] categoryType Can 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
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] signal This 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 
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] pScheduleEventSubscriber An 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 on 26 Sep 2016 for dca_interface by  doxygen 1.6.1