gc_ReqMoreInfo( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_ReqMoreInfo(crn, info_id, info_len, timeout, mode)
Inputs:	CRN crn	call reference number
	int info_id	ID of the type of information
	int info_len	amount of information to be collected
	int timeout	time-out value in seconds
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	optional call handling functions
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only), ISDN DM3: ISDN† SS7 †See the Global Call Technology User's Guides for additional information.

Description

The gc_ReqMoreInfo( ) function requests more information such as ANI or DNIS from the call control layer or remote side. The gc_ReqMoreInfo( ) function is used after a call to the gc_CallAck( ) function, which acknowledges the call and gets the first piece of information.

After an incoming call is received, the application examines the completeness of the destination address. If more information is required (such as DNIS or ANI), the application calls the gc_CallAck( ) function with the service type as GCACK_SERVICE_INFO to acknowledge the call and request more information. If the technology call control layer does not have the required information or does not have sufficient information, then the application requests additional information from the remote side. If the required information is received, the GCEV_MOREINFO event is generated. If more digits are still needed, the application then calls the gc_ReqMoreInfo( ) function with the number of additional digits to be collected. When all the information is received or when the timer for receiving additional information times out, the GCEV_MOREINFO event is generated with the appropriate result.

The collected digits can be retrieved by calling the gc_GetCallInfo( ) function. When all the information has been collected, the application may call the gc_CallAck( ) function with the service type as GCACK_SERVICE_PROC to indicate to the remote side that the call is proceeding.

In synchronous mode, the gc_ReqMoreInfo( ) function will return successfully regardless of the status of the requested information, that is, if all, some or none of the information is available. If the call control technology is still waiting for information, then the function blocks until the information is received or the timeout expires. The gc_GetCallInfo( ) function must be called to determine if any information was received. If an error occurs, the function returns -1.

For more information about the use of the gc_ReqMoreInfo( ) function, see the discussion of overlap receiving in the Global Call API Programming Guide.

Parameter	Description
crn	call reference number for the call
info_id	ID of the type of information to be collected. The valid values are: DESTINATION_ADDRESS Request the called party number (typically digits - DNIS). ORIGINATION_ADDRESS Request the calling party number (typically digits - ANI).
info_len	amount of the information to be collected
timeout	specifies the amount of time in seconds in which the additional information must be generated. The GCEV_MOREINFO event is generated with the appropriate result value when the timer expires. The time-out value must be a non-zero positive value. A value <= 0 means that the function will wait indefinitely until the additional digits are received.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_MOREINFO

indicates that the function call is successful and the requested digits have been received. The eventdatap field of the METAEVENT structure 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 indicates the valid values.

GCEV_TASKFAIL

indicates that the function failed.

Table 11. Result Values for GCEV_MOREINFO 

Result Value	Description
GCRV_INFO_PRESENT_ALL	The requested digits are now available
GCRV_INFO_PRESENT_MORE	The requested digits are now available. More/additional digits are available
GCRV_INFO_SOME_TIMEOUT	Only some digits are available - timed out
GCRV_INFO_SOME_NOMORE	Only some digits are available, no more digits will be received
GCRV_INFO_NONE_TIMEOUT	No digits are available - timed out
GCRV_INFO_NONE_NOMORE	No more digits are available

Cautions

The gc_ReqMoreInfo( ) function can only be called after the gc_CallAck( ) function is called.

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

/*
 * 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
 * 5. It is determined that more digits are required. The call is 
 *    acknowledged with gc_callAck() with DESTINATION_ADDRESS 
 *    parameter to request more DNIS
 * 6. The GCEV_MOREINFO event is received. 
 */
int req_moreinfo(CRN crn)
{
    GC_INFO   gc_error_info;  /* GlobalCall error information data */
    int       n_digits;      /* to be evaluated */ 
    /*
     * 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 
     *    =>  n_digits = 3.
     */ 
    if(gc_ReqMoreInfo(crn, DESTINATION_ADDRESS, n_digits, 0, EV_ASYNC) != GC_SUCCESS)
    {
        /* process error return as shown */
         /* process error return as shown */
         gc_ErrorInfo( &gc_error_info );
         printf ("Error: gc_ReqMoreInfo() 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);
    } 
    return (0);
}
/*
 * The application must wait for the GCEV_MOREINFO event.
 * The cause of the event will indicate if all the digits have
 * been received. If digits have benn received, then collect 
 * the remaining digits by calling gc_GetCallInfo()
 *
 *
 * Application can then answer, accept, or terminate the call at this
 * point, based on the DNIS information.
 */ 

See Also

• gc_GetCallInfo( )
• gc_CallAck( )
• gc_SendMoreInfo( )

Click here to contact Telecom Support Resources