dca_interface  6.3.4
base_classes.h
Go to the documentation of this file.
1 /* IBM Source Code */
2 /* (C) Copyright IBM Corp. 2009, 2012 */
3 /* Licensed Materials - Property of IBM */
4 /* US Government Users Restricted Rights - Use duplication or disclosure restricted by GSA Schedule Contract with IBM Corp. */
5 
6 #ifndef BASE_CLASSES_H
7 #define BASE_CLASSES_H
8 
18 #include <string>
19 #include <map>
20 
21 namespace dca {
22 
35  extern const int ERR_NOT_INITIALIZED;
40  extern const int ERR_CREATION;
45  extern const int ERR_PARAMS;
51  extern const int ERR_CONNECTION;
57  extern const int ERR_CONNECTION_PROXY;
63  extern const int ERR_CONNECTION_TIMEOUT;
69  extern const int ERR_MEMORY_SHORTAGE;
75  extern const int ERR_SIG_ABORT_DETECTED;
80  extern const int ERR_NOT_LICENSED;
86  extern const int ERR_UNEXPECTED;
92  extern const int ERR_WRAPPER_UNEXPECTED;
93 
135  class ExDca;
136  class funcresult_p;
137 
148  {
149  public:
151  FunctionResult();
152  FunctionResult( const ExDca& aExDca );
153  FunctionResult( const FunctionResult& rhi );
154  FunctionResult& operator = ( const FunctionResult& rhi );
155  virtual ~FunctionResult();
157 
163 
167  operator bool() const;
168 
174  std::string getDescription() const;
175 
183 
185  PRIVATE_PTR funcresult_p *_p;
186  };
187 
189  class exdca_p;
191  class FunctionResult;
192 
193 
212  enum LogLevel {
213  LOG_Initial = -1,
215  LOG_Error = 1,
218  LOG_Info = 4,
220  LOG_Debug = 6
225  };
226 
236  class ExDca
237  {
238  public:
240  ExDca();
241  ExDca( const ExDca& rhi );
242  ExDca& operator = ( const ExDca& rhi );
243  virtual ~ExDca() throw();
245 
248  std::string getDescription() const throw();
249 
254 
256  PRIVATE_PTR exdca_p *_p;
257  };
258 
264  struct InitData {
265  std::string binDir;
266  std::string initDir;
267  std::string logDir;
268  };
269 
275  struct ProxySettings {
277  ProxySettings();
279 
280  std::string user;
281  std::string password;
282  std::string proxyServer;
283  unsigned int proxyPort;
284  };
285 
286  struct LicenseData;
287  class License;
288  struct DbConnectionData;
289  class DbConnection;
290  class UpdateModule;
291  class CategoriesInfo;
293  class dcainst_p;
294 
315  {
316  public:
317 
342  static DcaInstance create( const InitData& initData );
343 
345  DcaInstance();
346  DcaInstance( const DcaInstance& aDcaInstance );
347  DcaInstance& operator = ( const DcaInstance& aDcaInstance );
348  virtual ~DcaInstance();
350 
370 
385  License createLicense( const LicenseData& licData, const ProxySettings& proxySettings = ProxySettings(), LogLevel aLogLevel = LOG_Initial ) const;
386 
401  DbConnection createDbConnection( const License& aLicense, const DbConnectionData& dbcData, const ProxySettings& proxySettings = ProxySettings(), LogLevel aLogLevel = LOG_Initial ) const;
402 
421 
422 
427 
445  bool signal( unsigned int signal ) const;
446 
475  FunctionResult schedule( ScheduleEventSubscriberIntf* pScheduleEventSubscriber = NULL ) const;
476 
478  PRIVATE_PTR dcainst_p *_p;
479  };
480 
495  {
504  };
505 
511  {
512  SMI_UrlDb = 0,
518  };
519 
527  public:
528  virtual ~ScheduleEventSubscriberIntf() {}
529 
537  virtual void onEvent( ScheduleActionType actionType, ScheduleModuleId moduleId, const std::string& version, const std::string& text ) = 0;
538  };
539 
546  struct LicenseData
547  {
548  std::string ticket;
549  std::string product;
550  };
551 
552  class license_p;
553 
559  class License
560  {
561  public:
563  License();
564  License( const License& aLicense );
565  License& operator = ( const License& aLicense );
566  virtual ~License();
568 
589  bool isLicensed( DCA_MODULE_ID_TYPE id = 0, bool force = false ) const;
590 
595  int getMaxSessions() const;
596 
601  int getMaxUsers() const;
602 
611 
617  std::string getTicket() const;
618 
624  std::string getSession() const;
625 
632  bool getCustomData( std::string& customData ) const;
633 
639  time_t getExpirationDate() const;
640 
654  std::string getLastMessage() const;
655 
657  PRIVATE_PTR license_p *_p;
658  };
659 
679  unsigned int dbUpdateIntervalMinutes;
684  };
685 
719 
724  unsigned int cacheMaxEntries;
744  unsigned int dbUpdateIntervalMinutes;
754  std::string configDir;
763  };
764 
778  std::string encryptionData;
779  unsigned int encryptionKey;
780  };
781 
786  extern const DbType DBT_Url;
791  extern const DbType DBT_Mail;
796  extern const DbType DBT_Custom;
797 
819 
825  };
826 
838  unsigned int majorVersion;
839  unsigned int minorVersion;
840  std::string versionString;
842  std::string creationDateUTC;
845  };
846 
847  class dbconnection_p;
848 
859  {
860  public:
862  DbConnection();
863  DbConnection( const DbConnection& aDbConnection );
864  DbConnection& operator = ( const DbConnection& aDbConnection );
865  virtual ~DbConnection();
867 
885  std::string getDatabaseVersion() const;
886 
895 
904 
906  PRIVATE_PTR dbconnection_p *_p;
907  };
908 
909  class updatemodule_p;
910  class UpdateResults;
911 
917  {
918  public:
921 
930  static UpdateModule create( const DcaInstance& aDcaInstance, const License& aLicense,
931  const ProxySettings& proxySettings = ProxySettings() );
932 
934  UpdateModule();
935  UpdateModule( const UpdateModule& );
936  UpdateModule& operator = ( const UpdateModule& );
937  virtual ~UpdateModule();
939 
964  FunctionResult performUpdate( bool force, UpdateResults& results ) const;
973  bool cancelUpdate() const;
974 
975 
984 
986  PRIVATE_PTR updatemodule_p *_p;
987  };
988 
989  class UpdateResult;
990  class updateresults_p;
991 
998  {
999  public:
1001  UpdateResults();
1002  UpdateResults( const UpdateResults& );
1003  UpdateResults& operator = ( const UpdateResults& );
1004  virtual ~UpdateResults();
1006 
1018  UpdateResult operator [] ( DCA_INDEX_TYPE index ) const;
1021 
1023  bool restartRequired() const;
1024 
1026  PRIVATE_PTR updateresults_p *_p;
1027  };
1028 
1029  class updateresult_p;
1030  class UpdateResultDetail;
1031 
1037  {
1038  public:
1040  UpdateResult();
1041  UpdateResult( const UpdateResult& );
1042  UpdateResult& operator = ( const UpdateResult& );
1043  virtual ~UpdateResult();
1045 
1057  UpdateResultDetail operator [] ( DCA_INDEX_TYPE index ) const;
1060 
1062  std::string name() const;
1063 
1067  bool contentUpdated() const;
1069  bool engineUpdated() const;
1070 
1072  PRIVATE_PTR updateresult_p *_p;
1073  };
1074 
1075  class updateresult_detail_p;
1076 
1082  {
1083  public:
1087  UpdateResultDetail& operator = ( const UpdateResultDetail& );
1088  virtual ~UpdateResultDetail();
1090 
1092  std::string component() const;
1094  std::string oldVersion() const;
1096  std::string newVersion() const;
1098  bool available() const;
1100  bool downloaded() const;
1102  bool installed() const;
1104  int returnCode() const;
1105 
1107  PRIVATE_PTR updateresult_detail_p *_p;
1108  };
1109 
1111  // Error codes of this package
1113 
1117  extern const int ERR_INVALID_DATABASE;
1118 
1123  extern const int ERR_INVALID_FOLDER;
1124 
1129  extern const int ERR_INVALID_XML_FILES;
1130 
1135  extern const int ERR_DB_UPDATE_ABORTED;
1136 
1141  extern const int ERR_DB_DOWNLOAD_ABORTED;
1142 
1147  extern const int ERR_DATABASE_ALREADY_EXISTING;
1148 
1153  extern const int ERR_URL_INVALID;
1154 
1159  extern const int ERR_URL_UNSUPPORTED_PROTOCOL;
1160 
1165  extern const int ERR_CUSTOMDB_INVALID_CATEGORIES;
1166 
1171  extern const int DCA_SUCCESS;
1172 
1177  extern const unsigned int DCA_SIG_ABORT;
1178 
1184  extern const int DCA_UPDATE_DOWNLOAD_SCHEDULED;
1185 }
1186 
1187 #endif
std::string password
proxy password associated for the given username
Definition: base_classes.h:281
@ SMI_MailDb
ID for a mail database.
Definition: base_classes.h:513
int DCA_MODULE_ID_TYPE
Type for module ids.
Definition: base_types.h:21
Is used to create a License object. A license first must be created with DcaInstance::createLicense t...
Definition: base_classes.h:547
const int ERR_CONNECTION_PROXY
This error may occur whenever a DCA function or class attempts to connect to a remote resource via a ...
LogLevel setLogLevel(LogLevel newLevel)
Sets the logging level for the given class instance. The old value will be returned.
Exception class used in the DCA.
Definition: base_classes.h:237
const DbType DBT_Mail
Used for DbConnection classes for ZLA classification.
@ SMI_UrlDb
ID for a URL database.
Definition: base_classes.h:512
int DbType
Type for DbConnection classes.
Definition: base_types.h:78
@ LOG_Warning
Warnings will be logged.
Definition: base_classes.h:216
bool cancelUpdate() const
Cancels a currently running update process. If there is currently no update running,...
@ SMI_IprDb
ID for a IPR database.
Definition: base_classes.h:516
const int ERR_PARAMS
One or more parameter values is invalid, or a combination of parameter values is invalid.
LogLevel setLogLevel(LogLevel newLevel)
Sets the logging level for the given class instance. The old value will be returned.
const int ERR_CUSTOMDB_INVALID_CATEGORIES
Error code: The given categories are invalid.
@ SMI_MalwareDb
ID for a Malware database.
Definition: base_classes.h:517
std::string oldVersion() const
Returns the version active (installed) before the update was invoked.
std::string initDir
the directory in which the DCA init files are stored
Definition: base_classes.h:266
FunctionResult schedule(ScheduleEventSubscriberIntf *pScheduleEventSubscriber=NULL) const
Invokes scheduled tasks, e.g. Database updates and processes that can take a long time.
bool signal(unsigned int signal) const
Cancels functions which could potentially take a long time to return, such as DcaInstance::schedule()...
const int ERR_CONNECTION
This error may occur whenever a DCA function or class attempts to connect to a local or remote resour...
const int ERR_MEMORY_SHORTAGE
This error is returned whenever it was not possible to allocate a required amount of memory....
static UpdateModule create(const DcaInstance &aDcaInstance, const License &aLicense, const ProxySettings &proxySettings=ProxySettings())
int getMaxSessions() const
Returns the maximum allowed sessions associated with your ticket/license.
VersionInfoResults getVersionInfo() const
Returns enumerable version information about all currently loaded modules.
time_t getExpirationDate() const
Returns the expiration date of the license in UTC.
std::string getDescription() const
Returns a description of the error.
bool getCustomData(std::string &customData) const
Returns CustomData as string if available. Whether custom data are available or not depends on your t...
UpdateResultDetail at(DCA_INDEX_TYPE index) const
Allows access to the details of the result.
std::string configDir
Specifies the complete folder path where the custom database is located, or the folder in which it sh...
Definition: base_classes.h:754
DbConnectionLocalData localData
Fill out this structure only if you are using a local (non-custom) database.
Definition: base_classes.h:822
bool downloaded() const
true if an update sucessfully downloaded for this component, false otherwise
const int ERR_DB_UPDATE_ABORTED
Error code: A (scheduled) database update was aborted unexpectly.
UpdateResult at(DCA_INDEX_TYPE index) const
Allows access to the result with given index.
int returnCode() const
The internal code of the update, this can be any internal error code, 0 in case of success or DCA_UPD...
CategoriesInfo getCategoriesInfo(DCA_CATEGORIES_INFO_TYPE categoryType) const
Returns the DCA internal categories, groups and locales.
DatabaseInformation getDatabaseInformation() const
Returns information about the underlying database.
Encapsulates the details of a result of an update process.
Contains information about underlying database.
Definition: base_classes.h:834
DbConnectionCustomData customData
Fill out this structure only if you are using a custom database.
Definition: base_classes.h:823
const int ERR_DATABASE_ALREADY_EXISTING
Error code: The specified database already exists.
DCA_RESULT_TYPE getReturnCode() const
Returns the last error code (if any).
unsigned int cacheEntryExpirationMinutes
The cache is also used to cache URL requests. This setting defines when an entry will be considered a...
Definition: base_classes.h:731
bool restartRequired() const
true if an update has been installed that requires a restart of the DCA, false otherwise.
std::string creationDateUTC
Definition: base_classes.h:842
The update module is used to download and install DCA content and engine updates.
Definition: base_classes.h:917
@ SAT_StopDbDownload
A complete database download has successfully finished.
Definition: base_classes.h:498
bool installed() const
true if an update sucessfully installed for this component, false otherwise
@ LOG_Initial
Initial internal log level, do not use.
Definition: base_classes.h:213
std::string binDir
the directory in which the DCA binary (*.dca) files are stored
Definition: base_classes.h:265
@ SMI_WacDb
ID for a WAC database.
Definition: base_classes.h:515
LogLevel setLogLevel(LogLevel newLevel)
Sets the logging level for the given class instance. The old value will be returned.
unsigned int encryptionKey
The encryption key to be used (provided with your license)
Definition: base_classes.h:779
Encapsulates the results of an update process.
Definition: base_classes.h:998
A container class that allows access to the contained Categories, Groups and Locales.
@ LOG_Notice
Write notices / important information to the log file.
Definition: base_classes.h:217
@ LOG_Critical
Critical events will be logged out.
Definition: base_classes.h:214
const unsigned int DCA_SIG_ABORT
Currently the only supported signal parameter for the DcaInstance::signal() function.
const int ERR_WRAPPER_UNEXPECTED
The DCA consists of a wrapper layer that makes function calls on the dynamically loaded shared object...
Stores the connection data for a database.
Definition: base_classes.h:815
ScheduleModuleId
This defines the module id of a schedule event.
Definition: base_classes.h:511
ScheduleActionType
This defines the action type of a schedule event.
Definition: base_classes.h:495
const int DCA_UPDATE_DOWNLOAD_SCHEDULED
Internal DCA status code to indicate that a potentially time consuming download has been scheduled....
time_t dbUpdateStartLocalTime
The start time for the database merge process. If left at 0, the current time plus a small random off...
Definition: base_classes.h:749
const int ERR_CONNECTION_TIMEOUT
This error may occur whenever a DCA function or class attempts to connect to a remote resource....
unsigned int minorVersion
Definition: base_classes.h:839
int getMaxUsers() const
Returns the maximum allowed users associated with your ticket/license.
@ SAT_ProgressDbDownload
Complete database download progress information.
Definition: base_classes.h:497
Class to store the Database connection data for a custom database.
Definition: base_classes.h:715
FunctionResult setDefaultProxySettings(const ProxySettings &newProxySettings)
Sets default proxy settings for all locations where proxy settings are used.
@ SAT_StopDbMerge
A database merge process has successfully finished.
Definition: base_classes.h:501
Database connection class for a local or remote database.
Definition: base_classes.h:859
const int ERR_DB_DOWNLOAD_ABORTED
Error code: A download of a database update was aborted unexpectly.
unsigned int dbUpdateIntervalMinutes
This is the interval of the database merge process, specified in minutes. Minimum is one minute,...
Definition: base_classes.h:744
bool contentUpdated() const
If true the update(s) include a content update.
const int ERR_NOT_LICENSED
This code is returned if the specified license data is invalid, or the license has expired.
@ LOG_Extensive
Use extensive logging, this may greatly increase the size of the log file.
Definition: base_classes.h:219
@ LOG_Error
Errors will be logged out.
Definition: base_classes.h:215
@ SAT_StartDbDownload
A complete database download has started.
Definition: base_classes.h:496
unsigned int cacheMaxEntries
This is the maximum number of entries the cache can be filled up with (by using the maintenance inter...
Definition: base_classes.h:724
DCA_RESULT_TYPE getReturnCode() const
Gets the code of the error.
std::string newVersion() const
Returns the version currently active (installed).
bool available() const
true if an update was available for this component, false otherwise
const int ERR_SIG_ABORT_DETECTED
This code is returned when you use the dca::DcaInstance::signal() call and a task is terminated as a ...
@ SAT_ErrorDbMerge
An error occured during the database merge process.
Definition: base_classes.h:502
time_t dbUpdateStartLocalTime
Definition: base_classes.h:682
Class that contains all version information of all initialized DCA modules.
const int ERR_URL_INVALID
Error code: The URL is invalid.
unsigned int updateFileWriteMaxEntries
The maximum number of entries. If exceeded, the database will be saved to an update file....
Definition: base_classes.h:762
Encapsulates one of the results of an update process.
@ SAT_UserCancel
The user has cancelled the operation.
Definition: base_classes.h:503
LogLevel
This enum is used in all setLogLevel() functions to change the verbosity level of the classes.
Definition: base_classes.h:212
Stores the remote server data for the connection to a remote database.
Definition: base_classes.h:774
Use a License to initialize a classification package or a toolbox package.
Definition: base_classes.h:560
unsigned int dbUpdateIntervalMinutes
Definition: base_classes.h:679
const DbType DBT_Custom
Used for DbConnection classes of custom databases.
const int ERR_INVALID_FOLDER
Error code: One (or more) of the specified folders were invalid (types or inaccessable)
FunctionResult performUpdate(bool force, UpdateResults &results) const
Performs an update for all licensed and initialized DCA modules and classifiers.
If you are using one or more proxy servers set up this structure and use it for e....
Definition: base_classes.h:275
bool isLicensed(DCA_MODULE_ID_TYPE id=0, bool force=false) const
Checks whether the given License is valid for the given module id.
std::string ticket
The ticket as provided in the license.
Definition: base_classes.h:548
std::string versionString
Definition: base_classes.h:840
bool useLocalDatabase
Set to true to connect to a local or custom database, set to false to use a remote database.
Definition: base_classes.h:821
unsigned int majorVersion
Definition: base_classes.h:838
Encapsulates the init and deinit of the DCA API.
Definition: base_classes.h:315
unsigned int proxyPort
the proxy server port to be used
Definition: base_classes.h:283
std::string product
The product code used with the license.
Definition: base_classes.h:549
static DCA_MODULE_ID_TYPE ID
This is the module id of the update module.
Definition: base_classes.h:920
@ LOG_Info
Write less important information to the log file.
Definition: base_classes.h:218
const DbType DBT_Url
Used for DbConnection classes for URL classification.
@ LOG_Debug
Definition: base_classes.h:220
const int ERR_INVALID_XML_FILES
Error code: The specified XML files are missing or corrupt.
std::string logDir
the directory in which the DCA log file should be created
Definition: base_classes.h:267
const int ERR_URL_UNSUPPORTED_PROTOCOL
Error code: The protocol of the URL is unsupported.
std::string getLastMessage() const
Returns the last message received from our license server or if none available the last available mes...
size_t DCA_INDEX_TYPE
Type for index access (used for arrays and collections).
Definition: base_types.h:66
const int DCA_SUCCESS
A return code to indicate a successful function call.
@ SAT_ErrorDbDownload
An error occured during a complete db download.
Definition: base_classes.h:499
std::string user
proxy username
Definition: base_classes.h:280
DbType dbType
The type of the database.
Definition: base_classes.h:820
DCA_SIZE_TYPE size() const
Returns the number of available details (if any).
std::string getDescription() const
Returns the description for the error or warning.
size_t DCA_SIZE_TYPE
Type for size (used for size of array and collections).
Definition: base_types.h:72
const int ERR_UNEXPECTED
This error is returned if an unexpcted error occurs. This should never happen, but if it does occur,...
const int ERR_INVALID_DATABASE
Error code: An attempt to connect to a local or custom database was not successful.
Stores the connection data for a local database.
Definition: base_classes.h:675
unsigned int updateFileWriteIntervalMinutes
This is the interval (specified in minutes) in which the modifications made to the database are saved...
Definition: base_classes.h:738
bool engineUpdated() const
If true the update(s) include an engine update.
@ SMI_CustomDb
ID for a custom database database.
Definition: base_classes.h:514
DbConnectionRemoteServerData remoteServerData
If you are creating a remote database connection, this structure must be filled out with the encrypti...
Definition: base_classes.h:824
void setReturnCode(DCA_RESULT_TYPE value)
Sets the return code.
std::string getTicket() const
Returns the ticket of the license as string.
const int ERR_NOT_INITIALIZED
If you e.g. forget to initialize an instance before using a member function this error will be return...
#define PRIVATE_PTR
Type for private pointer implementations, for internal use only.
Definition: base_types.h:83
Standard function result.
Definition: base_classes.h:148
std::string getSession() const
Returns the session of the license as string.
virtual void onEvent(ScheduleActionType actionType, ScheduleModuleId moduleId, const std::string &version, const std::string &text)=0
Called by the schedule framework when a schedule event occurs.
std::string name() const
Returns the name of the DCA module that is related to current updates.
An interface for schedule event notifications. Derive a class from this interface and implement onEve...
Definition: base_classes.h:526
char * DCA_CATEGORIES_INFO_TYPE
Type for CategoryInfo objects.
Definition: base_types.h:26
int DCA_RESULT_TYPE
Type for return codes.
Definition: base_types.h:60
const int ERR_CREATION
An error occured when attempting too create a class or instance in the DCA API.
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.
This structure is used to initialize the DcaInstance.
Definition: base_classes.h:264
std::string proxyServer
the proxy server (IP address or the fully qualified domain name)
Definition: base_classes.h:282
std::string getDatabaseVersion() const
Returns the currently used database version.
static DcaInstance create(const InitData &initData)
Creates a DcaInstance, starts up the DCA API and initializes the required main module.
@ SAT_StartDbMerge
A database merge process has started.
Definition: base_classes.h:500
DCA_SIZE_TYPE size() const
Returns the number of results available .
std::string encryptionData
The encryption data to be used (provided with your license)
Definition: base_classes.h:778
License createLicense(const LicenseData &licData, const ProxySettings &proxySettings=ProxySettings(), LogLevel aLogLevel=LOG_Initial) const
Creates a License object using the given LicenseData.
DCA_MODULE_ID_TYPE id() const
Returns the module ID for which the updates have been installed.
std::string component() const
Returns the name of the component the detail applies to.