cl_Open( )

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

Name:	int cl_Open(phDevice, pszDeviceName, pUsrAttr)
Inputs:	long* phDevice	pointer to returned call logging device handle
	const char* pszDeviceName	pointer to ASCIIZ string defining device to be opened and protocol to be used
	void* pUsrAttr	pointer to user-defined attribute for device
Returns:	0 on success -1 on failure
Includes:	cllib.h
Mode:	synchronous

Description

The cl_Open( ) function opens a call logging device and returns a call logging device handle that will be used to monitor the traffic on the line. The pszDeviceName parameter defines the protocol to be used, the method for retrieving L2 frames, and, if needed, the names of the HiZ devices to be used.

Parameter	Description
phDevice:	The pointer to the returned call logging device handle.
pszDeviceName:	The pointer to the ASCIIZ string that defines the call logging device to be opened and the protocol to be used. See below for a description of the format for this parameter.
pUsrAttr:	The pointer to the user-defined attribute for the specified call logging device.

The format of the pszDeviceName parameter is

<field1><field2>...<fieldN>

These fields may be listed in any order. The format of each of these fields is

:<key>_<value>

Table 12 below lists the valid keys and their acceptable values. All other keys are reserved for future use.

Table 12. pszDeviceName Field Values

Key	Meaning	Acceptable Values
P	Specifies the protocol name.	ISDN * NET5 QSIGE1 4ESS 5ESS DMS NI2 QSIGT1
M	Specifies the method used to get L2 frames.	HDLC FILE **
N	Specifies the name of the HiZ device that is connected to the network side. This key is ignored when the method used to get L2 frames is :M_FILE.	dtiB<n>
U	Specifies the name of the HiZ device that is connected to the user side. This key is ignored when the method used to get L2 frames is :M_FILE	dtiB<n>
* The protocol name ISDN specifically refers to the E-1 Euro-ISDN protocol, also known as NET5. ** Use FILE with the cl_DecodeTrace( ) for testing purposes. No physical device is needed when the FILE method is used to get L2 frames.

Termination Events

None

Cautions

• The Call Logging API is not multi-thread safe. Call logging functions must be called within the same thread.
• The application is responsible for allocating the memory used to store the user-defined attribute.
• Once per process, the cl_Open( ) function must be preceded by a call to gc_Start( ) first.

Example

#include <srllib.h>  
#include <gclib.h>  
#include <gcerr.h>  
#include <cllib.h>  
#include <stdio.h>  
#include <malloc.h>  
#include <memory.h>  
/* The Call Logging Device Handle */  
long g_hDevice = EV_ANYDEV;  
typedef struct  
{  
      const char*   pszProtocol;  
      const char*   pszNetworkDeviceName;  
      const char*   pszUserDeviceName;  
} DEVICEUSRATTR;  
extern long EventHandler(unsigned long hEvent);  
extern void ExitApplication(void);  
int InitApplication(const char* pszProtocol, const char* pszNetworkDeviceName, const char* pszUserDeviceName)  
{  
      DEVICEUSRATTR* pDeviceUsrAttr;  
      char szDeviceName[64];  
      if (g_hDevice == EV_ANYDEV)  
      {  
            if (pszProtocol == NULL)  
            {  
                  printf("InitApplication - Invalid NULL protocol\n");  
                  return -1;  
            }  
            pDeviceUsrAttr = (DEVICEUSRATTR*)malloc(sizeof(DEVICEUSRATTR));  
            if (pDeviceUsrAttr == NULL)  
            {  
                  printf("InitApplication - malloc() failed\n");  
                  return -1;  
            }  
            memset(pDeviceUsrAttr, 0, sizeof(DEVICEUSRATTR));  
            pDeviceUsrAttr->pszProtocol = pszProtocol;  
            if (gc_Start(NULL) != GC_SUCCESS)  
            {  
                  printf("InitApplication - gc_Start() failed\n");  
                  free(pDeviceUsrAttr);  
                  return -1;  
            }  
            if ((pszNetworkDeviceName == NULL) || (pszUserDeviceName == NULL))  
            {  
                  sprintf(szDeviceName, ":P_%s:M_FILE", pszProtocol);  
            }  
            else  
            {  
                  sprintf(szDeviceName, ":P_%s:M_HDLC:N_%s:U_%s", pszProtocol, pszNetworkDeviceName, pszUserDeviceName);  
                  pDeviceUsrAttr->pszNetworkDeviceName = pszNetworkDeviceName;  
                  pDeviceUsrAttr->pszUserDeviceName = pszUserDeviceName;  
            }  
            if (cl_Open(&g_hDevice, szDeviceName, pDeviceUsrAttr) != 0)  
            {  
                  printf("InitApplication - cl_Open() failed\n");  
                  gc_Stop();  
                  free(pDeviceUsrAttr);  
                  return -1;  
            }  
            if (sr_enbhdlr(g_hDevice, EV_ANYEVT, EventHandler) != 0)  
            {  
                  printf("InitApplication - sr_enbhdlr() failed\n");  
                  cl_Close(g_hDevice);  
                  g_hDevice = EV_ANYDEV;  
                  gc_Stop();  
                  free(pDeviceUsrAttr);  
                  return -1;  
             }  
      }  
      return 0;  
}  
int main(int argc, char* argv[])  
{  
      char szUnusedInput[256];  
      if (InitApplication("ISDN", "dtiB1", "dtiB2") != 0)  
      {  
            return 1;  
      }  
      /* Wait until <Return> is hit */  
      gets(szUnusedInput);  
      ExitApplication();  
      return 0;  
}

Errors

The cl_Open( ) function does not return errors in the standard Call Logging API return code format because the error is a system, parameter, or GlobalCall error. Also, the standard ATDV_LASTERR( ) function requires a device handle and if cl_Open fails, there is none.

If an error occurs during the cl_Open( ) call, a -1 is returned and the specific error code is returned in the errno global variable. The error codes that can be returned if cl_Open( ) fails are:

Error Code Value	Returned When
ECL_NULLPARAMETER	invalid NULL parameter
ECL_GCOPENEX_NETWORK *	gc_OpenEx( ) failed on the network side
ECL_GCOPENEX_USER *	gc_OpenEx( ) failed on the user side
ECL_INVALIDPARAMETER	invalid parameter
ECL_NOMEM	out of memory
ECL_INTERNAL	internal Call Logging API error; cause unknown
*The following additional flag is set in these error code values to indicate that the error occrurred while the Call Logging API was calling a GlobalCall function:
ECL_FLAG_INSIDE_GC	use gc_ErrorValue( ) for an additional error description

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

See Also

• cl_Close( )
• cl_SetUsrAttr( )

Click here to contact Dialogic Customer Engineering