cc_GetSigInfo( )

Description | Cautions | Example | Errors | See Also

Name:	int cc_GetSigInfo(valuep, info_id, evtdatap)
Inputs:	char *valuep	pointer to information buffer
	int info_id	signal information identifier
	void *evtdatap	pointer to an event block
Returns:	0 on success < 0 on failure
Includes:	cclib.h
Category:	Optional call handling
Mode:	synchronous
Technology:	BRI/SC; PRI (all protocols)

Description

The cc_GetSigInfo( ) function gets the signaling information of an incoming message. The library uses evtdatap to retrieve the associated signaling information elements (IEs) and puts the information in the queue.

In order to use the cc_GetSigInfo( ) function for a channel, the application needs to specify the size of the queue by calling the cc_SetParm( ) function and setting the RECEIVE_INFO_BUF to the desired size.

Parameter	Description
valuep:	Points to the buffer where the call information will be stored.
info_id:	Specifies the type of signaling information to be retrieved (see Table 23 below).
evtdatap:	Points to the event data block. This pointer may be acquired by using sr_getevtdatap( ), an element of the Dialogic Standard Runtime Library (SRL).

The following table provides definitions of possible info_id parameters.

Table 23. cc_GetSigInfo( ) Info_ID Definitions

Info_ID	Definition
U_IES	Information elements (IEs) in CCITT format. The cc_GetSigInfo( ) function retrieves all unprocessed IEs in CCITT format. Be sure to allocate enough memory (up to 256 bytes) to hold the retrieved information elements. The IEs are returned as raw data and must be parsed and interpreted by the application. Use IE_BLK to retrieve the unprocessed IEs. For a description of the IE_BLK data structure, see Section 6.6. IE_BLK. NOTE: Information Elements (IEs) that are specific to the DPNSS protocol are described in Appendix C.
UUI	User-to-user information - the data returned is application-dependent and is retrieved using the USRINFO_ELEM data structure. For a description of the return format for UUI, see Section 6.16. USRINFO_ELEM.

Cautions

• Make sure the size of the information buffer pointed to by the valuep parameter is large enough to hold the complete set of information elements requested by the info_id parameter.
• To use the cc_GetSigInfo( ) function for a channel, the application must specify the size of the queue by calling the cc_SetParm( ) function and setting the RECEIVE_INFO_BUF to the desired size. Failure to set the size of RECEIVE_INFO_BUF will result in an error.
• This function is not supported for the BRI/2 board.
• The CCEV_NOFACILITYBUF event will be received by the application for every incoming ISDN message that contains the Network Facility IE. The event is received because the first four IEs are stored in the ISDN library and the remaining ones are discarded. The CCEV_NOFACILITYBUF event can be ignored. The IE can be retrieved using the cc_GetCallInfo(U_IES) function or the cc_GetInfoElem( ) function. The ability to retrieve just the Network Facility IE using the cc_GetCallInfo( ) function is no longer supported.

Example

#include <windows.h>   /* For Windows applications only */  
#include <stdio.h>  
#include <errno.h>  
#include <srllib.h>  
#include <dtilib.h>  
#include <cclib.h>  
#define MAX_QUEUE_SIZE    20  
void main()  
{  
  LINEDEV ldev;  
  char *devname = "dtiB1T1";  
  .  
  .  
  .  
/*get line device handler */  
if (cc_Open(&ldev,devname,0)<0)  
  {  
    printf("ERROR opening device : errno = %d\n", errno);  
    exit(1);  
  }  
/* using cc_SetParm to set size of the buffer queue for cc_GetSigInfo */  
if (cc_SetParm (ldev, RECEIVE_INFO_BUF, MAX_QUEUE_SIZE) < 0)  
  {  
procdevfail (ldev);  
    exit (1);  
  }  
  .  
  .  
  .  
/* Retrieve events from SRL */  
FOREVER  
while (1)  
  {  
    sr_waitevt(-1);  
  }  
  exit(0);  
}  
int evt_hdlr()  
{  
  LINEDEV ldev = sr_getevtdev();  
  unsigned long *ev_datap = (unsigned long *)sr_getevtdatap();  
  int len = sr_getevtlen();  
  IE_BLK ie_blk;  
    
  .  
  .  
  .  
  switch(sr_getevttype()){  
  .  
  .  
  .  
  case CCEV_CALLINFO:  
        /* retrieve signaling information from queue */  
        if ( cc_GetSigInfo(&ie_blk, U_IES, ev_datap) <0)  
           {  
              /* failed, get failure reason */  
                
              procdevfail (ldev);  
           }  
        else  
          {  
              /* succeeded, process signaling information */  
              .  
              .  
              .  
           }  
        break;  
  }  
    .  
    .  
    .  
}  
int procdevfail(LINEDEV ldev)  
{  
        int reason;  
        char *msg;  
        reason = cc_CauseValue(ldev);  
        cc_ResultMsg(ldev,reason,&msg);  
        printf("reason = %x - %s\n",reason,msg);  
}

Errors

If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.

Error codes from the cc_GetSigInfo( ) function include the following:

Error Code	Description
E_ISMISGSI | ERR_ISDN_LIB	The cc_GetSigInfo( ) function is not supported because the application did not use cc_SetParm( ) to allocate the signaling queue.
E_ISLSIEBUF | ERR_ISDN_LIB	The signaling information queue was too small to accommodate the incoming data. The signaling information associated with this event is lost. The application needs to increase the buffer size so that the queue is large enough to hold the information string.

See Also

• cc_GetCallInfo( )
• cc_SetParm( )

Click here to contact Dialogic Customer Engineering