This transfer type is used with ETSI switches. There are two types of ECT, implicit linkage and explicit linkage. Ensure that the correct variant is provisioned in the configuration key transfertype. The user application uses the same functions and receives the same events, regardless of the type of ECT. Unlike TBCT, one of the calls involved in the transfer must be on hold. The application can put either of the calls on hold. If one of the calls is not on hold, the user application receives the event PKX_CALL_TASK_FAILED with event parameter p1 set to
PKX_ERROR_CALL_IN_WRONG_STATE.
The remaining messages are the same as for TBCT. The following diagram shows the steps in a successful ECT call transfer.
5.3.4.7 Terminating a Call
A call can be terminated by one of the following events: • The incoming call is rejected.
• The user application terminates the call. • The remote party terminates the call.
Rejecting incoming calls - If the user application does not wish to accept an incoming call, it calls the PKX_CALL_Drop function with the cause PKX_CALL_CAUSE_REJECTED after the
PKX_EVENT_GROUP_INCOMING_CALL event is retrieved from the event queue. This function must be used immediately after receiving the PKX_EVENT_GROUP_INCOMING_CALL event and before invoking any call function (other than PKX_CALL_GetInfo) using the callHandle specified in p1 of the event. The user application must call the PKX_CALL_Release function after rejecting the call.
The user application terminates the call - The user application calls the PKX_CALL_Drop function to terminate a call. The PKX_CALL_Drop function can be used to terminate a call after the incoming call has been accepted, or once a call has been established. The cause parameter should be set to PKX_CALL_DROP_CAUSE_NORMAL. The PKX_CALL_Drop function returns immediately, while lower-level processes send the appropriate messages to terminate the call. When the call has been disconnected, the user application is notified via a
PKX_EVENT_CALL_DROPPED event. After the PKX_EVENT_CALL_DROPPED event has been received, the user application must then call the PKX_CALL_Release function to free the resources used by the call. The user application receives a PKX_EVENT_CHANNEL_READY event once all active media operations started during the call are stopped and the channel is ready to process subsequent calls. If the disconnected call was joined to another call, the PKX_CALL_Drop function will not affect the second call or any channel connections established using the PKX_CHANNEL_FullDuplexConnect or PKX_CHANNEL_HalfDuplexConnect functions. It is the responsibility of the user application to terminate the second call and disconnect the channels using the PKX_CHANNEL_FullDuplexDisconnect or PKX_CHANNEL_HalfDuplexDisconnect functions.
The remote party terminates the call - When the remote party in a call hangs up, the user application receives a PKX_EVENT_CALL_DISCONNECTED event to indicate the call has been disconnected. The reason the call was disconnected is specified in the p1 parameter of the PKX_EVENT_CALL_DISCONNECTED event. The user application must then call the PKX_CALL_Release function to free the resources used by the call. The user
application receives a PKX_EVENT_CHANNEL_READY event once all active media operations started during the call are stopped and the channel is ready to process subsequent calls. If the disconnected call was joined to another call,
5
the PKX_CALL_Drop function will not affect the second call or any channel connections established using the PKX_CHANNEL_FullDuplexConnect or PKX_CHANNEL_HalfDuplexConnect functions. It is the responsibility of the user application to terminate the second call and disconnect the channels using the PKX_CHANNEL_FullDuplexDisconnect or PKX_CHANNEL_HalfDuplexDisconnect functions.
The following diagram shows the process flow for all methods of terminating a call.
Example
There are two examples shown below. The both examples are taken from the EventProcessing function in ivr.cpp source file of the Interactive Voice Response sample application. The first example demonstrates dropping a call. The second example demonstrates the processing of the events received when a call is terminated. When a
PKX_EVENT_CALL_DISCONNECTED event is received (the far-end terminated the call) or a
PKX_EVENT_CALL_DROPPED event is received (the application terminated the call), the application retrieves the call handle from the event and releases the call.
5.3.5 Media Processing
The following topics describe how to perform media processing functions on a channel: • Playing a stored message (pg. 78)
• Recording (pg. 84) • Collecting DTMF digits (pg. 88) • Sending DTMF digits (pg. 90) • Generating tones (pg. 91) • Detecting tones (pg. 93) • Detecting speech (pg. 94) • Fax Processing (pg. 100)
5.3.5.1 Playing a Stored Message
There are two methods of playing a stored message on a channel:
1. Queue one or more stored messages to the channel using the PKX_CHANNEL_PlayAddData function and then start playing the message(s) using the PKX_CHANNEL_Play function. The messages to be played can be stored in either a memory buffer or a file. A structure (PKX_TAudioData) is passed in as a parameter to the
PKX_CHANNEL_PlayAddData function. This structure defines where the stored message is located (in a memory buffer or in a file), which portion (offset and length) of the data to play, and whether this is the last segment of data to play.
2. Play one message file to a channel using the PKX_CHANNEL_PlayFile function. This method can play only one file.
Both the PKX_CHANNEL_PlayAddData and PKX_CHANNEL_PlayFile functions use a flags parameter that defines the audio properties of the data. See the Audio Flags (pg. 95) section for more information on the flags that can be passed to these functions.
Both the PKX_CHANNEL_Play and PKX_CHANNEL_PlayFile functions are passed a set of termination
conditions. See the Media Processing Termination Conditions (pg. 97) section for more information on conditions that can be used to terminate these functions. These functions can also be terminated using the
PKX_CHANNEL_Stop function.
5
The PKX_CHANNEL_PlayAddData function requires a PKX_TAudioData structure to be passed to it. This structure defines the location of the audio data block to be added to the queue of data to be played. The following table describes the fields defined in the PKX_TAudioData structure:
PKX_TAudioData
Field
Description
location.buffer Pointer to the memory buffer where the audio data block to play is stored. This location is used if the PKX_AUDIO_DATA_TYPE_FILE flag is not set in the typeFlags field.
NOTE: The user application must not free this memory buffer until it receives either the PKX_EVENT_CHANNEL_STOPPED_PLAY event or the
PKX_EVENT_CHANNEL_DONE_PLAY event.
location.fileName Name of the file where the audio data block to play is stored. This location is used if the PKX_AUDIO_DATA_TYPE_FILE flag is set in the typeFlags field.
offset The offset within the location to start processing the audio data.
length Number of bytes to play from the specified offset. The PKX_AUDIO_PLAY_ALL_DATA constant is used in this field to indicate that the play function should play all the audio data in the file. This constant cannot be used with buffer locations as it is not possible to determine the size of the buffer.
typeFlags Bit mask of indicators describing the data. These flags can be ORed together.
• PKX_AUDIO_LAST_BUFFER indicates to the PKX_CHANNEL_Play function that it should terminate playing after this data block is played. If this flag is not set on the last data block, a PKX_EVENT_CHANNEL_UNDERFLOW_PLAY event is raised and the play function pauses until more data is provided. This flag must be set only on the last data block, regardless of whether the data is stored in a memory buffer or a file.
• PKX_AUDIO_DATA_TYPE_FILE indicates the audio data to be played is located in the file location field.
The PKX_CHANNEL_Play and PKX_CHANNEL_PlayFile functions return immediately. Lower-level processes manage the playing of the audio data blocks. As these lower-level processes play the data, events are generated
indicating progress. The following table lists the events that can be generated while playing data: