User's Manual

Voice API Programming Guide — June 2005 137
Caller ID
11.3 Accessing Caller ID Information
You can process caller ID information in your application in the following ways:
• For CLASS or ACLIP, the caller ID information is received from the service provider between
the first and second ring. Set the ring event in the application to occur on or after the second
ring. The ring event indicates reception of the CLASS or ACLIP caller ID information from
the CO.
• For CLIP or JCLIP, the caller ID information is received from the service provider before the
first ring. Set the ring event in the application to occur on or after the first ring. The ring event
indicates reception of the CLIP caller ID information from the CO.
The caller ID information is available for the call from the moment the ring event is generated (if
the ring event is set in your application as stated above) until one of the following occurs:
• If the call is answered (application channel goes off-hook), the caller ID information is
available until the call is disconnected (application channel goes on-hook).
• If the call is unanswered (application channel remains on-hook), caller ID information is
available until rings are no longer received from the CO (signaled by ring event, if enabled).
Notes: 1. If the call is answered before the caller ID information has been received from the CO, caller ID
information will not be available to the application.
2. If the application remains on-hook and the ring event is received before the caller ID information
has been received from the CO, caller ID information will not be available until the beginning of
the second ring.
The following voice API functions are used to access caller ID information received from the CO.
These functions are not supported on DM3 boards:
dx_gtcallid( )
Returns the calling line Directory Number (DN). Issue this function for applications that
require only the calling line DN.
dx_gtextcallid( )
Returns the requested caller ID message. Issue this function for each type of caller ID message
required.
dx_wtcallid( )
Waits for a specified number of rings and returns the calling station’s DN. This convenience
function combines the functionality of the dx_setevtmsk( ), dx_getevt( ), and dx_gtcallid( )
functions.
Contact your service provider to determine the caller ID options available from your CO. Based on
the options provided, you can determine which caller ID function best meets the application’s
needs.
To determine if caller ID information has been received from the CO, before issuing a
dx_gtcallid( ) or dx_gtextcallid( ), check the event data in the DX_EBLK event block structure.
When the ring event is received (set by the application as stated above), the event data field in the
event block is bit mapped and indicates that caller ID information is available when bit 0 (LSB) is
set to 1 (see the function code examples in the Voice API Library Reference).