sntl_licensing_register_callback

Library Information

>This API belongs to the Sentinel RMS licensing library.

>The corresponding header is licensing.h.

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

SNTL_DECLARE(sntl_status_t) sntl_licensing_register_callback (sntl_licensing_app_context_t      *app_context,
                                                               char                              *type,
                                                               const sntl_licensing_callback_t   call_back);

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

Prototype for CustomEx

long callback_impl_custom(char* pcInput, char *pcOutput, unsigned int *piSizeOutput) 

The library first calls the CustomEx implementation with pcOutput 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 pcOutput. The response output, pcOutput, needs to be filled by the software vendor with the response XML.

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

A sample implementation is provided in the following 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

static char * 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

long callback_impl_custom(char* pcInput, char *pcOutput, unsigned int *piSizeOutput)
{
    if (pcOutput == NULL)
    {
        // Means licensing library is asking for the size of memory buffer to be allocated.     
        if (piSizeOutput)
        {
            *piSizeOutput = strlen(CALLBACK_OUTPUT_XML); //Output XML described above
        }
        else
        {
            return 1;   // return error
        }
    }
    else
    {
        // Non-NULL means licensing library has allocated the required buffer space and asking for the actual data to be copied into this buffer.
        if (piSizeOutput)
        {
            strncpy(pcOutput, CALLBACK_OUTPUT_XML, *piSizeOutput);
        }
        else
        {
            return 1;   // return error
        }
    }
    return (0); // return 0 to indicate success
}

// #3 Calling the sntl_licensing_register_callback API. Sample implementation only.
    
int main()
{
    int rc = -1;
    rc = sntl_licensing_register_callback(NULL, SNTL_CALLBACK_TYPE_CUSTOM_FINGERPRINT, callback_impl_custom);
    printf("sntl_licensing_register_callback(), %s, rc: %d\n", SNTL_CALLBACK_TYPE_CUSTOM_FINGERPRINT, rc);
    if (rc)
        return (0);
} 

Prototype for the Custom Trace Writer

long callback_impl_trace_writer(char* pcInput, char *pcOutput, unsigned int *piSizeOutput)

Parameter	Description
pcInput [In]	Defines the callback type, trace level and trace data in XML format. Set by the licensing library.
pcOutput[Out]	Not used.
piSizeOutput [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
long callback_impl_trace_writer(char* pcInput, char *pcOutput, unsigned int *piSizeOutput)
 {
   printf("\ncallback_impl_trace_writer() called with pcInput: as %s \n!", pcInput);
   return (0);
 }
 
// #2 Calling the sntl_licensing_register_callback API. Sample implementation only.
int main()
{
   int rc = -1;
   rc = sntl_licensing_register_callback(NULL, SNTL_CALLBACK_TYPE_CUSTOM_TRACE_WRITER, callback_impl_trace_writer);
   printf("sntl_licensing_register_callback(),rc: %d\n", rc);
   if (rc)
     return (0);
  }

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 Licensing Library 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.