registerCallback

Interface Information

>This API belongs to SentinelLicensing.dll.

>The corresponding library is Sentinel RMS licensing library.

Description

Use this API to register vendor-defined callback(s).

The callbacks can be provided to:

NOTE   Currently, Unified APIs do not support server-side customization. You may use the VLS APIs for the same.

Syntax

static void registerCallback(ApplicationContext appContext, String type, ICallback callBackFn)

Argument	Description
appContext [In]	Reserved for future use. Use NULL as the value for this argument.
type [In]	>For CustomEx locking, specify SNTL_CALLBACK_TYPE_CUSTOM_FINGERPRINT. >For registering a trace writer, specify SNTL_CALLBACK_TYPE_CUSTOM_TRACE_WRITER.
callBackFn [In]	The callback function. >Prototype for CustomEx locking > Prototype for trace writer function

NOTE   For the Lease mode, if the entitlement is not obtained, then as a workaround, the transfer API should be called explicitly with the <sync> action tag.

Prototype for CustomEx

long ICallback(String input,IntPtr output, ref uint size);

The library first calls the CustomEx implementation with output as NULL. The vendor needs to provide the size of the Response XML. In the subsequent call, the library will allocate the specified size of output. The response output, output, needs to be filled by the vendor with the response XML.

Parameter	Description
input [In]	Defines the callback type in XML format. Set by the licensing library.
output[Out]	The Response XML provided by the vendor's implementation.
size [Out]	The size of the buffer pointed by the output parameter.

A sample implementation is provided in the Code Snippet section.

Input XML

<?xml version="1.0" encoding="UTF-8"?>
<callbackInputData>
	<callbackType>customFingerprint</callbackType>
</callbackInputData>

Response XML

<?xml version="1.0" encoding="utf-8"?>
<callbackOutputData>
    <customFingerprint>
        <item>
            <rawValue></rawValue>
        </item>
        <item>
             <rawValue></rawValue>
        </item>
    </customFingerprint>
</callbackOutputData>

Code Snippet

// #1. Define a CustomEx locking specific XML
public static String CALLBACK_OUTPUT_XML = "
  <?xml version=\"1.0\" encoding=\"UTF-8\"?>
    <callbackOutputData> 
      <customFingerprint>
         <item>
           <rawValue>111222333444555666777888999aaab</rawValue>
         </item>
         <item>
            <rawValue>abcdef0123456789abcdef012345678</rawValue>
          </item>
      </customFingerprint>
    </callbackOutputData>";
// #2. Implementation of the Callback Function
static long callback_impl_custom_ex(String pcInput, IntPtr pcOutput, ref uint piSizeOutput)
{
    if (pcOutput == IntPtr.Zero)
    {
        //licensing library is asking for the size of memory buffer to be allocated.
        if (piSizeOutput == 0)
        {
           piSizeOutput = (uint) CALLBACK_OUTPUT_XML.Length; //Output XML
        }
        else
        {
         return 1; //return error
        }
    }
    else
    {
        // Licensing library has allocated the required buffer for the actual data to be copied.
           try
        { 
           byte[] chars = System.Text.Encoding.ASCII.GetBytes(CALLBACK_OUTPUT_XML + '\0');
           Marshal.Copy(chars, 0, pcOutput, chars.Length);
        }
           catch (Exception e)
        {
        }
    }
        return (0); // return 0 to indicate success
}

// #3 Calling the registerCallback API. Sample implementation only.

public static void main(String[] args)
{
    ApplicationContext.ICallback customexCallback = new ApplicationContext.ICallback
    (callback_impl_custom_ex);
    ApplicationContext.registerCallback(null, LicensingConstants.SNTL_CALLBACK_TYPE_CUSTOM_
    FINGERPRINT, customexCallback);
}

Prototype for Custom Trace Writer

long ICallback(String input,IntPtr output, ref uint size);

Parameter	Description
input [In]	Defines the callback type, trace level and trace data in XML format. Set by the licensing library.
output[Out]	Not used.
size[Out]	Not used.

Input XML

<?xml version="1.0" encoding="UTF-8"?>
  <callbackInputData>
	    <callbackType>customTraceWriter</callbackType>
	     <trace>
		     <!-- Possible values = "error" or "function" -->
		     <!-- Helps ISVs to filter messages -->
		       <traceLevel></traceLevel>
		       <traceData>Trace message line in UTF8 format</traceData>   
	</trace>	   
</callbackInputData>

Response XML

Not Applicable

Code Snippet

// #1. Implementation of the Callback Function
static long callback_impl_custom_trace_writer(String input, IntPtr output, ref uint size)
{
   System.Console.WriteLine("callback_impl_custom_trace_writer() called with pcInput: as \n!"+ input);
   return (0);
}
 
// #2 Calling the sntl_licensing_register_callback API. Sample implementation only.
public static void main(String[] args)
{
   ApplicationContext.ICallback callBackFn = new ApplicationContext.ICallback(callback_impl_custom_trace_writer);
   ApplicationContext.registerCallback(null, LicensingConstants.SNTL_CALLBACK_TYPE_CUSTOM_TRACE_WRITER, callBackFn);
}

Returns

The status code SNTL_SUCCESS is returned, if successful. Otherwise, an error code is returned indicating the reason for failure. For a complete list of error codes, see "Unified API - Error and Result Codes".

For CustomEx

If successfully registered, the callback is invoked by the licensing library whenever locking-related information is retrieved by the licensing library. Otherwise, the fingerprint values of CustomEx are not available in the resultant output of fingerprintInfo.

For more information, refer to the Defining the Custom Locking Criteria section

Exception Handling

If unsuccessful, throws LicensingException.