cl_ReleaseTransaction( )

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

Name:	int cl_ReleaseTransaction(hDevice, idTransaction)
Inputs:	long hDevice	call logging device handle
	long idTransaction	call logging transaction ID
Returns:	0 on success -1 on failure -2 if call logging transaction already released
Includes:	cllib.h
Mode:	synchronous

Description

The cl_ReleaseTransaction( ) function releases a call logging transaction. Once a transaction has been released, information about that particular call logging transaction can no longer be queried. Because a call logging system has no impact on a digital line and only observes the activity on the line, the cl_ReleaseTransaction( ) function does not drop the monitored call. Rather, the purpose of the function is to instruct the Call Logging API to release the internal resources allocated for the specified call logging transaction.

The cl_ReleaseTransaction( ) function is usually called from the call logging event handler when a CLEV_MESSAGE event is received and the event has the ECL_LAST_MESSAGE bit set in the iResult field of its call logging event data block (see 1.5.2. Retrieving Event Data for more information). If the cl_ReleaseTransaction( ) function is called before this specific event is received, the application will not receive any additional call logging events related to the specified call logging transaction.

Parameter	Description
hDevice:	The device handle of the call logging device.
idTransaction:	The call logging transaction ID to be released.

Termination Events

None

Cautions

• The Call Logging API is not multi-thread safe. Call logging functions must be called within the same thread.
• When the application has completed a call logging transaction, the cl_ReleaseTransaction( ) function must be called to release internally allocated resources. Failure to do so may cause memory problems due to the allocated memory not being released (ECL_OUT_OF_MEMORY error).
• Once the cl_ReleaseTransaction( ) function is called, the call logging transaction ID is no longer valid.

Example

#include <srllib.h>  
#include <cllib.h>  
#include <stdio.h>  
#include <malloc.h>  
typedef struct  
{  
      const char*   pszProtocol;  
      const char*   pszNetworkDeviceName;  
      const char*   pszUserDeviceName;  
} DEVICEUSRATTR;  
typedef struct  
{  
      time_t      timeConnect;  
      time_t      timeDisconnect;  
} TRANSACTIONUSRATTR;  
extern DEVICEUSRATTR* GetDeviceUsrAttr(long hDevice);  
extern TRANSACTIONUSRATTR* GetTransactionUsrAttr(long hDevice, long idTransaction);  
extern TRANSACTIONUSRATTR* SetTransactionUsrAttr(long hDevice, long idTransaction);  
long EventHandler(unsigned long hEvent)  
{  
      long hDevice;  
      long lEvent;  
      CL_EVENTDATA* pclEventData;  
      int iRet;  
      long idTransaction;  
      DEVICEUSRATTR* pDeviceUsrAttr;  
      TRANSACTIONUSRATTR* pTransactionUsrAttr;  
      hDevice = sr_getevtdev(hEvent);  
      if (hDevice == -1)  
      {  
            printf("EventHandler - sr_getevtdev() failed\n");  
            return 1;  
      }  
      lEvent = sr_getevttype(hEvent);  
      if (lEvent == -1)  
      {  
            printf("EventHandler - sr_getevttype() failed\n");  
            return 1;  
      }  
      pclEventData = (CL_EVENTDATA*)sr_getevtdatap(hEvent);  
      if (pclEventData == NULL)  
      {  
            printf("EventHandler - sr_getevtdatap() failed\n");  
            return 1;  
      }  
      pDeviceUsrAttr = GetDeviceUsrAttr(hDevice);  
      if (lEvent == CLEV_MESSAGE)  
      {  
            printf("EventHandler - CLEV_MESSAGE - iResult=%08X\n", pclEventData->iResult);  
            iRet = cl_GetTransaction(hDevice, &idTransaction, pclEventData);  
            if (iRet != 0)  
            {  
                  if (iRet == -2)  
                  {  
                        printf("EventHandler - Transaction already released\n");  
                  }  
                  else  
                  {  
                        printf("EventHandler - cl_GetTransaction() failed\n");  
                  }  
                  return 0;  
            }  
            printf("Transaction ID=%08X\n", idTransaction);  
            if ((pclEventData->iResult & ECL_FIRST_MESSAGE) != 0)  
            {  
                  pTransactionUsrAttr = SetTransactionUsrAttr(hDevice, idTransaction);  
            }  
            else  
            {  
                  pTransactionUsrAttr = GetTransactionUsrAttr(hDevice, idTransaction);  
            }  
            if (pTransactionUsrAttr != NULL)  
            {  
                  if ((pclEventData->iResult & ECL_CONNECT_MESSAGE) != 0)  
                  {  
                        pTransactionUsrAttr->timeConnect = pclEventData->timeEvent;  
                  }  
                  if ((pclEventData->iResult & ECL_DISCONNECT_MESSAGE) != 0)  
                  {  
                        pTransactionUsrAttr->timeDisconnect = pclEventData->timeEvent;  
                  }  
            }  
            if ((pclEventData->iResult & ECL_LAST_MESSAGE) != 0)  
            {  
                  free(pTransactionUsrAttr);  
                  pTransactionUsrAttr = NULL;  
                  iRet = cl_ReleaseTransaction(hDevice, idTransaction);  
                  if (iRet != 0)  
                  {  
                        if (iRet == -2)  
                        {  
                              printf("EventHandler - Transaction already released\n");  
                        }  
                        else  
                        {  
                              printf("EventHandler - cl_ReleaseTransaction() failed\n");  
                        }  
                  }  
            }  
            return 0;  
      }  
      else if (lEvent == CLEV_ALARM)  
      {  
            printf("EventHandler - CLEV_ALARM - iResult=%08X\n", pclEventData->iResult);  
            return 0;  
      }  
      else if (lEvent == CLEV_ERROR)  
      {  
            printf("EventHandler - CLEV_ERROR - iResult=%08X\n", pclEventData->iResult);  
            return 0;  
      }  
      printf("EventHandler - Unknown event(%08X)\n", lEvent);  
      return 1;  
}

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_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_GetTransaction( )
• cl_GetTransactionDetails( )
• cl_GetTransactionUsrAttr( )
• cl_SetTransactionUsrAttr( )

Click here to contact Dialogic Customer Engineering