gc_CallAck( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_CallAck(crn, callack_blkp, mode)
Inputs:	CRN crn	call reference number
	GC_CALLACK_BLK *callack_blkp	pointer to additional information for processing call
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	optional call handling
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1†, ISDN† DM3: ISDN† SS7† IP (host-based stack)† †See the Global Call Technology User's Guides for additional information.

Description

The gc_CallAck( ) function indicates (to the originator) call reception and optionally takes action or retrieves information from the network about the incoming call. This function is used when the call is in the Offered state (that is, after receiving a GCEV_OFFERED event or after the successful completion of the gc_WaitCall( ) function and before answering the call). Some services offered by this function, such as retrieving additional DDI (DNIS) digits, are available to all of the supported technologies. When the gc_CallAck( ) function is used to request additional DDI digits, use the gc_GetCallInfo( ) function to retrieve the DDI digits.

See also the appropriate Global Call Technology User's Guide for technology-specific information.

Parameter	Description
crn	call reference number
callack_blkp	points to the GC_CALLACK_BLK structure where the type field specifies the type of service requested by the gc_CallAck( ) function. See GC_CALLACK_BLK for further information.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution. When using ISDN protocols and the type field in the GC_CALLACK_BLK data structure is set to GCACK_SERVICE_ISDN, this mode parameter must be set to EV_SYNC.

For example, to use the gc_CallAck( ) function to collect four DDI digits, set:

• callack_blkp->type=GCACK_SERVICE_INFO
• callack_blkp->info.info_type=DESTINATION_ADDRESS
• callack_blkp->info.info_len=4

Table 2 shows the values that are supported for the type field.

Table 2. Possible Values for the type Field in GC_CALLACK_BLK 

type Value	Description
GCACK_SERVICE_INFO	Acknowledge the call and request more information. This type should be used instead of GCACK_SERVICE_DNIS (see below) to get more digits. Note: If this value is used for type, then the 'info' structure must be used in the service union. See Table 3 for information about the 'info' structure.
GCACK_SERVICE_PROC	Acknowledge that all the information has been received and the call is proceeding. This type should be used for acknowledging the call, for example, CALL_PROCEEDING for ISDN protocols, instead of using the GCACK_SERVICE_ISDN (see below) parameter.
GCACK_SERVICE_DNIS	Request retrieval of additional DNIS digits. Note: This type is not supported for all call libraries. It is recommended that GCACK_SERVICE_PROC be used instead.
GCACK_SERVICE_ISDN	Send the first response to an incoming call (ISDN only).

Table 3 describes the fields in the 'info' structure used when GCACK_SERVICE_INFO is specified.

Table 3. Fields in the 'info' Structure for GCACK_SERVICE_INFO 

Field	Description
info_type	Type of information requested. The possible values are: DESTINATION_ADDRESS request more DNIS ORIGINATION_ADDRESS request more ANI
info_len	Length of the info requested (typically number of digits)

Termination Events

GCEV_ACKCALL

indicates that the gc_CallAck( ) function was successful, that is, the requested call information was retrieved. See the appropriate Global Call Technology User's Guide to determine if this event is supported.

GCEV_MOREINFO

this event is received if the GCACK_SERVICE_INFO type is used. This event indicates the status of the information (typically digits) that was requested. The extevtdatap field of the METAEVENT contains the status of the information. Use the gc_ResultValue( ) function to get the result value that indicates if the requested number of digits is available, more digits are available, or no digits are available. Table  11, "Result Values for GCEV_MOREINFO" indicates the valid values.

GCEV_CALLPROC

this event is received if the GCACK_SERVICE_PROC type is used. This event indicates that the all the necessary information for the call has been received and the remote side has been notified that the call is now proceeding.

GCEV_TASKFAIL

indicates that the function failed. For more information, see the "Error Handling" section in the Global Call API Programming Guide.

Note: When using the ISDN call control library, the gc_CallAck( ) function may return either a GCEV_MOREDIGITS or a GCEV_ACKCALL termination event when the type field in the GC_CALLACK_BLK data structure is set to GCACK_SERVICE_DNIS.

Cautions

If this function is invoked for an unsupported technology, the function fails. The error value EGC_UNSUPPORTED will be the Global Call value returned when the gc_ErrorInfo( ) function is used to retrieve the error code.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_TASKFAIL event is received, use the gc_ResultInfo( ) function to retrieve information about the event. 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 <memory.h>
#include <gclib.h>
#include <gcerr.h>
#include <gcisdn.h>
/*
 * Assume the following has been done:
 * 1. Opened line devices for each time slot on DTIB1.
 * 2. Wait for a call using gc_WaitCall()
 * 3. An event has arrived and has been converted to a metaevent
 *    using gc_GetMetaEvent() or gc_GetMetaEventEx() (Windows NT)
 * 4. The event is determined to be a GCEV_OFFERED event
 */
int call_ack(void)
{
    CRN crn;                     /* call reference number */
    GC_CALLACK_BLK callack;      /* type & number of digits to collect */
    char dnis_buf[GC_ADDRSIZE];  /* Buffer for holding DNIS digits */
    GC_INFO     gc_error_info;    /* GlobalCall error information data */ 
    /*
     * Do the following:
     * 1. Get called party number using gc_GetCallInfo() and evaluate it.
     * 2. If three more digits are required by application to properly
     * process or route the call, request that they be sent.
     */
    memset(&callack, 0, sizeof(callack)); 
    /*
     * Fill in GC_CALLACK_BLK structure according to protocol
     * or technology used for application, and call gc_CallAck()
     */
    callack.type = GCACK_SERVICE_INFO;
    callack.service.info.info_type = DESTINATION_ADDRESS;
    callack.service.info.info_len = GCDG_NDIGIT;  /* Set to 3 */
    if (gc_CallAck(crn, &callack, EV_ASYNC) != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_CallAck() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               metaevent.evtdev, 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);
    }
    /*
     * Now collect the remaining digits.
     */
    if (gc_GetCallInfo(crn, DESTINATION_ADDRESS, dnis_buf) != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_GetCallInfo() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               metaevent.evtdev, 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);
    } 
    /*
     * Application can answer, accept, or terminate the call at this
     * point, based on the DNIS information.
     */
    return (0);
} 

See Also

• gc_AcceptCall( )
• gc_AnswerCall( )
• gc_GetCallInfo( )
• gc_GetDNIS( ) (deprecated)
• gc_WaitCall( )

Click here to contact Telecom Support Resources