gc_GetCallState( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_GetCallState(crn, state_ptr)
Inputs:	CRN crn	call reference number
	int *state_ptr	pointer to variable for returning call state
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	synchronous
Platform and Technology:	All

Description

The gc_GetCallState( ) function retrieves the state of the call associated with the call reference number (CRN). The acquired state will be associated with the last message received by the application. This function is especially useful when an error occurs and the application requires an update as to whether the call state has changed. State transition diagrams and call state definitions are presented in the Global Call API Programming Guide.

Parameter	Description
crn	call reference number
state_ptr	points to the location where the call state value will be returned. Possible state values are: GCST_ACCEPTED An inbound call was accepted; the call is in the Accepted state. GCST_ALERTING The call is waiting for the destination party to answer; the call is in the Alerting state (alerted sent or received). GCST_CALLROUTING Exists for an incoming call when the user has sent an acknowledgment that all call information necessary to effect call establishment has been received. Note: GCST_CALLROUTING is not supported on DM3 boards. GCST_CONNECTED An inbound or outbound call was connected; the call is in the Connected state. GCST_DETECTED An incoming call has been received but has not yet been offered to the application; the call is in the Detected state. GCST_DIALING An outbound call request was received; the call is in the Dialing state.
	GCST_DIALTONE The line device is ready to make a consultation call in a supervised transfer; the call is in the Dialtone state. (Supported only under the PDKRT call control library.) GCST_DISCONNECTED The call was disconnected from the network, the call is in the Disconnected state. GCST_GETMOREINFO Exists for an inbound call when the network has received an acknowledgment of the call establishment request, which permits the network to send additional call information (if any) in the overlap mode. GCST_IDLE The call is not active; the call is in the Idle state. GCST_NULL The call was released; the call is in the Null state. GCST_OFFERED An inbound call was received, the call is in the Offered state. GCST_ONHOLD The call was placed on hold; the call is in the OnHold state. GCST_ONHOLDPENDINGTRANSFER The call is on hold and waiting to be transferred to another call (supervised transfer); the call is in the OnHoldPendingTransfer state. (Supported only under the PDKRT call control library.) GCST_PROCEEDING Exists for an outbound call when the user has received an acknowledgment that all call information necessary to effect call establishment has been received and the call is proceeding. Note: GCST_PROCEEDING is not supported on DM3 boards. GCST_SENDMOREINFO Exists for an outbound call when the user has received an acknowledgment of the call establishment request that permits or requests the user to send additional call information to the network in overlap mode.

Termination Events

None

Cautions

• Due to the process latency time, the state value acquired through the gc_GetCallState( ) function may lag behind the current call state in the protocol state machine. If the two state values differ, the acquired state value is always behind the actual state. This is especially evident in the process of establishing an outbound call. The state acquired by the application will be associated with the latest event received by the application.
• The GCST_CALLROUTING and GCST_PROCEEDING call states are not supported on DM3 boards.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).

Example

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
#define MAXCHAN   30                 /* max. number of channels in system */
/*
 * Data structure which stores all information for each line
 */
struct linebag {
   LINEDEV  ldev;                    /* GlobalCall line device handle */
   CRN      crn;                     /* GlobalCall API call handle */
   int      state;                   /* state of first layer state machine */
} port[MAXCHAN+1]; 
struct linebag *pline;               /* pointer to access line device */ 
int get_call_state(int port_num)
{
   LINEDEV        ldev;              /* line device ID */
   CRN            crn;               /* call reference number */
   int            call_state;        /* current state of call */
   GC_INFO        gc_error_info;   /* GlobalCall error information data */
   /* Find info for this time slot, specified by 'port_num' */
   /* (Assumes port_num is valid) */
   pline = port + port_num;
   crn = pline -> crn;
   /*
    * Retrieve the call state and save it.
    */
   if (crn) { 
       if (gc_CRN2LineDev( crn, &ldev) != GC_SUCCESS)
       {
            /* get and process error */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_CRN2LineDev() on crn: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                  CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                  crn, gc_error_info.gcValue, gc_error_info.gcMsg, 
                  gc_error_info.ccLibId, gc_error_info.ccLibName,
                  gc_error_info.ccValue, gc_error_info.ccMsg);
            return (gc_error_info.gcValue);
         }
         if (gc_GetCallState( crn, &call_state) != GC_SUCCESS)
         {
            /* process error return as shown */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_GetCallState() on devive handle: 0x%lx, 
                  GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                  ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
                  gc_error_info.ccLibId, gc_error_info.ccLibName,
                  gc_error_info.ccValue, gc_error_info.ccMsg);
           return (gc_error_info.gcValue);
         }
   } 
     pline->state = call_state;
     return (0);
} 

See Also

None

Click here to contact Telecom Support Resources