MARCO CONCEPTUAL

PKX_EVENT_CHANNEL_UNDERFLOW_PLAY Indicates the PKX_CHANNEL_Play asynchronous function has run out of audio data to play and has not received a PKX_TAudioData structure indicating it is the last block of audio data. The play function plays silence until more data is added, or the media function is terminated by meeting one of its termination conditions or the user application calls the PKX_CHANNEL_Stop function. PKX_EVENT_CHANNEL_DATAREADY_PLAY Indicates a block of data has been played. This event can be

used by the user application to maintain a constant number of pending play audio data blocks when playing a very long (or infinitely long) audio stream.

PKX_EVENT_CHANNEL_DONE_PLAY Indicates the PKX_CHANNEL_PlayFile or

PKX_CHANNEL_Play asynchronous function completed successfully.

PKX_EVENT_CHANNEL_STOPPED_PLAY Indicates the PKX_CHANNEL_PlayFile or PKX_CHANNEL_Play asynchronous function

terminated successfully using the PKX_CHANNEL_Stop function.

PKX_EVENT_CHANNEL_TERM_condition Indicates the PKX_CHANNEL_PlayFile or PKX_CHANNEL_Play asynchronous function terminated because one of its termination conditions has been met. The condition corresponds to the termination condition that was met. See Media Processing

Termination Conditions (pg. 97) for more information on which termination conditions are allowed for these functions.

If a second call to PKX_CHANNEL_PlayFile is executed before the first call has completed playing the data, the second PKX_CHANNEL_PlayFile returns a status of PKX_ERROR_CHANNEL_MEDIA_IN_USE.

The following diagrams demonstrate when these events are generated. While the examples refer to adding a buffer, the stored message can be provided in either a memory buffer or a file. The data is handled in the same way, regardless of how the data is provided and the user application should always set the last buffer flag only on the last data block provided.

In the first scenario, the PKX_CHANNEL_Play function is executed before any buffers have been added. The user application receives a PKX_ERROR_CHANNEL_AUDIO_DATA_NOT_AVAILABLE event.

In the second scenario, the buffer with the last buffer flag set is added before the PKX_CHANNEL_Play function is executed. The stored message is played on the channel and the user application receives two events,

PKX_EVENT_CHANNEL_DATAREADY_PLAY and PKX_EVENT_CHANNEL_DONE_PLAY, when the message has completed playing.

In the third scenario,the PKX_CHANNEL_PlayFile function is used to play data from a file. The stored message is played on the channel and the user application receives two events,

PKX_EVENT_CHANNEL_DATAREADY_PLAY and PKX_EVENT_CHANNEL_DONE_PLAY, when the message has completed playing.

In the fourth scenario, four buffers are added, with the fourth buffer having the last buffer flag set. Only the last buffer (in this example, the fourth buffer) should have the last buffer flag set. When the PKX_CHANNEL_Play function is executed, the buffers are played sequentially, in the order they were added. The user application receives a

PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. After the fourth buffer is played, the user application receives a PKX_EVENT_CHANNEL_DONE_PLAY event.

In the fifth scenario, four buffers are added, with the fourth buffer having the last buffer flag set. Only the last buffer (in this example, the fourth buffer) should have the last buffer flag set. When the PKX_CHANNEL_Play function is executed, the buffers are played sequentially, in the order they were added. The user application receives a

PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. In the middle of playing the third buffer, the PKX_CHANNEL_Stop function is executed. This causes the playback of the third buffer to stop. The rest of the third buffer and the fourth buffer are discarded. The user application receives one event, PKX_EVENT_CHANNEL_STOPPED_PLAY. No events are generated for the third or fourth buffers.

In the sixth scenario, one of the termination conditions specified in the PKX_CHANNEL_Play function has been met before all the data has been played. When the termination condition is met, the playing of the data stops and a PKX_EVENT_CHANNEL_TERM_xxx is generated. The xxx corresponds to the termination condition that was met. The rest of the third buffer and the fourth buffer are discarded.

In the seventh scenario, two buffers are added and then the PKX_CHANNEL_Play function is executed. While the initial two buffers are playing, two more buffers are added. As long as the additional buffers are added before the initial buffers have completed playing, a continuous audio stream is played. The user application receives a

PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. After the fourth buffer is played, the user application receives a PKX_EVENT_CHANNEL_DONE_PLAY event.

In the eighth scenario, two buffers are added before the PKX_CHANNEL_Play function is executed. The second buffer does not have the last buffer flag set. The first two buffers are played before the third buffer is added. Since there is no more data queued to be played and the last buffer flag was not set in the last buffer played, a

PKX_EVENT_CHANNEL_UNDERFLOW_PLAY event is generated. When the third and fourth buffers are added, the data continues playing.

Example

Two examples are shown:

• The first example is the playFile function in ivr.cpp of the Interactive Voice Response sample application. It

demonstrates playing a message stored in a file to a channel. The flag for WAVE file header is set. This indicates the specification of the encoding format and sampling rate are contained in the WAVE header appended to the file. No termination conditions are specified so the entire file is played.

• The second example is the queuePlayBuffer function in meetme.cpp of the MeetMe sample application. It demonstrates using a single buffer to store separate message data and then play them back. This approach saves memory if multiple channels need simultaneous access to play the same data.

5.3.5.2 Recording Audio Data From a Channel

There are two methods of recording audio data from a channel:

1. Start recording the audio data from a channel using the PKX_CHANNEL_Record function. The user application receives PKX_EVENT_CHANNEL_DATAREADY_RECORD events to indicate a block of recorded audio data is ready for the user application to retrieve using the PKX_CHANNEL_RecordGetData function.

NOTE: When a PKX_EVENT_CHANNEL_DATAREADY_RECORD event is returned by the

PKX_SYSTEM_WaitOnEvent function, the buffer of recorded data must be retrieved before the next call to PKX_SYSTEM_WaitOnEvent or the recorded data is lost.

2. Record the audio data from a channel directly to a file using the PKX_CHANNEL_RecordFile function.

Both the PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions are passed a flags parameter that defines the audio properties of the data recorded. See the Audio Flags (pg. 95) section for more information on the flags that can be passed to these functions.

Both the PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions are passed a set of termination conditions. See Media Processing Termination Conditions (pg. 97) for more information on conditions used to terminate these functions. These functions can also be terminated using the PKX_CHANNEL_Stop function.

The PKX_CHANNEL_RecordGetData function requires a PKX_TAudioData structure to be passed to it. This structure defines the buffer into which the audio data block recorded is copied. The following table describes the fields defined in the PKX_TAudioData structure used for the PKX_CHANNEL_RecordGetData function.

PKX_TAudioData

Field

Description

location.buffer Pointer to the memory buffer where the recorded audio data block is stored. location.fileName Not used.

offset Not used.

length IN: The number of bytes allocated by the user application for the buffer. If the size is

insufficient, the error PKX_ERROR_INSUFFICIENT_MEMORY_PROVIDED will be returned.

OUT: The actual number of bytes copied into the buffer. The number of bytes of data available in the record buffer is specified in the

PKX_EVENT_CHANNEL_DATAREADY_RECORD event. typeFlags Not used.

The PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions return immediately. Low-level processes manage the recording of the audio data blocks. As these low-level processes record the data, events are generated indicating progress. The following table lists the events that can be generated while recording data.

Play Event

Description

PKX_EVENT_CHANNEL_DATAREADY_RECORD Indicates the PKX_CHANNEL_Record asynchronous function has a block of recorded audio data ready for the user application to retrieve using the

PKX_CHANNEL_RecordGetData function. The p0 field of the event specifies the number of bytes available in the internal audio buffer.

PKX_EVENT_CHANNEL_OVERFLOW_RECORD Indicates the PKX_CHANNEL_Record asynchronous function has run out of internal memory to temporarily store the recorded audio data. Incoming audio data is lost until the user application retrieves a block of audio data using the PKX_CHANNEL_RecordGetData function. There are five 16 kB internal audio buffers. PKX_EVENT_CHANNEL_STOPPED_RECORD Indicates the PKX_CHANNEL_RecordFile or

PKX_CHANNEL_Record function has been

terminated using the PKX_CHANNEL_Stop function.

PKX_EVENT_CHANNEL_TERM_xxx Indicates the PKX_CHANNEL_RecordFile or PKX_CHANNEL_Record function has been

terminated because one of its termination conditions has been met. See Media Processing Termination

Conditions (pg. 97) for more information on which termination conditions are allowed for these functions. The following diagrams demonstrate when these events are generated.

In the first scenario, the PKX_CHANNEL_RecordFile function is executed. The audio data on the channel is recorded to the file until one of the termination conditions specified in the PKX_CHANNEL_RecordFile function call is met. When the termination condition is met, the recording of the data stops, all the recorded data is written to the file, the file is closed, and a PKX_EVENT_CHANNEL_TERM_xxx is generated. The xxx corresponds to the

termination condition that was met.

In the second scenario, the PKX_CHANNEL_Record function is executed. As each buffer of audio data is recorded, a PKX_EVENT_CHANNEL_DATAREADY_RECORD event is generated. The user application periodically retrieves the recorded audio data buffers using the PKX_CHANNEL_RecordGetData function and stores or processes the data. The user application stops the recording of audio data using the PKX_CHANNEL_Stop function. This causes recording of audio data on the channel to stop, a final

PKX_EVENT_CHANNEL_DATAREADY_RECORD event to be generated, and a PKX_EVENT_CHANNEL_STOPPED_RECORD event to be generated.

In the third scenario, the PKX_CHANNEL_Record function is executed. GP has only five internal audio buffers. The user application receives five PKX_EVENT_CHANNEL_DATAREADY_RECORD events but does not retrieve any of the audio data. A PKX_EVENT_CHANNEL_RECORD_OVERFLOW event is generated and audio data recording stops. Later, the user application executes a PKX_CHANNEL_RecordGetData function, retrieving the data from one of the internal audio data buffers. This frees the audio buffer and audio data recording restarts. The user application stops the audio data recording using the PKX_CHANNEL_Stop function. This causes audio data recording on the channel to stop, a final PKX_EVENT_CHANNEL_DATAREADY_RECORD event to be generated, and a PKX_EVENT_CHANNEL_STOPPED_RECORD event to be generated. The audio data received or transmitted on the channel between the generation of the

PKX_EVENT_CHANNEL_RECORD_OVERFLOW event and the PKX_CHANNEL_RecordGetData function call is lost.

GP uses large audio buffers (16 kB) for record functions. The size of these buffers may become an issue to some user applications processing the audio because they introduce latency. A user application must wait until the entire buffer is filled with data before getting an event indicating that audio data is available to be processed. Refer to section

Configuring a Channel (pg. 125) for information on customizing the recording buffer size.

Tips

Performing active call logging when two or more calls are conferenced together requires a virtual channel to be used to record the audio.

Example

There are three examples shown:

• The first example is the function recordFile and can be found in the ivr.cpp source file of the Interactive Voice Response sample application. It demonstrates recording the audio data from a channel directly into a file. The encoding format is set to mu-Law, the sampling rate is set to 8 kHz, and the flag to play an initial beep to indicate

recording is being performed is set. Two termination conditions are set for the recording process, either the pound (#) phone key tone or a period of silence is detected on the channel.

• The second example is taken from from the handleIvrEvents function in ivr.cpp source file of the Interactive Voice Response sample application. It demonstrates the processing required when one of the termination conditions has been met. In this example the call is dropped.

• The third example is taken from the the EventProcessing function in the meetme.cpp source file of the MeetMe sample application. It shows how to record data to a buffer. This approach allows the application to access the data as it is recorded instead of waiting until one of the termination conditions is met to retrieve the entire block of data from a file. The example shows data being appended to the end of a buffer to avoid overwriting previously recorded data.

5.3.5.3 Collecting DTMF Digits From a Channel

The user application uses PKX_CHANNEL_CollectDigits to apply termination conditions to the collection of DTMF digits on a channel. The user application can use the PKX_CHANNEL_GetNumberOfDigits function to determine the number of digits in the received digit buffer for a specified channel. The PKX_CHANNEL_GetDigits function copies the specified number (or fewer, if there are insufficient digits in the channel digit buffer) of digits from the channel digit buffer into a local buffer supplied by the user application. Digits copied into a local buffer are removed from the channel digit buffer. The digits are stored in the local buffer as a null (\0) terminated string, where each digit is an ASCII character (not a numerical value). The user application must ensure the local buffer is large enough to receive all the requested digits plus the null terminator. The user application can use the strlen function on the local buffer to determine the actual number of digits returned.

A channel digit buffer can store up to 127 digits. When 127 digits have been collected, without any of the digits having been retrieved by a PKX_CHANNEL_GetDigits function call, additional digits generated on the channel are not placed in the buffer. A PKX_EVENT_CHANNEL_DIGIT_BUFFER_FULL event is generated for every DTMF digit received that is not put in the buffer because the buffer is full: p0 of this event is set to 127, and p1 of this event specifies the DTMF digit received. Subsequent calls to the PKX_CHANNEL_GetDigits function frees space in the channel digit buffer, and digits received after the PKX_CHANNEL_GetDigits function call are collected up to the limit of the channel digit buffer.

The PKX_CHANNEL_ClearDigits function deletes any digits stored in the channel digit buffer.

The PKX_CHANNEL_Stop function is used to stop the termination conditions applied to the collection of DTMF digits on a channel. When DTMF digits are being collected on a channel and the PKX_CHANNEL_Stop function is

5

executed on that channel, a PKX_EVENT_CHANNEL_STOPPED_COLLECT_DIGITS event is generated. The p0 field of this event specifies the number of digits in the channel digit buffer when the PKX_CHANNEL_Stop was executed.

Whenever a DTMF digit is detected on a channel (whether PKX_CHANNEL_CollectDigits has been called or not), a PKX_EVENT_CHANNEL_DTMF event is generated, indicating the DTMF digit has been received over the channel. The DTMF digit is specified as an ASCII character in the p0 field of the event.

The following diagram shows the events generated and the state of the internal digit buffer as DTMF digits are received.

In the diagram, a PKX_EVENT_CHANNEL_DTMF event is generated for each digit received. The

PKX_CHANNEL_CollectDigits function (with a termination condition of maxDigits=3) is executed after one digit has been received. After the third digit is received, a PKX_EVENT_CHANNEL_TERM_MAX_DIGITS event is generated. The PKX_CHANNEL_CollectDigits function (with a termination condition of maxDigits=3) is executed again, after four digits have been received. Since there are four digits in the buffer, a

PKX_EVENT_CHANNEL_TERM_MAX_DIGITS event is generated immediately. The

PKX_CHANNEL_GetDigits function is called with four specified as the number of digits to transfer. Four digits are removed from the internal digit buffer and copied into the local buffer. The PKX_CHANNEL_CollectDigits

function (with a termination condition of maxDigits=5) is executed after the four digits have been removed from the buffer. The PKX_CHANNEL_Stop function is executed before the ninth digit is received. A

PKX_EVENT_CHANNEL_STOPPED_COLLECT_DIGITS event is generated. This means that

PKX_EVENT_CHANNEL_TERM_MAX_DIGITS is NOT generated after the ninth digit is received. The digits remaining in the channel internal digit buffer may still be retrieved using the PKX_CHANNEL_GetDigits function.

NOTE: If DTMF detection has been disabled using the PKX_CHANNEL_SetConfig API function, digit collection will not be possible, however, no error will be generated.

Example

There are three examples: the first example is the function selectOption, and the second and third examples are taken from from the handleIvrEvents function. All examples can be found in ivr.cpp source file of the Interactive Voice Response sample application. The first example demonstrates the setting of termination conditions on the collection of digits on a channel. Two termination conditions are specified, a digit being received, or no tone being received for a timeout period. The second example demonstrates getting one digit from the channel digit buffer. Depending on the digit received, the application plays a canned message or plays a prompt to the caller that instructs them to record a message. The third example demonstrates the action taken if the timeout termination condition is met. In this example, the call is dropped.

5.3.5.4 Sending DTMF Digits to a Channel

The user application uses the PKX_CHANNEL_PlayDigits function to send DTMF digits to a channel. The user application passes a null terminated string of ASCII characters for the DTMF keys to this function. The ASCII characters supported are: 0 to 9; a to d; A to D; P; T; W; ,; &; #; and *. If any other characters are contained in the string, the PKX_CHANNEL_PlayDigits function returns a

PKX_ERROR_CHANNEL_INVALID_PLAY_DIGIT_SPECIFIED error status.

The DTMF tones are played as a continuous stream. The tone on and off durations are defined in the root

5

configuration file. See Tone Generation for more information on the specification of tone on and off durations.

When the string of DTMF digits has been transmitted, a

PKX_EVENT_CHANNEL_DONE_TONE_GENERATION event is generated.

The generation of a string of DTMF digits can be terminated using the PKX_CHANNEL_Stop function. The generation of DTMF tones stops, with any unplayed tones discarded. A

PKX_EVENT_CHANNEL_STOPPED_TONE_GENERATION is generated. The p0 field of this event specifies the last tone played.

5.3.5.5 Generating Tones on a Channel

The tone groups GP can generate are listed in the [tone_generation] section of the root configuration file. To generate a tone group on a channel, the user application uses the PKX_CHANNEL_PlayTone function. The parameters passed to this function are:

• The channel handle.

• The index to the entries of the [tone_generation] section of the GP configuration file.

• The termination conditions to stop the tone playing. See Media Processing Termination Conditions (pg. 97) for more information on the termination conditions that may be used for this function.

NOTE: A tone group is a collection of single-frequency tones. For example: a DTMF tone is a tone group made up of two single-frequency tones. GP function calls always deal with the tone group.

The tone group is played for the total of the on and off duration specified in the tone definition unless a termination condition is met or the PKX_CHANNEL_Stop function is executed on that channel. When the tone group has been