Usage

Quantum Origin provides a C SDK which enables users to integrate Quantum Origin directly into their own applications.

Overview

The process of integrating Quantum Origin into your application using the C SDK is summarized as follows:

  1. Installation:

Please see Installation section.

  1. Build system:

    Configure your build system such that your compiler can locate the subdirectory containing the Quantum Origin SDK header files, and your linker can find the Quantum Origin SDK library/libraries, static or dynamic as required. A short script named envars.bat (Windows) or envvars.sh (Linux) is created by the installer and placed in the sample_code folder(s) to assist with setting of build-time and run-time environment variables.

  2. Declaration:

    In your code, include the header file: quantum_origin/quantum_origin_sdk_c.h:

    #include <quantum_origin/quantum_origin_sdk_c.h>

  1. Configuration Options:

    Each instance of Quantum Origin SDK requires various configuration parameters depending on the specific application and environment.

    The SDK supports two approaches:

    1. SetOptions: The runtime parameters are supplied programmatically by the application using calls to the various qosdk_setopt_xxx functions and the relevant optionIDs.

    2. ConfigFile: The runtime parameters are supplied in a YAML configuration file stored on disk.

    In either case, the configuration items themselves are similar. Please refer to the Configuration section for information on each of the configuration options.

  2. Logging:

    Quantum Origin SDK includes a logging sub-system which allows an application to process or emit API log entries to a data store of choice. However, at this time, this does not affect the emitting or destination of log entries emitted from the underlying generator threads.

    The logging sub-system is optional and can be configured to log to a file, syslog, etc.. The logging level can also be set to control the verbosity of the log entries. These options can be set programmatically or via a configuration file. Quantum Origin SDK also supported installation of a custom logging callback function which can be used to have more control over how log entries are processed, or even integrated to an existing logging sub-system.

    Please see the Logging Configuration section for details.

  1. Configuration and Instantiation:

    1. SetOptions Approach:

      1. Configuration:

      An Options structure needs to be created (qosdk_setopt_init) and populated (qosdk_setopt_int, qosdk_setopt_str, qosdk_setopt_bytes) with the appropriate OptionID (tQOSDK_OPTID) and value.

      Each option is set using the appropriate setopt_xxx call, depending on the _type_ of the associated value.

      For example: setting the size of the internal cache requires a numeric value, so is set with a call of the form

      erc = qosdk_setopt_int(pConfigCtx, QOSDK_OPT_CACHE_SIZE, 256);

      Calling sequence (pseudo code)…

      ...
qosdk_setopt_init();
qosdk_setopt_int  (..., QOSDK_OPT_XXX, nValue );
qosdk_setopt_str  (..., QOSDK_OPT_YYY, szValue );
qosdk_setopt_bytes(..., QOSDK_OPT_ZZZ, pvalue, cbValue );
...

qosdk_init_from_config_struct();
qosdk_setopt_cleanup();
...

      1. Instantiation:

      Construct and configure a Quantum Origin SDK object using a call to qosdk_init_from_config_struct().

      The return value/context is passed as the 1st parameter to subsequent SDK calls, most notably, the generation of randomness.

      Once the Quantum Origin SDK object is successfully created, the Options structure should be released with a call to qosdk_setopt_cleanup().

      The context pointer will now be invalid and should be zeroised.

      See the Sample Code in the 6.1 SetOptions Approach section.

    2. ConfigFile Approach:

      1. Configuration:

      Create a YAML file containing the required settings and parameters. Construct and configure a Quantum Origin SDK object using qosdk_init_from_config_file().

      1. Instantiation:

      Construct and configure a Quantum Origin SDK object using qosdk_init_from_config_file(). The return value/context will be used in most calls to the SDK, including the generation of randomness.

      See the Sample Code in the 6.2 ConfigFile Approach section.

  2. Generation of randomness:

    When randomness is needed, simply call the qosdk_get_randomness() function.

    For example, to generate 32 bytes of randomness, the call would be:

    tQOSDK_RESULT erc;
unsigned char resultBuffer[32];
size_t bytesRequested = sizeof(resultBuffer);
size_t bytesSupplied = 0;

// Get randomness
erc = qosdk_get_randomness(pQuantumOrigin, resultBuffer, bytesRequested, &bytesSupplied);

    where pQuantumOrigin is a Quantum Origin instance i.e. the context pointer returned from the qosdk_init_from_config_struct() or qosdk_init_from_config_file() calls.

    This function will fill the provided buffer with the requested number of bytes, and return tQO_ERRCODE_SUCCESS if successful, otherwise an error code indicating the cause of the failure.

    This may be called any number of times using the single Quantum Origin instance/context.

  3. Destruction and Cleanup:

    When the Quantum Origin SDK object is no longer required, the application must call qosdk_destroy in order to free up resources used at construction time and at runtime.

    The instance pointer will now be invalid and should be zeroised.