Modifying API Messages

Overview

You can modify the PPL Event Request message to send customized data to the Excel platform and to receive PPL Event Indication messages with customized data from the Excel platform. Excel recommends using these PPL Event messages, because you can increase performance by reducing messaging between the host and the Excel platform. You also save time that you would normally use to develop features for host applications.

You can modify the PPL Event messages using predefined data sets, named Tag/Length/Value (TLV) blocks. For example, one TLV calculates the billing duration with a specified granularity, so the host applications do not need to track timestamps and other billing information.

See the API Reference for information on TLVs and on the PPL Variable Data ICB that transports them.

Atomic Functions

The following atomic functions enhance the ability of the host to send and receive the TLV ICB.

• AF 109: Tests for the presence of a specified buffer.

• AF 110: Moves/copies data from an incoming to an outgoing buffer.

• AF 111: Clears the given outgoing buffer:

• AF 356: Performs tasks jobs depending upon the arguments passed.

• AF 357: Moves the TLV from the working buffer (with the Switch Tag corresponding to that Host Tag in Arg2) to the GPR indicated by the index in Arg1.

• AF 358: Makes a new TLV from the values of the GPR indicated by Arg1, and puts the TLV into the working buffer (with the Switch Tag corresponding to the Host Tag indicated by Arg2)

• AF 359: Puts the DSP data list TLV into the working buffer.

The system time must be set correctly in the Excel platform to use the timestamp features.

The timestamp features do not work correctly during a Matrix Controller switchover. You may lose the start timestamp along with other TLVs.

Please note the maximum duration allowed is 1193.05 (approximately 50 days) hrs. If the duration requested is for more than 1193.05 hours, the duration indicator will reset and start from zero.

Use only the Tags defined in this document. Using an unlisted or reserved Tag may result in undesired operations.

Customization

This section describes possible customizations that you can make, using the EXS API.

Start Timestamp TLV

You can use the Start Timestamp TLV to do the following:

• Calculate the call duration.

• Mark the beginning of a call using any event that the CH component can access

• To record an event. For example, you could use the Start Timestamp TLV to record Event p and report to the host, and to time the stages of any protocol ladder (without overlap).

Figure 5-6 Using the Start Timestamp TLV

Current Timestamp TLV

You can use the Current Timestamp TLV with any combination of user-defined TLVs to report the time of that an event occurs (one at a time-- for example, one timestamp in one PPL Event Indication message). The figure below shows a call flow of this scenario.

Figure 5-7 Current Timestamp with User-Defined TLV

To concatenate a series of timestamps into a single report for the host, you can use custom TLVs with the Current Timestamp TLV in sequence.

In the next figure, the host receives a single PPL Event Indication message that contains the user-defined TLVs and the timestamps, in the same order in which they were created. Based on the user-defined TLVs, the host can match the timestamps to events.

For example, the timestamp after user-defined TLV 1 represents the time when Event P occurred and the timestamp after User-Defined TLV 2 represents the time when Event R is sent to the host.

Important! Do not concatenate so many timestamps into one message that the message exceeds its maximum size.

Figure 5-8 Multiple Timestamps with User-defined TLVs

User-Defined TLV

This TLV lets you send and receive any data to and from the Excel platform. The following are a few of the possible uses for the User-defined TLV:

• Label a particular call, such as: important/secret/private/public/from pay phone/from emergency and process the call based upon the label

• Temporarily store values for later use

• Inform the PPL state machine of an internal event. Based on the data in the user-defined TLVs, the state machine can take different branches.

• Use in combination with other TLVs which can have multiple instances in one message and identify them at the host with different meanings. For example, as described in the Current Timestamp TLV, you can use this to determine the events that triggered the multiple timestamps.

• Host application related sequencing.

• Host application related indexing.

Generic Counter TLV

This TLV provides a counter that increments or decrements and returns values to the host.

Using Multiple TLVs

You can dramatically reduce the message volume from the Excel platform to the host by using multiple TLVs of the same type in a single message. The following are some guidelines for using multiple TLVs of the same type:

• Avoid using the same user-defined TLV tag more than once in a single message. It may be difficult for the host to determine the order of messages from the Excel platform.

• Use a unique user-defined TLV to indicate the following: in the Current Timestamp TLV example user-defined TLV 1 represents the time of Event p, and User-defined TLV 2 represents the time of sending Event r.

• Try to use only one start timestamp TLV in a message. A start timestamp remains unchanged until you overwrite it with the Store Start Timestamp atomic function (AF 356). The duration is always calculated with respect to the last start timestamp stored.

• Avoid using the Generic Counter and Generic Tag TLVs more than once. Instead, use the user-defined TLV with different tag values to achieve the same result.

• To time a sequence of events, use the Duration TLV repeatedly instead of the Current Timestamp TLV.

DSP Resource Management

You can modify the default CH component state machine to initiate DSP services without host intervention. You cannot manage conferencing DSP resources with Call Control.