Initialization of 3rd party libraries

Overview

The SCA is designed as an API that is used within a client application. As such, process-wide initialization of 3rd party libraries cannot be performed inside the SCA, as we don't know whether we are the exclusive user of these libraries. A client application must therefore assume the responsibility to perform the relevant initialization and deinitialization.

To make the init/deinit integration of the libraries used in the SCA easy for a client, we provide as part of the API source code snippets with functions that perform the required operations.

A client program can simply call these functions, and so does not need to deal directly with the libaries.

If a client already uses the libraries, it can use its current init/deinit functionality as is without any need for modification.

(If you did not installed the required 3rd party libraries read first chapter: Requirements for using the XFE SDK)

libcurl

The SCA uses libcurl internally. Before using, an initialization function must be called to set up global variables, and after the last usage a deinitialization function must be called to perform a cleanup.

As we cannot know whether a client is also using the libcurl library, we do not call these init/deinit function pairs inside of the SCA.

To provide an easy way to set and unset the library use the provided implementations of the SCA. Unlike other packages of the dca_base we did not add the header file of those functions to the package header file, though you must add it by yourself.

Using a CA certificate bundle

libcurl requires a CA certificate bundle for SSL certificate verification.

On most Linux distributions, libcurl uses /etc/ssl/certs/ and /etc/ssl/certs/ca-bundle.crt respectively (/usr/share/curl/curl-ca-bundle.crt for libcurl versions older than 7.18.0).

On Windows, the environment variable CURL_CA_BUNDLE must be set to the CA bundle's path (provided that libcurl was compiled with -DCURL_WANTS_CA_BUNDLE_ENV).

See also

Section Creating a CA certificate bundle (Windows)

OpenSSL

The SCA uses OpenSSL to request license and update information from our license and content servers.

When this library is used in a multi-threaded environment a callback must be set up. Whenever an application exits, the callback should be unset.

As we cannot know when a client application is about to exit, we cannot set or unset the callbacks from inside the SCA.

To provide an easy way to set and unset the library use the provided implementation in the SCA.

Unlike other packages of the dca_base we did not add the header file of those functions to the package header file, though you must add it by yourself.

Sample: 3rd Party Libraries Initilization

The initialization functions InitCUrl() and SetOpenSslCallbacks() should be called before accessing any SCA function:

#include <dca/dca_callbacks.h>
 
main()
{
        ...
        dca::InitCUrl();
        dca::SetOpenSslCallbacks();
        {
                // scope that ensures myDca is out of scope before calling the
                // DeinitCUrl(), UnsetOpenSslCallback() functions.
                ...
                DcaInstance myDca = DcaInstance::create( ... )
        }
        dca::UnsetOpenSslCallbacks();
        dca::DeinitCUrl();
}

Do not call any SCA function or any libcurl related function after calling the DeinitCUrl() function.

Do not call any SCA function or any OpenSSL related function after calling UnsetOpenSslCallbacks().

Samples

For a detailed description of the internal 3rd party libraries initialization possibilities see also:

Example implementation of libCUrl initializations and OpenSSL callbacks for Linux.
Example implementation of libCUrl initializations and OpenSSL callbacks for Windows.