registerCallback

Interface Information

>This API belongs to SentinelLicensing.jar.

>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 cbObject)

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.
cbObject [In]	The callback function. >Prototype for CustomEx locking > Prototype for trace writer function

Prototype for CustomEx

long callback(String input, Pointer output, Pointer 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
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
class Callback_CustEx implements ApplicationContext.ICallback
{
    public long callback(String input, Pointer output, Pointer size)
    {
       if (output == null)
        {
            // The licensing library is asking for the size of memory buffer to be allocated.
            if(size != null)
            {
               size.setInt(0, CALLBACK_OUTPUT_XML.length());//Output XML described below
            }
            else
               return 1; //return error
        }
       else
        {    
            // The licensing library has allocated the required buffer space to copy data into this buffer
            output.setString(0, CALLBACK_OUTPUT_XML); 
        }   
            return 0;  //return 0 to indicate success
    }
}

// #3 Calling the registerCallback API. Sample implementation only.
public static void main(String[] args) throws java.io.IOException, InterruptedException
{
       Callback_CustEx callback_obj = new Callback_CustEx();
       ApplicationContext.registerCallback(null,LicensingConstants.SNTL_CALLBACK_TYPE_CUSTOM_
       FINGERPRINT,callback_obj);
} 

Prototype for Custom Trace Writer

long callback(String input, Pointer output, Pointer 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 in this release
size[Out]	Not used in this release

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
class CallbackTraceWriter implements ApplicationContext.ICallback
{
    public long callback_impl_custom_trace_writer(String input, Pointer output, Pointer size);
    {
      System.out.println(" \n callback_impl_custom_trace_writer() called with pcInput: as  \n!"+ input);
       return 0;
     }
}
 
// #2 Calling the registerCallback API. Sample implementation only.
public static void main(String[] args) throws LicensingException, UnsupportedEncodingException
{
    CallbackTraceWriter  callback_Obj = new CallbackTraceWriter();
    ApplicationContext.registerCallback(null,LicensingConstants. SNTL_CALLBACK_TYPE_CUSTOM_TRACE_WRITER, callback_Obj);
}

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" .

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.

Exception Handling

If unsuccessful, throws LicensingException or UnsupportedEncodingException.