Initialization, Configuration and Memory Management

This category covers the initialization and cleanup, and provisions versions of the API and backward compatibility. When version 1.1 or 2.0 are introduced, the initialization can still be performed against 1.0 and the API will be then responsible the upgrade input / downgrade output payloads in order to maintain compatibility.

Configuration can be stored and retrieved in order to configure the API behaviors. Memory allocated when returning variable-length output parameters must be freed by the library itself, only one function to free the allocated memory is available to simplify the usage of the library.

Enumerations

enum HSDCVersion : WORD { HSDCVersionUnknown = 0, HSDCVersion_1_0 = 0x0100 }

Functions

HSDCError HSDCAPI HSDCStartup (WORD version, const char *jstr, const char *license)

The API must be initialized once per process. When the process does not need the API anymore, it can release resources by calling the HSDCCleanup function. Multiple sequences of startup and cleanup can be done in the process lifetime.

HSDCError HSDCAPI HSDCCleanup ()

This call cleans up resources (but not the dictionary strings) allocated during HSDCStartup and other API calls. No other calls should be made after this call, other than HSDCStartup. Any memory allocated by the API as returned parameters during previous call is released, and any registered callbacks are also unregistered.

HSDCError HSDCAPI HSDCGetVersion (WORD *pVersion)

Returns the API version.

HSDCError HSDCAPI HSDCFreeObject (void *pObj)

Frees memory allocated by the API that has been returned. The API tracks all memory allocations and releases forgotten allocations on HSDCCleanup. The caller is encouraged to process output parameters as soon as possible or make a copy then free output parameters as quickly as possible to avoid memory leaks.

HSDCError HSDCAPI HSDCGetConfiguration (char **pJstr)

Returns the JSON configuration of the API layer.

HSDCError HSDCAPI HSDCSetConfiguration (const char *jstr)

Sets the JSON configuration of the API layer.

HSDCError HSDCAPI HSDCSetLogging (const char *logSetup)

Updates the log settings of the HSDC Agent components.

HSDCError HSDCAPI HSDCGetLogging (char **logSettingsOut)

Returns all of the values for known HSDC components. Only found components and values that have registry entries are included. Entries not being found is not considered an error.

Enumeration Type Documentation

HSDCVersion

enum HSDCVersion : WORD

Enumerators

HSDCVersionUnknown

Unknown version, SDK is not yet initialized.

HSDCVersion_1_0

Version 1.0, current.

Function Documentation

HSDCStartup()

HSDCError HSDCAPI HSDCStartup ( WORD version, const char * jstr, const char * license )

The API must be initialized once per process. When the process does not need the API anymore, it can release resources by calling the HSDCCleanup function. Multiple sequences of startup and cleanup can be done in the process lifetime.

Parameters

version

The version of the client API. Must be set to HSDCVersion_1_0.

jstr

JSON payload containing the registry path under Local Machine and a flag to indicate if the strings dictionary must be initialized (it includes all strings available in RTNotify and DCExt programs). Below is the expected format with the default values. The caller can pass a nullptr value to keep the default values. Under the registry key, the usual Device Control logging settings can be configured (log to file, and so on). A unhandled exception handler is set to catch and dump unforeseen crashes for analysis, enabled by default if the minidump tag is not present.

Copy 
{
   "registry": "Software\\Lumension Security\\API",
   "strings" : true,
   "minidump":
   {
      "name": "hsdc",
      "type": "console"
   }
}

license

Integrator should provide the string that has been given to them, unaltered. The format is subject to change.
Returns

HSDCErrorSuccess

The initialization succeeded

HSDCErrorInvalidArg

Invalid argument

HSDCErrorInvalidLicense

The license provided is invalid

HSDCErrorExpiredLicense

The license provided is expired

HSDCErrorVersionAlreadyInitialized

The library has already been initialized

HSDCErrorVersionNotSupported

The requested version is not supported

HSDCErrorOSVersionNotSupported

The operating system is not supported

HSDCErrorCryptoNotFunctionnal

The cryptographic engine initialization failed

HSDCErrorUnexpected

Unexpected error occurred

HSDCCleanup()

HSDCError HSDCAPI HSDCCleanup ( )

This call cleans up resources (but the dictionary strings) allocated during HSDCStartup and other API calls. No other calls should be made after this call, other than HSDCStartup. Any memory allocated by the API as returned parameters during previous call is released, and any registered callbacks are also unregistered.

Returns

HSDCErrorSuccess

The operation succeeded

HSDCErrorVersionNotInitialized

Initialization has not been performed

HSDCGetVersion()

HSDCError HSDCAPI HSDCGetVersion ( WORD * pVersion )

Returns the API version.

Parameters

pVersion

It returns the initialized version.
Returns

HSDCErrorSuccess

The operation succeeded

HSDCErrorInvalidArg

The passed argument was invalid, pVersion was nullptr

HSDCFreeObject()

HSDCError HSDCAPI HSDCFreeObject ( Void * pObj )

Frees memory allocated by the API that has been returned. The API tracks all memory allocations and releases forgotten allocations on HSDCCleanup. The caller is encouraged to process output parameters as soon as possible or make a copy then free output parameters as quickly as possible to avoid memory leaks.

Parameters

pObj

Pointer to memory, which could be a string (utf-8 or Unicode, and so on).
Returns

HSDCErrorSuccess

The operation succeeded

HSDCErrorInvalidArg

The pointer was nullptr or did not point to memory that was managed in the HSDC library

HSDCGetConfiguration()

HSDCError HSDCAPI HSDCGetConfiguration ( char ** pJstr )

Returns the JSON configuration of the API layer.

Parameters

pJstr

Pointer to a JSON string containing the configuration, in the form:

Copy 
{
  "registry": "Software\\Ivanti\\DeviceControlAFEngine",
  "strings": true,
  "minidump": {
    "name": "DeviceControlAFEngine",
    "type": "console"
  }
}

registry is used to get logging settings such as log to file and log file name as for the general logging settings.

strings indicates if the string dictionary with all translations is loaded.

minidump controls the prefix name and the type of crash dump generated for unhandled exceptions; set type to console to log in the console, otherwise a dialog will appear.
Returns

HSDCErrorSuccess

The operation succeeded

HSDCErrorInvalidArg

Input was nullptr

HSDCErrorNotInitialized

Initialization was not performed

HSDCErrorUnexpected

Unexpected error

HSDCSetConfiguration()

HSDCError HSDCAPI HSDCSetConfiguration ( const char * jstr )

Sets the JSON configuration of the API layer.

Parameters

jstr

JSON string containing the configuration, in the form:

Copy 
{
  "registry": "Software\\Ivanti\\DeviceControlAFEngine",
  "strings": true,
  "minidump": {
    "name": "DeviceControlAFEngine",
    "type": "console"
  }
}

registry is used to get logging settings such as log to file and log file name as for the general logging settings.

strings indicates if the string dictionary with all translations is loaded.

minidump controls the prefix name and the type of crash dump generated for unhandled exceptions; set type to console to log in the console, otherwise a dialog will appear.
Returns

HSDCErrorSuccess

The operation succeeded

HSDCErrorInvalidArg

Input was nullptr

HSDCErrorNotInitialized

Initialization was not performed

HSDCSetLogging()

HSDCError HSDCAPI HSDCSetLogging ( const char * logSetup )

Updates the log settings of the HSDC Agent components.

The allowed components are:

Component

Values

PostAction

scomc

ODS Standard Items

Restart Service

RTNotify

ODS Standard Items

Logon

Dcext

ODS Standard Items

Logon

API

ODS Standard Items

Restart Process using SDK

The names are all case sensitive. The ODS Standard Items referred to above are visible in the below example settings for SCOMC.

Copy 
const char* json{ R"++(
    {
        "scomc":{
            "toFile":true,
            "toDbwin":true,
            "toConsole":false,
            "fileName":"scomc.log",
            "filePath":"C:\temp\",
            "fileSize":10485760,
            "retainLimit": 5
        }
    }
)++"};
if(HSDCErrorSuccess == HSDCSetLogging(json)){
    std::cout << "Log Registries updated" << std::endl;
}
Parameters

logSetup

The JSON settings to apply.
Returns

HSDCErrorSuccess

successful

HSDCErrorJsonParse

not JSON passed

HSDCErrorJsonVerification

the input was JSON but was not valid for use by the function

HSDCErrorServiceDoesNotExist

the required key is not in place

HSDCErrorAccessDenied

the key is in place but we have no rights to modify the values

HSDCErrorFailed

the writing of the value is prevented for any other reason

HSDCErrorInvalidArg

the input is nullptr

HSDCGetLogging()

HSDCError HSDCAPI HSDCGetLogging ( char ** (logSettingsOut )

Returns all of the values for known HSDC Components. Only found components are included and only the value which have registry entries. Entries not being found is not considered an error.

Returns

HSDCErrorSuccess

success

HSDCErrorAccessDenied

no access to Reg key

HSDCErrorFailed

internal errors

HSDCErrorUnexpected

unknown errors
Copy 
char* json;
if(HSDCErrorSuccess == HSDCGetLogging(&json)){
    std::cout << json << std::endl;
    HSDCFreeObject(json);
}