PLUSNative Cloud-Controlled Floating Network Licensing using SOLO Server

Network Floating Licensing is where an application may be restricted to running on a specific network, and restricted to a certain number of concurrent seats (where a seat may be a user or running instance of your application). This topic guides you through some basics of getting started with using Cloud-Controlled Floating Network Licensing using SOLO Server. This feature has some limitations, so it is very important to review the overview of network floating before using it.

 If you wish to use Cloud-Controlled Floating Network Licensing using SOLO Server, you will need to contact us for additional details on availability and pricing.

Getting Started

As is characteristic of PLUSNative, the first step is to initialize an API context. Only one network session may be opened at a time for each API context initialized. In other words, if you have a single application that needs to manage separate sessions to limit concurrent use of individual modules/features separately, each one will require its own API context.

Important

Note that, due to operating system API limitations, the Cloud-Controlled Floating Network Licensing using SOLO Server can only limit use of a session certificate file to 1 process in Windows platforms.

Opening a Session

Opening a session is synonymous with attempting to allocate a seat, which is only allowed to occur if the seats are not already consumed by other users and/or application instances. A rough example of the contents of a function that opens a session is shown below.

C/C++
SK_ResultCode result = SK_ERROR_NONE;
SK_XmlDoc request = NULL;
SK_XmlDoc certificate = NULL;
int resultCode = 0;
int statusCode = 0;
BOOL successful = FALSE;
char *sessionId = NULL;

do
{
SK_PLUS_NetworkSessionDispose(context, SK_FLAGS_NONE); /*Dispose of any prior session in memory.*/
if (SK_ERROR_NONE != (result = SK_SOLO_NetworkSessionOpenGetRequest(context, SK_FLAGS_NONE, [licenseID], "[password]", &request, NULL)))
{
/*TODO: Failed to generate the web service request.  Show an error message to the user.*/
break;
}

/*Call the web service...*/
if (SK_ERROR_NONE != (result = SK_CallXmlWebService(context, SK_FLAGS_WEBSERVICE_RAW_RESULT, SK_CONST_WEBSERVICE_OPENSESSION_URL, request, &certificate, &resultCode, &statusCode)))
{
if (SK_ERROR_WEBSERVICE_RETURNED_FAILURE == result)
{
/*TODO: The web service returned an error, so show the details about the error message in the response. You can use SK_XmlDocumentDecryptRsa to decrypt the response, and then use SK_XmlNodeGetValueString to get values from /GetNetworkSession/PrivateData/ResultCode and /GetNetworkSession/PrivateData/ErrorMessage. (See the next code sample below.)*/
}
else
{
/*TODO: Handle an error showing the details about the result returned. You can use SK_ApiResultCodeToString*/
}
break;
}

if (SK_ERROR_NONE != (result = SK_PLUS_NetworkSessionOpen(context, SK_FLAGS_NONE, certificate))
{
/*Local validation of the certificate we received from SOLO Server failed. Show the user an error message, and close the session.*/
break;
}

/*TODO: Make sure the value in sessionId is stored/copied to a variable that can be accessed later for all other requests (see the next code sample below).*/
/*TODO: Use the SK_XmlNodeGetValue* functions to retrieve other, relevant information, such as the PollFrequency, PollRetryCount, PollRetryFrequency, AllocatedUntilDate, etc...*/

successful = TRUE;
} while (FALSE);

SK_XmlDocumentDispose(SK_FLAGS_NONE, &request);
SK_XmlDocumentDispose(SK_FLAGS_NONE, &certificate);
SK_StringDispose(SK_ERROR_NONE, &errorMsg);

if (TRUE == successful)
{
/*TODO: The session was opened and validated successfully. Update controls as needed.*/
}
else
{
/*TODO: The session could not be opened.  Show an error message to the user.*/
}

The code excerpt above has 3 primary steps needed to open the session, and exhibits the same pattern needed to perform other actions with a session.

  1. Use the SK_SOLO_NetworkSessionOpenGetRequest function to generate a web service request to open the session. In the example above, [licenseId] and "[password]" are replaced with the License ID and password issued to the customer in SOLO Server.
  2. Use SK_CallXmlWebService function to the call the web service using the request generated in the previous step.
  3. Verify the response and perform the activation (in this case, open) using the SK_PLUS_NetworkSessionOpen function.

To avoid making this topic excessively long, the additional steps will be summarized like the list above, without also providing example code here.  Of course, you can always reference the PLUSNative samples to get complete, functioning code that you can re-use in your applications.

Upon opening a session, you receive a network session certificate, which contains data about the session and how the protected application should behave. For example, it contains the date and time the session expires, whether or not it has been checked-out, how long it should wait between poll attempts, and more. Expanding on the example above, here is an example of how you can get the Session ID from the certificate:

C/C++
{
SK_XmlDoc certificateData = NULL;
char *sessionId = NULL;

/*Decrypt the certificate first...*/
if (SK_ERROR_NONE != (result = SK_XmlDocumentDecryptRsa(context, SK_FLAGS_NONE, 0, certificate, &certificateData)))
{
/*TODO: Failed to decrypt and/or verify the certificate document. Show the user an error, and break if in the do {} while (FALSE); loop shown above.*/
}

if (SK_ERROR_NONE == SK_XmlNodeGetValueString(SK_FLAGS_NONE, certificateData, "/GetNetworkSession/PrivateData/NetworkSession/SessionID", FALSE, &sessionId))
{
/*TODO: Failed to get the Session ID from the certificate document. Show the user an error, and break if in the do {} while (FALSE); loop shown above.*/
}

/*TODO: Display the value of sessionId, or copy it for display later.
/*TODO: Load other data from the certificate/response as needed.

/*When done with this copy of the session ID, dispose of it.*/
SK_StringDispose(SK_FLAGS_NONE, &sessionId);
/*Dispose the decrypted certificate when done with the decrypted certificate document.*/
SK_XmlDocumentDispose(SK_FLAGS_NONE, &certificateData);
}

Validating a Session

Once a session is open, and immediately after any action (other than closing the session) is performed, it is necessary to validate the session. The PLUSNative API automatically does this for you any time you call any of the SK_PLUS_NetworkSession* functions (though this does not apply to SK_PLUS_NetworkSessionClose). The automatic validation does the following:

Note that it is important to close the session rather than abandoning it when validation fails. This is because the session should not be allowed to be used when invalid, and if the session remains open on SOLO Server even though local validation has failed, abandoning it will cause SOLO Server to consider the seat to be valid until the allocated until date (or the date and time the session is set to expire if it has not polled successfully before then).

Polling a Session

When a session is open, it is set to expire by its "allocated until date."  In other words, if no poll occurs before the date and time shown in the "allocated until date" is reached, the session is considered expired by SOLO Server. Successfully polling the session with SOLO Server automatically extends the allocated until date, which is what allows SOLO Server to recover orphaned sessions/seats (which is helpful for handling abnormal application termination).

  1. Use the SK_SOLO_NetworkSessionPollGetRequest function to generate a web service request to poll the session.
  2. Use SK_CallXmlWebService function to the call the web service using the request generated in the previous step.
  3. Call the SK_PLUS_NetworkSessionPoll function, which verifies the response and loads the updated network session certificate.

If a session has been checked-out for extended/offline use, you may still poll to verify the session if Internet connectivity is available. However, the "allocated until date" is not automatically extended for a checked-out session.

Checking-out and Checking-in a Session

In some cases, you may find the need to allow users to check-out a session/seat for offline and/or extended use. An example could be a user who needs to use the protected application while traveling. To allow this, you can allow the user to check-out a session for a requested duration. When successful, SOLO Server will respond with an updated session certificate that has an allocated until date that is valid for the requested duration (or until the minimum or maximum check-out duration allowed if the requested duration is outside of those bounds). Follow the steps below to check-out a session:

  1. Use the SK_SOLO_NetworkSessionCheckoutGetRequest function to generate a web service request to poll the session.
  2. Use SK_CallXmlWebService function to the call the web service using the request generated in the previous step.
  3. Call the SK_PLUS_NetworkSessionCheckout function, which verifies the response and loads the updated network session certificate that is configured to work without connectivity.

Once checked-out, your application may continue to poll when Internet connectivity is available (just keep in mind that attempting to poll while offline could cause performance degradation). The seat will then be consumed until the allocated until date is reached, or the user checks-in and closes the session. So in the example of a traveling user, you might allow the user to check-out for up to a week, even though the user is only expected to travel for 3 to 4 days. This allows the user to continue to use the application in a disconnected state should unforeseen circumstances (such as inclement weather) arise. If the user returns when expected, he or she could then check-in the session and return to normal connected use so the seat becomes available for other users when not in use. Follow the steps below to check-in a session that was previously checked-out:

  1. Use the SK_SOLO_NetworkSessionCheckinGetRequest function to generate a web service request to check-in the session.
  2. Use SK_CallXmlWebService function to the call the web service using the request generated in the previous step.
  3. Call the SK_PLUS_NetworkSessionCheckin function, which verifies the response and loads the updated network session certificate that is configured to resume normal polling in a connected state.

Closing a Session

When your user finishes using the application or feature being licensed, you should close the session to make the seat available to other users. Follow the steps below to close a session:

  1. Use the SK_SOLO_NetworkSessionCloseGetRequest function to generate a web service request to poll the session.
  2. Use SK_CallXmlWebService function to the call the web service using the request generated in the previous step.
  3. Call the SK_PLUS_NetworkSessionClose function, which verifies the response and loads the updated network session certificate.

When you're done using the PLUSNative for managing a network session you should also call the SK_PLUS_NetworkSessionDispose function.  This function is automatically called for you when calling SK_ApiContextDispose, which needs to be called when you are done with the API context (such as when the application is being closed).

Review the Sample

The example code excerpts given above are only meant to provide guidance on how the APIs should be used. Review the PLUSNative samples to see complete, functioning example code that can be re-used in your applications.