cl_GetMessageDetails( )

Description | Termination Events | Cautions | Example | Errors | See Also

Name:	int cl_GetMessageDetails(hDevice, pidMessage, pclEventData, piSource, pszName, iNameSize, pszTraceText, iTraceTextSize)
Inputs:	long hDevice	call logging device handle
	long* pidMessage	pointer to L3 message ID
	CL_EVENTDATA* pclEventData	pointer to call logging event data block
	int* piSource	pointer to code that identifies sender side of message
	char* pszName	pointer to buffer for L3 message name
	int iNameSize	size of buffer for L3 message name
	char* pszTraceText	pointer to buffer for decoded L3 message text
	int iTraceTextSize	size of buffer for decoded L3 message text
Returns:	0 on success -1 on failure -2 if call logging transaction already released
Includes:	cllib.h
Mode:	synchronous

Description

The cl_GetMessageDetails( ) function returns the ID and details of a Layer 3 message for which a CLEV_MESSAGE event was generated. Optional details about the L3 message that can be returned include the message source, the message name, and the human-readable decoded text based on the protocol message. Pass NULL as the related parameter for any details that are not needed.

The returned L3 message ID is unique and protocol-dependent. The value of the returned code is either CL_SOURCE_NETWORK or CL_SOURCE_USER.

Parameter	Description
hDevice:	The device handle of the call logging device.
pidMessage:	The pointer to the returned L3 message ID.
pclEventData:	The pointer to the call logging event data block obtained from sr_getevtdatap( ) while the function was processing a CLEV_MESSAGE event. See Section 1.5.2. Retrieving Event Datafor more information.
piSource:	The pointer to the returned code that identifies the sender side of the L3 message. The value of the returned code is either CL_SOURCE_NETWORK or CL_SOURCE_USER
pszName:	The pointer to the buffer into which the name of the L3 message is returned as an ASCIIZ string.
iNameSize:	The size of the buffer into which the name of the L3 message is returned, where the maximum size includes the terminating NUL of the ASCIIZ string.
pszTraceText:	The pointer to the buffer into which the human-readable decoded text of the L3 message is returned as an ASCIIZ string.
iTraceTextSize:	The size of the buffer into which the human-readable decoded text of the L3 message is returned, where the maximum size includes the terminating NUL of the ASCIIZ string.

Termination Events

None

Cautions

• The Call Logging API is not multi-thread safe. Call logging functions must be called within the same thread.
• This function can be called only while processing a CLEV_MESSAGE event.
• The names of the L3 messages are protocol dependent.

Example

#include <cllib.h>  
#include <stdio.h>  
const char* ToText_MessageSource(int iMessageSource)  
{  
      if (iMessageSource == CL_SOURCE_NETWORK)  
      {  
            return "Network-side";  
      }  
      else if (iMessageSource == CL_SOURCE_USER)  
      {  
            return "User-side";  
      }  
      return "Unknown";  
}  
void GetMessageDetails_WithinEventHandler(long hDevice, CL_EVENTDATA* pclEventData)  
{  
      int iRet;  
      long idMessage;  
      int iMessageSource;  
      char szMessageName[32];  
      char szMessageTraceText[4096];  
      iRet = cl_GetMessageDetails(hDevice, &idMessage, pclEventData, &iMessageSource, szMessageName, sizeof(szMessageName), szMessageTraceText, sizeof(szMessageTraceText));  
      if (iRet != 0)  
      {  
            if (iRet == -2)  
           {  
                  printf("GetMessageDetails_WithinEventHandler - Transaction already released\n");  
            }  
            else  
            {  
                  printf("GetMessageDetails_WithinEventHandler - cl_GetMessageDetails() failed\n");  
            }  
            return;  
      }  
      printf("Message ID=%08X \"%s\" sent by %s(%i):\n%s\n", idMessage, szMessageName, ToText_MessageSource(iMessageSource), iMessageSource, szMessageTraceText);  
}

Errors

If the function returns a value < 0, use the SRL Standard Attribute function ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive error message. The error codes that can be returned by ATDV_LASTERR( ) are:

Error Code Value	Returned When
ECL_NULLPARAMETER	invalid NULL parameter
ECL_INVALIDCONTEXT	invalid event context
ECL_TRANSACTIONRELEASED	transaction already released
ECL_INTERNAL	internal Call Logging error; cause unknown

See 2.2 Error Handling for more information about what kinds of errors can cause these codes to be returned

See Also

• cl_ReleaseTransaction( )
• cl_GetMessage( )

Click here to contact Dialogic Customer Engineering