gc_ReqANI( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_ReqANI(crn, anibuf, req_type, mode)
Inputs:	CRN crn	call reference number
	char *anibuf	buffer to store ANI digits
	int req_type	request type
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	interface specific
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: ISDN† †See the Global Call Technology User's Guides for additional information.

Description

The gc_ReqANI( ) function requests the remote side to return Automatic Number Identification (ANI), which is normally included in the ISDN setup message. If the caller ID does not exist, and the AT&T ANI-on-Demand feature is available, the driver will automatically request caller ID from the network if the ANI-on-Demand service is enabled. The returned caller ID (a NULL terminated ASCII string) is stored in the buffer indicated by the anibuf parameter.

If ANI information is always available, use the gc_GetANI( ) function, instead of the gc_ReqANI( ) function to obtain a faster return.

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

Parameter	Description
crn	call reference number
anibuf	address of the buffer where ANI digits will be loaded. This buffer will be terminated by "\0".
req_type	request type: ISDN_CPN_PREF calling party number preferred ISDN_BN_PREF billing number preferred ISDN_CPN calling party number only ISDN_BN billing number only ISDN_CA_TSC special use
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_REQANI

indicates successful completion of the function, that is, the requested ANI information was returned.

GCEV_TASKFAIL

indicates that the function failed. See the "Error Handling" section in the Global Call API Programming Guide.

Note: A GCEV_DISCONNECTED event is an unsolicited event that may be reported to the application after a gc_ReqANI( ) function is issued.

Cautions

• Ensure that anibuf buffer is at least as large as GC_ADDRSIZE bytes. Currently, ANI-on-Demand is available only on the AT&T ISDN network.
• If this function is invoked for an unsupported technology, the function will fail. The error value EGC_UNSUPPORTED will be the Global Call value returned when the gc_ErrorInfo( ) function is used to retrieve the error code.
• The gc_ReqANI( ) function may not be supported in all service-provider environments. Check whether retrieving billing information is an available option from your service provider.

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

/*
 * Assume the following has been done:
 * 1. device has been opened (e.g. :N_dtiB1T1:P_isdn, 
 *    :N_dtiB1T2:P_isdn, etc...)
 * 2. gc_WaitCall() has been issued to wait for a call.
 * 3. gc_MetaEvent() has been called to convert the event into metaevent.
 * 4. a GCEV_OFFERED has been detected.
 */ 
#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h>
#include <gcisdn.h> 
/*
 * For this example, let's assume that the mode = EV_SYNC and
 * req_type = ISDN_CPN_PREF (Calling Party Number Preferred).
 * req_type can be one of following:
 *     ISDN_BN_PREF (Billing Number preferred)
 *     ISDN_CPN     (Calling Party Number only)
 *     ISDN_BN      (Billing Number only)
 *     ISDN_CA_TSC  (Special Use)
 */ 
int req_crn(CRN crn, char *ani_buf, int req_type, unsigned long mode)
{
    LINEDEV  ldev;            /* Line device */
    GC_INFO  gc_error_info;   /* GlobalCall error information data */ 
    if(gc_CRN2LineDev(crn, &ldev) != GC_SUCCESS) {
        /* process error return as shown */
        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_ReqANI(crn, ani_buf, req_type, mode) != GC_SUCCESS) {
         /* process error return as shown */
         gc_ErrorInfo( &gc_error_info );
         printf ("Error: gc_ReqANI() on device 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);
    } 
    return(0);
} 

See Also

• gc_GetCallInfo( )
• gc_GetANI( ) (deprecated)
• gc_WaitCall( )

Click here to contact Telecom Support Resources