The notion of bearer mode corresponds to the quality of service requested from the network for establishing a call. It is important to keep bearer mode separate from media mode. The media mode of a call describes the type of information that is exchanged over the call of a given bearer mode. As an example, the analog telephone network (PSTN) only provides 3.1 kHz voice grade quality of service (bearer mode). However, a call with this bearer mode can support a variety of different media modes such as voice, fax, or data modem. Media modes require certain bearer modes. The Telephony API only manages the bearer modes by passing the bearer mode parameters on to the network. Media modes are fully managed through the appropriate media mode APIs, although some limited support is provided in the Telephony API.
The bearer mode of a call is specified when the call is set up, or is provided when the call is offered. With line devices able to represent channel pools, it is possible for a service provider to allow calls to be established with wider bandwidth. The rate (or bandwidth) of a call is specified separately from the bearer mode, allowing an application to request arbitrary data rates.
The bearer modes defined in the API are:
voice - Regular 3.1 kHz analog voice service. Bit integrity is not assured.
speech - G.711 speech transmission on the call.
multiuse - As defined by ISDN.
data - Unrestricted data transfer. The data rate is specified separately.
alternate speech and data - The alternate transfer of speech and unrestricted data on a call (ISDN).
non call-associated signaling - This provides a clear signaling path from the application to the service provider.
Although support for changing a call's bearer mode or bandwidth is limited in networks today, the API provides an operation to request a change in a call's bearer mode and/or data rate. The operation is lineSetCallParams.
lineSetCallParams
Request a change in the call parameters of an existing call.
When a call is in the connected state, information can be transported over the call. A call's media mode provides an indication of the type of information (e.g., data type, higher level protocol) of this media stream. The Telephony API allows applications to be provided with a callback notification about changes in a call's media mode. The notification provides an indication of the call's new media mode. Note that the service provider decides how it wants to make this determination. For example, the provider could use signal processing of the media stream to determine media mode, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media mode determination is done, the app is simply informed about media mode changes on a call.
The media modes defined by the API include:
unknown - The media mode of the call is not currently known; the call is unclassified.
interactive voice - Voice energy was detected on the call, and the call is handled as an interactive voice call with a human at the application's end.
automated voice - Voice energy was detected on the call, and the call is handled as a voice call but with no human at the application's end (i.e., this could be an answering machine application).
digital data - A digital data stream of unspecified format.
G3 fax - A group 3 fax session on the call.
G4 fax - A group 4 fax session on the call.
data modem - A modem session on the call. Note that current modem protocols require the called station to initiate the handshake. For an inbound data modem call, the application can typically make no positive detection. How the service provider makes this determination is its choice. For example, a period of silence just after answering an inbound call may be used as a heuristic to decide that this might be a data modem call.
teletex, videotex, mixed - These corresponds to the telematic services with the same names.
TDD - The call's media stream uses the Telephony Devices for the Deaf protocol.
ADSI - An Analog Display Services Interface session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.
Media monitoring can be enabled/disabled on a per call per app basis via lineMonitorMedia. The app specifies which media modes it is interested in monitoring. If enabled, the detection of a media mode causes the app to be notified via the LINE_MONITORMEDIA callback. The callback provides the call handle on which the media mode change was detected as well as the new media mode.
lineMonitorMedia
Enables or disables media mode notification on a specified call.
LINE_MONITORMEDIA
Notifies the application about a media mode change.
There is a distinction between the media mode of a call as reported by lineGetCallInfo, and the media mode event reports by LINE_MONITORMEDIA messages. A call's media mode is determined exclusively by owner applications of the call and is not automatically changed by media monitoring events. The one exception is the initial media mode determination of a call that may be performed by the API implementation to select the initial owner. One could argue that in that case, the API implemention is the owner of the call.
Default media mode monitoring is performed for the media modes for which the line device has been opened. This allows an inbound call's media mode to be determined before the call is handed to an application based on what the applications demand.
Note that the scope of a call's media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.
An application can obtain device IDs for various Windows device classes associated with an opened line by invoking lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device ID for the device of the given device class that is associated with the open line device, address, or call. If the device class is line, then the device ID of the line device is returned. If the device class is mci waveaudio, then the device ID of an mci waveaudio device is returned (if supported) that allows the recording/playback etc. of audio over the call on the line.
lineGetID
Retrieves a device ID associated with the specified open line, address, or call.
The app can use the returned device ID with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if your application needs to use the line as a waveform device, it will first have to call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical wave form data format supported by telephony in North America is 8-bit m-law at 8000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.
To subsequently open a line device for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device-specific, and each implementation has a number of options for implementing this function.
Digit monitoring monitors the call for digits. The API provides for digits to be signaled according to two methods (digit modes):
pulse - Digits are signaled as pulse/rotary sequences. Note that for detection, these pulses manifest themselves as nothing more than sequences of audible clicks. Valid pulse digits are '0' through '9'.
DTMF - Digits are signaled as DTMF (Dual Tone Multiple Frequency) tones. Valid DTMF digits are '0' through '9', 'A'. 'B', 'C', 'D', '*', and '#'. Both the beginning and the down edge of DTMF digits can be monitored.
Digit monitoring can be enabled/disabled on a per call per app basis via lineMonitorDigits. If enabled, all detected digits causes the app to be notified via the LINE_MONITORDIGITS callback. The callback provides the call handle on which the digit was detected as well as the digit value and the digit mode.
lineMonitorDigits
Enables or disables digit detection notification on a specified call.
LINE_MONITORDIGITS
Notifies the application about a digit detection.
Note that the scope of digit monitoring is bound by the lifetime of the call. Digit monitoring on a call ends as soon the call disconnects or goes idle.
Tone monitoring monitors the media stream of a call for specified tones. A tone is described by its component frequencies and cadence. An implementation of the API may allow several different tones to be monitored simultaneously. An application can "tag" each tone in order to be able to distinguish the different tones for which it requests detection.
Tone monitoring can be enabled/disabled on a per call per app basis via lineMonitorTones. If enabled, a detected tone causes the app to be notified via the LINE_MONITORTONE callback. The callback provides the call handle on which the tone was detected as well as the application's "tag" for the tone.
lineMonitorTone
Specifies which tones to detect on a specified call.
LINE_MONITORTONE
Notifies the application about a tone detection.
The scope of tone monitoring is bound by the lifetime of the call. Tone monitoring on a call ends as soon the call disconnects or goes idle.
Note that the monitoring of tones, digits, or media modes often requires the use of resources of which the service provider may only have a finite amount. A request for monitoring may be rejected if resources needed are not available. For the same reason, an application should disable any monitoring that is not needed.
An application can request the execution of a limited set of media control operations on the call's media stream triggered by telephony events. Although an application is encouraged to use the media API specifically defined for the media mode, media control can yield a significant performance improvement for client/server implementations. The operation lineSetMediaControl allows an application to specify a list of tuples specifying a telephony event and the associated media control action.
The telephony events that can trigger media control activities are:
detection of a digit - The app provides a list of specific digits and the media control action each of them triggers.
detection of a media mode - The app provides a list of media modes and the media control actions a transition into the media mode triggers.
detection of a specified tone - The app specifies a list of tones and the media control action each tone detection triggers.
detection of a call state - The app specifies a list of call states and the media control action each transition to the call state triggers.
The media control actions are defined generically for the different media modes. Not all media streams may provide meaningful interpretations of the media control actions. The operations should map well to audio streams.
start - Starts the media stream.
reset - Resets the media stream.
pause - Stops or pauses the media stream.
resume - Starts or resumes the media stream.
rate up - Increases the rate (i.e., speed) of the media stream by a implementation-defined amount.
rate down - Decreases the rate (i.e., speed) of the media stream by a implementation-defined amount.
rate normal - Returns the rate (i.e., speed) to normal.
volume up - Increases the volume (i.e., amplitude) of the media stream.
volume down - Decreases the volume (i.e., amplitude) of the media stream.
volume normal - Returns the volume (i.e., amplitude) to normal.
lineSetMediaControl
Sets up a call's media stream for media control.
The scope of media control is bound by the lifetime of the call. Media control on a call ends as soon the call disconnects or goes idle. Only a single media control request can be outstanding on a call across all apps.
Besides enabling digit monitoring and being notified of digits one at a time, an application can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is the application notified. Digit gathering is useful for functions such as credit card number collection. The application invokes lineGatherDigits specifying a buffer to fill with digits. Digit gathering terminates when one of a number of conditions is true.
The requested number of digits has been collected.
One of multiple termination digits is detected. The termination digits are specified to lineGatherDigits, and the termination digit is placed in the buffer as well.
One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an inter-digit timeout, specifying the maximum duration between successive digits.
Digit gathering is canceled explictly by invoking lineGatherDigits again with either another set of parameters (e.g., a new buffer) to start a new gathering request or by using a NULL digit buffer parameter to simply cancel.
When terminated for whatever reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering. Note that only a single digit gathering request can be outstanding on a call at any given time across all applications that are owners of the call.
lineGatherDigits
Performs the buffered gathering of digits on a call.
Note that digit gathering and digit monitoring may be enabled on the same call at the same time. In that case, the app will receive a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.
Generating Inband Digits and Tones
Once in the connected state, information can be transmitted over a call. Two operations are provided that allow end-to-end inband signaling between the application and remote station equipment such as an answering machine. One operation is lineGenerateDigits, which signals digits over the voice channel. Digits can be signaled as either rotary/pulse sequences or as DTMF tones. The other operation is lineGenerateTone, which enables the application to generate one of a variety of multi-frequency tones over the media stream. This generates telephony tones, such as ringback, beep, busy, as well as arbitrary multi-frequency multi-cadenced tones.
lineGenerateDigits
Generates inband digits on a call.
lineGenerateTone
Generates a given set of tones inband on a call.
Only one digit or tone generation can be in progress on a call at any one time. When digit or tone generation completes, a LINE_GENERATE message is sent to the application that requested the generation. In the case of generation of multiple digits, only a single message is sent back after all digits have been generated. Calling lineGenerateDigits or lineGenerateTone while digit or tone generation is in progress will abort the generation currently in progress and send the LINE_GENERATE message the application whose generation was aborted with an cancel indication.
Call Accept, Reject, and Redirect
In environments like ISDN, call offering is separate from alerting. In fact, after a call has been offered to an application, a time window exists during which the application has a number of options.
The application can simply answer the call using lineAnswer (described earlier).
The application can reject the offering call using lineDrop, which will revert the offering call to the idle state.
The application can accept the call using lineAccept, which will initiate alerting to both the caller as ringback, and the called party as ring.
The application can redirect the call using lineRedirect, which deflects the offering call elsewhere. The call will revert to the idle state.
lineAccept
Accepts an offered call and start alerting of both caller (ringback) and called party (ring).
lineRedirect
Redirects an offering call to another address.
Most PBXs can associate multiple calls with a single line. A call can be placed on hard hold. This frees up the user's line/address to make other calls. An application can place a call on hold by invoking lineHold. An application may retrieve an on-hold call by invoking lineUnhold.
Hard hold is different from a consultation hold. A call is automatically placed on consultation hold, for example, when a call is prepared for transfer or conference.
lineHold
Places the specified call on hard hold.
lineUnhold
Retrieves a held call.
The Telephony API provides two mechanisms for call transfer: blind transfer and consultation transfer. In blind transfer (or single-step transfer), an existing call is transferred to a specified destination address in one phase using lineBlindTransfer. Under a consultation transfer, the existing call is first prepared for transfer using lineSetupTransfer. This places the existing call on consultation hold, and identifies the call as the target for the next transfer completion request. lineSetupTransfer also allocates a consultation call that can be used to establish the consultation call with the party to be transferred to. The application can dial the extension of the destination party on the consultation call (using lineDial), or it can drop and deallocate the consultation call and instead activate an existing held call (using lineUnhold), if supported by the switch.
While the initial call is on consultation hold and the consultation call is active, the application can toggle between these calls via lineSwapHold.
Finally, the application completes the transfer in one of two ways using lineCompleteTransfer:
Transfer the call on transfer hold to the destination party. Both calls will revert to the idle state.
Enter a three-way conference. A new call handle is created to represent the conference and this handle is returned to the application.
lineSetupTransfer
Prepares a specified call for transfer to another address.
lineCompleteTransfer
Transfers a call that was set up for transfer to another call, or enter a three-way conference.
lineBlindTransfer
Transfers a call that was set up for transfer to another call.
lineSwapHold
Swaps the active call with the call currently on consultation hold.
Conference calls are calls that include more than two parties simultaneously. Conference calls can be set up using either a switch-based conference bridge or an external server-based bridge. Typically, only switch-based conferencing will allow the level of conference control provided by the API. In server-based conference calls all participating parties dial into the server which mixes all the media streams together and sends each participant the mix; there may be no notion of individual parties in the conference call, only that of a single call between the application and the bridge server.
A conference call can be established in a number of ways, depending on device capabilities.
A conference call may be able to start out as a regular two-party call, e.g., a call established via lineMakeCall. Once the two-party call exists, additional parties can be added, one at a time. Preparing to add the third party establishes the conference call via lineSetupConference, this takes the original two-party call as input, allocates a conference call, connects the original call to the conference, and allocates a consultation call whose handle is returned to the application.
The application can then use lineDial on the consultation call to establish a connection to the next party to be added. lineDrop can be used to abandon this call attempt. The third party is added via lineAddToConference, which specifies both the conference call and the consultation call.
To add additional parties once a conference call (handle) exists uses linePrepareAddToConference, which specifies the conference call handle and returns a consultation call handle to the app. Once the consultation call exists, it can be added via lineAddToConference (as above).
A conference call may have to be established via lineSetupConference, without an existing two-party call. This returns a handle for the conference call, and allocates a consultation call. After a period of consultation, the consultation call can be added via lineAddToConference. Additional parties are added via linePrepareAddToConference followed by lineAddToConference.
A final mechanism for establishing a three-way conference call is by resolving a transfer request for three-way conference. In this scenario, a two-party call is established as either an inbound or outbound call. Next the call is placed on transfer hold via lineSetupTransfer which returns a consultation call handle. After a period of consultation, the application may have the option to resolve the transfer setup by selecting the three-way conference option which conferences all three parties together in a conference call via lineCompleteTransfer with the conference option (instead of the transfer option). Under this option, a conference call handle representing the conference call is allocated and returned to the application.
Once a call becomes a member of a conference call, the member's call state reverts to conferenced. The state of the conference call typically becomes connected. The call handle to the conference call and all the added parties remain valid as individual calls. LINE_CALLSTATE events can be received about all calls, for example, if one of the members disconnects by hanging up, an appropriate call state message may inform the application of this fact; such a call is no longer a member of the conference.
As is the case with call transfer, the application may toggle between the call consultation call and the conference call using lineSwapHold.
Use the call handle for the member calls to later remove the call from the conference. Do this by invoking lineRemoveFromConference on the call handle. Note that this operation is not commonly available in its fully general form. Some switches may not allow it at all, or only allow the most recently added party to be removed. The line's device capabilities describe which flavor of lineRemoveFromConference is possible.
lineSetupConference
Prepares a given call for the addition of another party. The capabilities of the addressed line device may limit the number of parties conferenced in a single call and whether or not a conference starts out with a normal two-party call.
linePrepareAddToConference
Prepares for adding a party to an existing conference call by allocating a consultation call that can later be added to the conference call which is placed on conference hold.
lineAddToConference
Adds a consultation call to an existing conference call.
lineRemoveFromConference
Removes a party from a conference call.
Two forms of call parking are provided: directed call park and non-directed call park. In directed call park, the application specifies the destination address where the call is to be parked. This roughly behaves like a call transfer to the destination address, but it doesn't alert or time out as a transfer would.
In non-directed call park, the switch returns to the application the address where it parked the call. In either case, the function linePark is used to park a call.
A parked call can later be retrieved. The application specifies the park address to lineUnpark which returns an call handle to the unparked call. Appropriate LINE_CALLSTATE messages will be sent to the application as the call is reconnected.
linePark
Parks a given call at another address.
lineUnpark
Retrieves a parked call.
Forwarding affects the treatment by the switch or network of incoming calls destined for a given address. The application can specify call forwarding conditions based on origin of call (internal, external, selective based on caller ID), status of the address (busy, no answer, unconditionally), and destination address where calls are to be forwarded. When the specified conditions are met for an incoming call, the switch deflects the incoming call to the specified destination number. Note that because the switch performs the forwarding action, the application will typically not know when a call has been forwarded.
The lineForward function provides a combination of call forwarding and do-not-disturb features. LineForward also cancels any or all of the forwarding requests currently in effect. Some switches require that a call be established to the forwarding address in order for call forwarding to be initiated. On such systems, lineForward allocates a consultation call and returns the handle for it to the application. The consultation call can be used as any other call. After the connection is established, forwarding confirmation is received from the switch, and the call is dropped (using lineDrop), is forwarding in effect. A LINE_ADDRESSSTATE message with a forwarding indication informs the application about changes in an address' forwarding status.
lineForward
Set or cancel call forwarding requests.
Note that it may be impossible for a service provider to know at all times what forwarding is in effect for an address. Forwarding may be canceled or changed in ways that make it impossible for a service provider to be informed of this fact.
Call pickup allows an application to answer a call that is alerting at another address. The application invokes linePickup by identifying the target of the pickup and is returned a call handle for the picked up call. There are several ways to specify the target of the pickup request. First, specify the address (extension) of the alerting party. Second, if no extension is specified and the switch allows it, the application can pick up any ringing phone in its pickup group. Third, some switches require a group ID to identify the group to which the ringing extensions belongs.
After the call has been picked up, the call is diverted to the application and the app is sent appropriate LINE_CALLSTATE messages for the call. An application can invoke lineGetCallInfo to find out information about the picked up call, if provided by the switch.
linePickup
Pick up a call that is alerting at another number.
When making an outbound call, the unavailability of certain resources may prevent the call from reaching the connected state; e.g., if the destination party is busy or doesn't answer. Unavailable resources include trunk circuits as well as the destination party's station. LineCompleteCall allows the application to specify how its wants to complete a call that cannot be completed normally. The application has the following options:
Camp on to queue the call until the call can be completed.
Call back requests the called station to return the call when it returns to idle. Answering the call back may automatically re-initiate (i.e., redial) the connection request.
Intrude allows the application to barge in to the existing call.
Message (aka "leave word calling") allows the application to send one of a small number of predefined messages to the destination. These messages can be text shown on the phone's display, a voice message left for the user, etc.
A call completion request can be canceled via lineUncompleteCall. Multiple call completion request can potentially be outstanding for a given address at any one time. To identify individual requests, the implementation returns a completion ID. When a call completion request completes and results in a new call, then the call completion ID is available in the LINECALLINFO data structure returned by lineGetCallInfo. Canceling a call completion request in progress also uses this call completion ID.
lineCompleteCall
Places a call completion request.
lineUncompleteCall
Cancels a call completion request.
Applications that use Simple Telephony services only initiate requests that are temporarily queued by the Telephony DLL. Another application, the request recipient application, is responsible for retrieving these requests and executing them on behalf of the Simple Telephony application. Three such request submission services are defined:
tapiRequestMakeCall - requests the establishment of a voice call. The requesting app does not control the call.
tapiRequestMediaCall and tapiRequestDrop - requests the establishment of a media call. The requesting app is informed about the status of the connection via the TAPI_REPLY message. The only operation that can be requested on the call after tapiRequestMediaCall has been issued is tapiRequestDrop.
lineRequestLogEntry - requests that a comment be added to the call log of a specified call.
The API allows the user to establish different or the same request recipient applications for each of these sub services. An application becomes a request recipient by registering for the sub service or services via lineRegisterRequestRecipient. The application selects which sub services (or request modes) it wants to handle. If multiple applications register for the same request mode, a priority scheme is used to allow the user to select which application he prefers to handle the requests. This priority scheme is identical to that used for call handoff and routing of incoming calls.
Once a request has been made, a LINE_REQUEST message is sent to the highest priority application that has registered for that request's request mode. The message carries an indication of the request's mode. The request recipient app can then invoke lineGetRequest to get the next request. This removes the request from the Telephony DLL. The request parameters are copied in an application-allocated request buffer. The size and interpretation of the contents of the buffer are dependent on the request mode of the request.
lineRegisterRequestRecipient
Registers or deregisters the application as a request recipient for the specified request mode.
LINE_REQUEST
Notifies the request recipient application that a new request has arrived.
lineGetRequest
Gets the next request from the Telephony DLL.
lineRequestLogEntry
Requests that a comment be added to the call log.