Global Call API Library Reference: gc

gc_GetCallInfo( )

Termination Events | Cautions | Errors | Example | See Also

Name: int gc_GetCallInfo(crn, info_id, valuep)

Inputs:
CRN crn

call reference number

int info_id

call info ID

char *valuep

pointer to info buffer

Returns:
0 if successful

<0 if failure

Includes:
gclib.h

gcerr.h

Category:
interface specific

Mode:
synchronous

Platform and Technology:
All†

†See the Global Call Technology User's Guides for additional information.

Description

The gc_GetCallInfo( ) function retrieves information associated with the call. You can use this function at any time. The application can retrieve only one type of information at a time. The type of information that can be retrieved depends on the technology and whether the call is inbound or outbound (see Table 6).

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

Parameter

Description

crn call reference number

info_id ID of the information to be collected. See Table 6.

valuep buffer address where the requested information is stored

Table 6. gc_GetCallInfo( ) info_id Parameter ID Definitions

info_id Parameter

Definition

Technology

valuep Format

CALLINFOTYPE

Call related information: CHARGE or NO CHARGE for the current call.

E-1 CAS†

string

CALLNAME

Calling party's name

Analog

string

CALLTIME

Time and date call was made

Analog

string

CATEGORY_DIGIT

Category digit. Determined by the protocol/technology.

E-1 CAS (Springware only), SS7

character

CONNECT_TYPE

Defines the type of connection returned by call progress analysis. When gc_GetCallInfo( ) is used to retrieve information for an outbound call, one of the following is returned:

GCCT_DISCARDED

the call was disconnected by the remote end or the network and media type detection was discarded

GCCT_CAD

connection due to cadence break

GCCT_FAX

connection due to fax machine detection

GCCT_FAX1

connection due to CNG fax tone detection (PDKRT only)

GCCT_FAX2

connection due to CED fax tone detection (PDKRT only)

GCCT_INPROGRESS

media detection information is not yet available

GCCT_LPC

connection due to change in loop current

GCCT_PVD

connection due to positive voice detection

GCCT_NA

media type detection was not enabled

GCCT_PAMD

connection due to positive answering machine detection

GCCT_UNKNOWN

unknown media type answered

Analog, E-1 CAS, T-1 Robbed Bit†, R4 on DM3

character

DESTINATION_ADDRESS

Request the called party address (for example, DNIS).

E-1 CAS, T-1 Robbed Bit, Analog, ISDN PRI, R4 on DM3 (T-1 and ISDN), SS7†, IP

digits

ORIGINATION_ADDRESS

Request the calling party address (for example, ANI).

E-1 CAS, T-1 Robbed Bit, Analog, ISDN PRI, R4 on DM3 (T-1 and ISDN), SS7†, IP

digits

PRESENT_RESTRICT

The calling party presentation restriction:

0

presentation allowed

1

presentation restricted

2

address not available (national use only)

SS7

byte

U_IES

Unformatted user-to-user Information Elements (IEs) retrieved in CCITT format. The application needs to allocate sufficient memory (up to 256 bytes) to hold the retrieved IEs. The IEs are returned as raw data and must be parsed and interpreted by the application. Use the GC_IE_BLK data structure to retrieve unprocessed IEs.

See also the Global Call ISDN Technology User's Guide for DPNSS-related IEs.

ISDN

string

UUI

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

ISDN

string

† Not supported in all protocols; check your protocol in the Global Call Country Dependent Parameters (CDP) Reference or contact your Intel® Dialogic sales representative. The gc_GetCallInfo( ) function with an info_id parameter of CONNECT_TYPE should only be called after a GCEV_CONNECTED or GCEV_MEDIADETECTED event is received.

Termination Events

None

Cautions

An incoming Information Element (IE) is not accepted until the existing IE is read by the application. A GCEV_NOUSRINFOBUF event is sent to the application.
Multiple IEs in the same message - only happens to Network Specific Facility IE. When it happens, the library stores all IEs. If the combination of IEs is longer than the storage capacity, the library discards the overflow IEs and issues a GCEV_NOFACILITYBUF event to the application.
Ensure that the application verifies that the buffer pointed to by the valuep parameter is large enough to hold the information requested by the info_id parameter. For ANI and DNIS, the largest expected string length is defined by GC_ADDRSIZE.
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 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. 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_GetMetaEvent() or gc_GetMetaEventEx() (Windows) 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> 
/*
 * the variable info_id parameter(s) defines the information 
 * requested from the network.
 * The variable valuep stores the returned information.
 */ 
int get_call_info(CRN crn, int info_id, char *valuep)
{
    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_GetCallInfo(crn, info_id, valuep) != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_GetCallInfo() on linedev: 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

None

Name:	int gc_GetCallInfo(crn, info_id, valuep)
Inputs:	CRN crn	call reference number
	int info_id	call info ID
	char *valuep	pointer to info buffer
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	interface specific
Mode:	synchronous
Platform and Technology:	All† †See the Global Call Technology User's Guides for additional information.

Parameter	Description
crn	call reference number
info_id	ID of the information to be collected. See Table 6.
valuep	buffer address where the requested information is stored

**Table 6. gc_GetCallInfo( ) info_id Parameter ID Definitions**
info_id Parameter	Definition	Technology	valuep Format
CALLINFOTYPE	Call related information: CHARGE or NO CHARGE for the current call.	E-1 CAS†	string
CALLNAME	Calling party's name	Analog	string
CALLTIME	Time and date call was made	Analog	string
CATEGORY_DIGIT	Category digit. Determined by the protocol/technology.	E-1 CAS (Springware only), SS7	character
CONNECT_TYPE	Defines the type of connection returned by call progress analysis. When gc_GetCallInfo( ) is used to retrieve information for an outbound call, one of the following is returned: GCCT_DISCARDED the call was disconnected by the remote end or the network and media type detection was discarded GCCT_CAD connection due to cadence break GCCT_FAX connection due to fax machine detection GCCT_FAX1 connection due to CNG fax tone detection (PDKRT only) GCCT_FAX2 connection due to CED fax tone detection (PDKRT only) GCCT_INPROGRESS media detection information is not yet available GCCT_LPC connection due to change in loop current GCCT_PVD connection due to positive voice detection GCCT_NA media type detection was not enabled GCCT_PAMD connection due to positive answering machine detection GCCT_UNKNOWN unknown media type answered	Analog, E-1 CAS, T-1 Robbed Bit†, R4 on DM3	character
DESTINATION_ADDRESS	Request the called party address (for example, DNIS).	E-1 CAS, T-1 Robbed Bit, Analog, ISDN PRI, R4 on DM3 (T-1 and ISDN), SS7†, IP	digits
ORIGINATION_ADDRESS	Request the calling party address (for example, ANI).	E-1 CAS, T-1 Robbed Bit, Analog, ISDN PRI, R4 on DM3 (T-1 and ISDN), SS7†, IP	digits
PRESENT_RESTRICT	The calling party presentation restriction: 0 presentation allowed 1 presentation restricted 2 address not available (national use only)	SS7	byte
U_IES	Unformatted user-to-user Information Elements (IEs) retrieved in CCITT format. The application needs to allocate sufficient memory (up to 256 bytes) to hold the retrieved IEs. The IEs are returned as raw data and must be parsed and interpreted by the application. Use the GC_IE_BLK data structure to retrieve unprocessed IEs. See also the Global Call ISDN Technology User's Guide for DPNSS-related IEs.	ISDN	string
UUI	User-to-User Information. See also the Global Call ISDN Technology User's Guide for technology-specific information.	ISDN	string
† Not supported in all protocols; check your protocol in the Global Call Country Dependent Parameters (CDP) Reference or contact your Intel® Dialogic sales representative. The gc_GetCallInfo( ) function with an info_id parameter of CONNECT_TYPE should only be called after a GCEV_CONNECTED or GCEV_MEDIADETECTED event is received.

Click here to contact Telecom Support Resources