2.4.1.10 Inbound Call Notification
After the TAPI DLL has opened a line device registering a media mode it can be notified when a call arrives. The Service Provider informs the TAPI DLL of a new incoming call via the LINE_NEWCALL callback message. This message passes the Service Provider's handle for the call to the TAPI DLL. The TAPI DLL returns its handle for the call. The Service Provider follows this with a LINE_CALLSTATE callback message. For an unanswered inbound call, the call state will be offering. The TAPI DLL can then invoke TSPI_lineGetCallInfo to find out information about the call. The fact that a call is offered may not necessarily imply the user is being alerted. A separate LINE_LINEDEVSTATE callback is made with a ringing indication to provide this information to the TAPI DLL.
Call information includes (among other things):
- bearer mode, rate - This is the bearer mode (voice, data) and data rate (in bps) of the call.
- media mode - The current media mode of the call. Unknown if this information is unknown.
- call origin - Indicates whether the call originated from an internal caller, an external caller, or unknown.
- reason for the call - Describes "why" the call is occurring. Possible reasons are: direct call, transferred from another number, busy-forwarded from another number, unconditionally forwarded from another number, the call was picked up from another number, a call completion request, or a callback reminder. Unknown if this information is not known.
- caller-ID - Identifies the originating party of the call. This can be in a variety of (name or number) formats, determined by what the switch or network provides.
- called-ID - Identifies the party originally dialed by the caller.
- connected-ID - Identifies the party that is actually connected to. This may be different from the called party if the call was diverted.
- redirection-ID - Identifies to the caller the number towards which diversion was invoked.
- redirecting-ID - Identifies to the diverted-to user the party from which diversion was invoked.
- user-to-user information - User-to-user information sent by the remote station (ISDN).
Note that depending on the telephony environment, not all information about a call may be available at the time the call is initially offered. For example, if caller ID is provided by the network between the first and second ring, caller-ID will be unknown at the time the call is first offered. When it becomes known shortly thereafter, a LINE_CALLINFO callback message will notify the TAPI DLL about the change in party ID information of the call.
If a new call arrives while another call already exists on the line or address, then similar notification and call information is supplied following the same mechanism as for any incoming call. If an app does not want any interference for a call from the switch or phone network, then it should secure the call. Securing a call can be done at the time the call is made via a parameter to TSPI_lineMakeCall, or later on when the call already exists via TSPI_lineSecureCall. The call will be secure until the call is disconnected. Securing a call may be useful for example when it is feared that certain network tones (e.g., call waiting) could destroy a call's media stream (e.g., fax).
TSPI_lineSecureCall
Secures an existing call from interference by other events.