The PLUSNative library uses an API context to persist configuration settings and a copy of the license file in memory between consecutive function calls. Many of the functions in this library require an API context as the first argument. The API context is usually initialized during application start-up and must be disposed of properly after the license checks or on application shut-down.
The steps laid out in the common implementation sub-topics of this manual do not match exactly what is in the Protection PLUS 5 SDK sample projects. The manual topics are more simplified to make it easier to explain, while the sample projects have more complex organization, but the resulting functionality is similar in both cases.
During application start-up or prior to calling any of the functions in the PLUSNative library an API context must be initialized. The API context also determines whether to treat the license file as a read-only license file or a self-signed writable license file.
The following code snippet demonstrates initializing the API context:
The example above uses data from the SOLO Server test account. The Product ID, product version and encryption key data must be updated to use data specific to your own account. This is described in detail in the Using your own SOLO Server account topic. The encryption envelope and envelope key above has been truncated for the sake of clarity.
When calling the SK_ApiContextInitialize function, the flags (first) argument accepts flags that can be applied as global context flags. In the example above, the SK_FLAGS_USE_SSL, SK_FLAGS_USE_ENCRYPTION, and SK_FLAGS_USE_SIGNATURE flags are specified globally for the new context. For any functions called using the context initialized in this function call, these flags are automatically applied in addition to any flags specified in the function call's flags argument. For instance, calling the SK_CallXmlWebService function with no flags (SK_FLAGS_NONE) with this context will automatically use the SK_FLAGS_USE_SSL, SK_FLAGS_USE_ENCRYPTION, and SK_FLAGS_USE_SIGNATURE flags as specified in this example. If this same function were to be called with SK_FLAGS_REQUIRE_SSL, then all 4 flags (SK_FLAGS_USE_SSL, SK_FLAGS_USE_ENCRYPTION, SK_FLAGS_USE_SIGNATURE, and SK_FLAGS_REQUIRE_SSL) would apply in this same example.
It is also possible to omit all global context flags in an individual function call using the SK_FLAGS_EXPLICIT_ONLY flag. To expand on the example above, let's say we wanted to make a web service call using SSL, but without separately encrypting and digitally signing the XML. (This could be done to call SOLO Server XML web service methods that do not support this extra layer of encryption, such as XmlLicenseServer's InfoCheck or UpdateCheck methods.) To do this with this example, this specific call to the SK_CallXmlWebService function would specify the SK_FLAGS_EXPLICIT_ONLY and SK_FLAGS_USE_SSL flags. The result would be that the call would only use the SK_FLAGS_USE_SSL flag, regardless of the flags that were previously defined when initializing the context.
Aside from the required configuration options set when initializing an API context, it is possible to set additional configuration options as well. One example is to set a proxy server configuration, as illustrated below:
When done with the PLUSNative library, or on application shut-down, the API context must be disposed of properly to free memory that has been allocated during initialization and normal use. If you use multiple contexts and/or call SK_ApiContextDispose() multiple times, the last time you call the function you must pass in the SK_FLAGS_APICONTEXTDISPOSE_SHUTDOWN flag to shutdown the PLUSNative API and free all memory.