customdb_samples: customdbsample_extended


Introduction

Uses a Custom Database and the URL Classification functionality to classify a URL.

If the Custom Database matched for the given URL this result is used, otherwise the result from the local database's is used.

This sample also shows how to implement the schedule and performUpdate calls using threads, and how to handle errors in those calls.

Syntax:

customdbsample_extended <dca-redist-folder> <ticket> <product> 
        <url-list-file> <custom-db-folder>
url-list-file
A file that includes URLs (one per line) that are used to URL classification
custom-db-folder
The folder where the newly created database file will be saved in.
See also:
dca::UrlCustomDbModule
Custom Categories
customdb_samples: createdbsample
customdb_samples: customdbsample
url_samples: urldbsample_remote
url_samples: urldbsample_extended
Package: Custom Database Module Toolbox
Samples Main Documentation: Samples

Files

file  customdb_samples/customdbsample_extended/main.cpp
 

Extended Custom Database sample program.


file  customdb_samples/customdbsample_extended/mythreads.h
 

Header file for functions related to start and stop the update and schedule threads.


file  customdb_samples/customdbsample_extended/perform_update_thread.h
 

Header file for the update thread.


file  customdb_samples/customdbsample_extended/schedule_thread.h
 

Header file for the schedule thread.


Defines

#define DCA_BINDIR   "bin/linux"
 DCA subdirectory of the DCA binaries.
#define DCA_INITDIR   "init"
 DCA subdirectory of the DCA initialization data.
#define DCA_LOGDIR   "./logs"
 Relative directory for logfile(s).

Functions

static void SetupInitData (const std::string &redist_folder, InitData &initData)
 Sets up the given initData by substituting the given redist_folder with DCA subdirectories.
static void SetupLicense (const std::string &ticket, const std::string &product, LicenseData &licenseData)
 Sets up the given licenseData by copying the given ticket and product strings.
static void SetupConnectionData (DbConnectionData &cData)
 Sets up the given cData to use a local URL database.
static void SetupCustomConnectionData (const std::string &customdb_folder, DbConnectionData &cData)
 Sets up the given cData to use a Custom Database.
static void PrintResults (const CategoriesInfo &catinfos, const UrlClassificationResults &cats)
 Prints out the classification results and uses the categories info for textual representation of matched categories.
static void PrintToolHeader ()
 Prints out the name and the version of this sample.
static void PrintUsage (const char *name)
 Prints out the syntax of the sample.
static void LoadUrlFile (const std::string &fileName, std::vector< std::string > &urlList)
 Loads given fileName and puts each line to given urlList (by deleting trailing CRLFs).
void TestUrlClassification (const std::string &aUrlListFile, const DcaInstance &myDca, const UrlDbClassifier &myUrlDbClassifier, const UrlDbClassifier &myUrlCustomDbClassifier, const CategoriesInfo &myCategoriesInfo)
 Performs URL database classification with some URLs found in a given text file.
int main (int argc, char *argv[])
 The main routine.
void StartupThreads (const dca::DcaInstance &aDcaInstance, const dca::UpdateModule &aUpdateModule, volatile bool *schedulerErrorSignal, volatile bool *performUpdateErrorSignal)
 Starts up the update and schedule threads and supplies the given DcaInstance and UpdateModule.
void ShutdownThreads ()
 Shuts down the previously started update and schedule threads.
void mySleep (unsigned int ms)
 sleeps the given interval (in milliseconds)
void createPerformUpdateThread (const dca::UpdateModule &aUpdateModule, volatile bool *errorSignal)
 Starts up the update thread and supply the given UpdateModule.
void shutdownPerformUpdateThread ()
 Shuts down the previously started update thread.
void createScheduleThread (const dca::DcaInstance &aDcaInstance, volatile bool *errorSignal)
 Starts up the schedule thread and supplies the given DcaInstance.
void shutdownScheduleThread ()
 Shuts down the previously started schedule thread.

Variables

const std::string S_UsageString
 Usage string, displayed if a parameter was missing.

Function Documentation

static void SetupInitData ( const std::string &  redist_folder,
InitData initData 
) [static]

Sets up the given initData by substituting the given redist_folder with DCA subdirectories.

Parameters:
[in] redist_folder This is the folder where the DCA has been installed to (assuming trailing filslash)
[out] initData The InitData structure to set up
Note:
Only DCA_BINDIR differs between Windows and Linux
The directory ./logs is used for the logfile(s)

Definition at line 107 of file customdb_samples/customdbsample_extended/main.cpp.

static void SetupLicense ( const std::string &  ticket,
const std::string &  product,
LicenseData licenseData 
) [static]

Sets up the given licenseData by copying the given ticket and product strings.

Parameters:
[in] ticket This is the ticket data as provided with your DCA license
[in] product This is the product shortcut e.g. DC oder MS etc
[out] licenseData The LicenseData structure to set up

Definition at line 121 of file customdb_samples/customdbsample_extended/main.cpp.

static void SetupConnectionData ( DbConnectionData cData  )  [static]

Sets up the given cData to use a local URL database.

Parameters:
[out] cData The DbConnectionData structure to set up
Note:
Assuming the DCA had already downloaded an initial URL database. If not, set useLocalDatabase to false.

Definition at line 135 of file customdb_samples/customdbsample_extended/main.cpp.

static void SetupCustomConnectionData ( const std::string &  customdb_folder,
DbConnectionData cData 
) [static]

Sets up the given cData to use a Custom Database.

Parameters:
[in] customdb_folder The folder where the Custom Database file is stored in
[out] cData The DbConnectionData structure to set up
Note:
Assuming there is already an existing Custom Database located in given folder.

Definition at line 148 of file customdb_samples/customdbsample_extended/main.cpp.

static void PrintResults ( const CategoriesInfo catinfos,
const UrlClassificationResults cats 
) [static]

Prints out the classification results and uses the categories info for textual representation of matched categories.

Parameters:
[in] catinfos The CategoriesInfo class associated with the given URL database
[in] cats The results of an URL classification

Definition at line 161 of file customdb_samples/customdbsample_extended/main.cpp.

static void PrintUsage ( const char *  name  )  [static]

Prints out the syntax of the sample.

Parameters:
[in] name The name of the executable

Definition at line 199 of file customdb_samples/customdbsample_extended/main.cpp.

static void LoadUrlFile ( const std::string &  fileName,
std::vector< std::string > &  urlList 
) [static]

Loads given fileName and puts each line to given urlList (by deleting trailing CRLFs).

Parameters:
[in] fileName The file that includes URLs
[out] urlList The list to be filled with the URLs found in fileName

Definition at line 210 of file customdb_samples/customdbsample_extended/main.cpp.

void TestUrlClassification ( const std::string &  aUrlListFile,
const DcaInstance myDca,
const UrlDbClassifier myUrlDbClassifier,
const UrlDbClassifier myUrlCustomDbClassifier,
const CategoriesInfo myCategoriesInfo 
)

Performs URL database classification with some URLs found in a given text file.

The given aUrlListFile contains an URL per line. The URLs will be added to a vector and for each file a URL database classification is invoked. The results are printed out by using the PrintResults() function.

Parameters:
[in] aUrlListFile The file that includes URLs
[in] myDca A valid set up DCA Instance
[in] myUrlDbClassifier A valid set up UrlDbClassifier
[in] myUrlCustomDbClassifier A valid set up UrlDbClassifier
[in] myCategoriesInfo A valid set up CategoriesInfo
Note:
The results of a classification returns either "URL is unknown", "not categorized" or a "set of matched categories".
When creating a multi-threaded application you can include something similar to this function into each thread's worker function.

Definition at line 244 of file customdb_samples/customdbsample_extended/main.cpp.

int main ( int  argc,
char *  argv[] 
)

The main routine.

Parameters:
[in] argc The count of arguments provided
[in] argv An array of provided arguments
Returns:
5 on usage error, 10 on exception and internal error and 0 on success
Note:
Syntax is: customdbsample_extended <redist-folder> <ticket> <product> <url-list-file> <custom-db-folder>

Definition at line 358 of file customdb_samples/customdbsample_extended/main.cpp.

void StartupThreads ( const dca::DcaInstance aDcaInstance,
const dca::UpdateModule aUpdateModule,
volatile bool *  schedulerErrorSignal,
volatile bool *  performUpdateErrorSignal 
)

Starts up the update and schedule threads and supplies the given DcaInstance and UpdateModule.

Parameters:
[in] aDcaInstance An initialized DcaInstance
[in] aUpdateModule An initialized UpdateModule
[out] schedulerErrorSignal If an UpdateModule::performUpdate() call encounters an error this bool will be set to true, and the main application will shut down.
[out] performUpdateErrorSignal If an DcaInstance::schedule() call encounters an error this bool will be set to true, and the main application will shut down.

Starts up two threads

  • an update thread that calls the aUpdateModule::performUpdate() method in a loop and
  • a schedule thread that calls the aDcaInstance::schedule() method in a loop.

The called functions will check engine and content updates automatically and install them in the provided dca/init directory.

They will be stopped by a call to ShutdownThreads()

See also:
createPerformUpdateThread, createScheduleThread, ShutdownThreads

Definition at line 13 of file customdb_samples/customdbsample_extended/mythreads.cpp.

void ShutdownThreads (  ) 

Shuts down the previously started update and schedule threads.

Shutting down will stop the threads safely.

If an update is already in progress the function will return as soon as possible but will not force-terminate any thread.

Note:
To force stop any running update processes immediately a call to DcaInstance::signal() should be invoked.
See also:
shutdownScheduleThread, shutdownPerformUpdateThread, StartupThreads

Definition at line 20 of file customdb_samples/customdbsample_extended/mythreads.cpp.

void createPerformUpdateThread ( const dca::UpdateModule aUpdateModule,
volatile bool *  errorSignal 
)

Starts up the update thread and supply the given UpdateModule.

Parameters:
[in] aUpdateModule An initialized UpdateModule
[out] errorSignal Error signal that is set to true, if an error occured in the call to performUpdate()

Starts up an update thread that calls the aUpdateModule::performUpdate() method in a loop.

The called function will check engine and content updates automatically and install them in the provided dca/init directory.

It can be stopped by a call to shutdownPerformUpdateThread

Note:
There are separate implementations for Windows and Linux distributions.
See also:
shutdownPerformUpdateThread

Definition at line 63 of file customdb_samples/customdbsample_extended/linux/perform_update_thread.cpp.

void shutdownPerformUpdateThread (  ) 

Shuts down the previously started update thread.

Shutting down will stop the thread safely.

If an update is already in progress the function will return as soon as possible but will not force-terminate the thread.

Note:
To force any running update processes to stop immediately a call to DcaInstance::signal() should be invoked.
There are separate implementations for Windows and Linux distributions.
See also:
createPerformUpdateThread

Definition at line 71 of file customdb_samples/customdbsample_extended/linux/perform_update_thread.cpp.

void createScheduleThread ( const dca::DcaInstance aDcaInstance,
volatile bool *  errorSignal 
)

Starts up the schedule thread and supplies the given DcaInstance.

Parameters:
[in] aDcaInstance An initialized DcaInstance
[out] errorSignal Error signal that is set to true if an error occured in the call to schedule()

Start up a schedule thread that calls the aDcaInstance::schedule() method in a loop.

It can be stopped by a call to ShutdownScheduleThread()

Note:
There are separate implementations for Windows and Linux distributions.
See also:
shutdownScheduleThread

Definition at line 58 of file customdb_samples/customdbsample_extended/linux/schedule_thread.cpp.

void shutdownScheduleThread (  ) 

Shuts down the previously started schedule thread.

Shutting down will stop the thread safely.

If an update is already in progress the function will return as soon as possible but will not force-terminate any thread.

Note:
To force any running update processes to stop immediately a call to DcaInstance::signal() should be invoked.
There are separate implementations for Windows and Linux distributions.
See also:
createScheduleThread

Definition at line 66 of file customdb_samples/customdbsample_extended/linux/schedule_thread.cpp.


Variable Documentation

const std::string S_UsageString
Initial value:
        " <redist-folder> <ticket> <product> <url-list-file> <custom-db-folder>\n"
        "  redist-folder - the folder where the DCA is installed to\n"
        "  ticket - a valid ticket\n"
        "  product - the product associated with your ticket\n"
        "  url-list-file - file that includes the URLs to classify\n"
        "  custom-db-folder - folder where the Custom Database is located\n\n"

Usage string, displayed if a parameter was missing.

Definition at line 66 of file customdb_samples/customdbsample_extended/main.cpp.


Generated on 26 Sep 2016 for dca_interface by  doxygen 1.6.1