PPL Table Download 0x00D6

SwitchKit Name

PPLTableDownload

Type

EXS API and SwitchKit API message

Description

Use this message to download PPL tables that are subsequently used to create a PPL protocol.

Before using this message, the host must first establish the table to be downloaded using the PPL Table Initiate Download message. The PPL Table Download message is then used to pass the table data to the Excel platform.

If the table data exceeds the maximum length allowed for one message, you will have to use more than one of these messages. You must send them sequentially because the Excel platform maintains the offset into the table on successive commands.

Sent by

Host

SwitchKit Code

C Structure

typedef struct {

unsigned short ComponentID;

UBYTE TableType;

UBYTE TableID;

UBYTE Data[249];

} XL_PPLTableDownload;

C Structure Response

typedef struct {

unsigned short Status;

UBYTE DataSize;

UBYTE ErrorType;

UBYTE Data[250];

} XL_PPLTableDownloadAck;

C++ Class

class XLC_PPLTableDownload : public XLC_OutboundMessage {

public:

unsigned short getComponentID() const;

void setComponentID(unsigned short x);

UBYTE getTableType() const;

void setTableType(UBYTE x);

UBYTE getTableID() const;

void setTableID(UBYTE x);

const UBYTE *getData() const;

UBYTE *getData();

void setData(UBYTE *x);

};

C++ Class Response

class XLC_PPLTableDownloadAck : public XLC_AcknowledgeMessage {

public:

unsigned short getStatus() const;

void setStatus(unsigned short x);

UBYTE getDataSize() const;

void setDataSize(UBYTE x);

UBYTE getErrorType() const ;

void setErrorType(UBYTE x);

const UBYTE *getData() const;

UBYTE *getData();

void setData(UBYTE *x);

};

EXS API Hex Format

MESSAGE (White)

RESPONSE (Gray)

Byte

Field Description

Byte

Field Description

0

Frame (0xFE)

0

Frame (0xFE)

1, 2

Length (0xNNNN)

1, 2

Length (0xNNNN)

3, 4

Message Type (0x00D6)

3, 4

Message Type (0x00D6)

5

Reserved (0x00)

5

Reserved (0x00)

6

Sequence Number

6

Same Sequence Number

7

Logical Node ID

7

Logical Node ID

8, 9

PPL Component ID MSB, LSB

See PPL Component IDs in the
API Reference.

8, 9

Status MSB, LSB

 

10

Table Type (see formats below)

0x01 Primitive Table

0x02 Basic State/Event Table

0x03 Route Table

0x04 Resource Group Table

0x07 Extended State/Event Table

 

:

The following bytes apply if the Status is a NACK: "Table Does Not Validate" (0xA9). Otherwise, this field is 0x00, followed by the checksum.

 

Error Data Length:

The number of bytes of data to follow, including the Error Type field.

11

Table ID
Number assigned to table by host

0x01–0x0A

:

Error Type:

 

General Errors

0x01 Invalid Table Type

0x02 Invalid Checksum

 

Primitive Table Errors

0x03 Invalid Number of Atomic Functions In Primitive

0x04 Invalid Atomic Function ID

0x05 Invalid Primitive Table Size

 

State/Event Table Errors

0x06 Invalid Number of Events per State

0x07 Invalid Event ID (Exceeds Allowable Range)

0x08 Invalid Next State Type

0x09 Invalid State/Event Table Size

 

0x0A Invalid route number
0x0B Invalid criteria type
0x0C Null TLV
0x0D Invalid number of AIBs in Resource Group
0x0D Invalid AIB in Resource Group
0x0F Incorrect number of address elements in Resource
Group
0x10 Router Table Full
0x11 Router Table validation error
0x12 Invalid Route Group Id for Criteria

12

Table Data - See tables below this one.

:

Error Data[0]

The data is dependent on the value on the Error Type field.

 

(0x01) Invalid Table Type

Reported via a Status code.

 

(0x02) Invalid Checksum

Bytes 0–3 Checksum

 

(0x03) Invalid Number Of Atomic Functions

Bytes 0, 1 Primitive ID

Byte 2 Number of Atomic Functions

 

(0x04) Invalid Atomic Function ID

Bytes 0, 1 Primitive ID

Bytes 2, 3 Atomic Function ID

 

(0x05) Invalid Primitive Table Size

Bytes 0, 1 Primitive ID

Bytes 2 Number of Atomic Functions

 

(0x06) Invalid Number of Events Per State

Bytes 0, 1 State ID

Bytes 2, 3 Number of events

 

(0x07) Invalid Event ID
Bytes 0, 1 State ID

Bytes 2, 3 Event ID

 

(0x08) Invalid Next State Type

Bytes 0, 1 State ID

Byte 2 Next State Type

 

(0x09) Invalid State/Event Table Size

Bytes 0, 1 State ID

Bytes 2, 3 Number of Events

N + 3

Checksum

N+3

Checksum

Primitive Table Format (0x01)

A Primitive Table is a set of primitives used in conjunction with a State/Event Table to create a PPL protocol. Each Primitive Table can contain up to 400 primitives. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Primitive Table format is shown in the table below.

 

Byte

Field Description

Definition

Message Header

8, 9

PPL Component ID (MSB, LSB)

See list of Component IDs in this document.

10

Table Type

0x01 Primitive Table

11

Table ID

Assigned by host.

Table Data

12, 13

Data[0,1] Primitive ID (MSB, LSB)

Identifies each primitive in the primitive table. Each primitive in the table must be unique, and in the range from 0 to 199. The primitives in the table must be ordered lowest number to highest (numbers may be skipped).

14

Data[2] Number of AFs

The number of AFs used to create the primitive (1 to 10).

15, 16

Data[3,4] AF: ID (MSB, LSB)

The AF ID specifies the predefined function to be invoked (in the range supplied by Excel).

17, 18

Data[5,6] Arg 1 Value (MSB, LSB)

The first argument value to pass to the AF.

19, 20

Data[7,8] Arg 2 Value (MSB, LSB)

The second argument value to pass to the AF.

Repeat Data[3-8] for each AF in the primitive.

:

Checksum

 

Basic State/Event Table Format (0x02)

A Basic State/Event table is a group of valid events that pertain to a given state, the primitives that get invoked upon the occurrence the event, and the next state to transition into in response to the event(s). State/event tables allow for up to 100 states and up to 20 events per state. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Basic State/Event Table format is shown in the table below.

 

Byte

Field Description

Definition

Message Header

8, 9

PPL Component ID (MSB, LSB)

See list of Component IDs in this document.

10

Table Type

0x02 Basic State/Event Table

11

Table ID

Assigned by host

Table Data

12

Data[0] Table Data

Initial State Number

Identifies the current state that the protocol is in. States must be specified in order from 1 to 199. State numbers can be skipped. The initial State Type is assumed to be Normal.

13

Data[1] Number of Events

The number of valid events accepted by the state. Each state can accept up to 120 events. For best performance, events most likely to occur should be placed at the beginning of the list.

14, 15

Data[2, 3] Event 1 # (MSB, LSB)

See the for event data.

16, 17

Data[4, 5] Event Data 1 Value (MSB, LSB)

18, 19

Data[6, 7] Event Data 2 Value (MSB, LSB)

20, 21

Data[8, 9] Primitive ID (MSB, LSB)

The primitive invoked when the specified event occurs based on the Primitive Table associated with the event.

22

Data[10] Next State Number

The state that the protocol should enter in response to the indicated event(s).

23

Data[11] Next State Type

0x01 Normal/Wait

0x02 Internal

Repeat Data[2-11] for each event associated with the state.

:

Checksum

 

Route Table (0x03)

The Route Table format is shown in the table below.

 

Byte

Field Description

Definition

Message Header

8, 9

PPL Component ID (MSB, LSB)

See PPL Information chapter in API Reference.

10

Table Type

0x03 Route Table

11

Table ID

Assigned by host

Table Data

12, 13

Data[0, 1] Route Number

Index into the Route Table

14

Data[2] Route Property

This field is a bit mask indicating the details about the format of the remaining message bytes.

Bit

0-4 Not used

5 Force the storage of entry in Sequential
Linked List. If not set, use the default method
o
f storage.

6 If set, use exact matching. If cleared use default method of matching

7 Version of Route Table. Should always be set.

15

Data[3] Route Property - Addressing method

This field is a bit mask indicating the addressing method, either single or range.

Bit

0 Single

1 Range

16, 17

Data[2, 3] Version

Currently version 0x0001.

18, 19

Data[4, 5] Route Group ID

A grouping of routes based on a defined criteria or other information.

20, 21

Data[6, 7] Route Criteria Type. See Route Criteria Type entries below.

Identifies the type of information defining the route.

22

Data[8] Criteria Data: Format

0x01 Data in raw hex bytes
0x03 BCD (All digit based routes are BCD.)

23, 24

Data[9, 10] Criteria Data: Length of Criteria Data

 

25

Data[11..N] Criteria Data

See Route Criteria Type entries below for the definition of remaining data.

:

Data[N+0, N+1] Entry Data TLV Count

2 Bytes

:

Data[N+2, N+3] Entry Data TLV Length

2 Bytes

:

Data[N+4] Entry Data: TLVs

See Route Entry Data TLV entries below.

:

Checksum

 

Route Criteria Type entries

0x0007 Incoming Span/Channel, Single/Range

0x0009 Terminating Span/Channel, Single/Range

0x0010 Incoming Resource Group, Single/Range

0x0015 Terminating Resource Group, Single/Range

0x0065 Physical VoIP Channel

0x0071 Virtual VoIP Channel

0x03E9 User-defined

NOTE: See Notes 1, 2 and 3 below to configure the following Route Criteria Type entries.

0x2710 Universal Protocol Data, Single/Range

0x2717 Called Party Number, Single/Range

0x2718 Calling Party Number, Single/Range

0x2792 Source IP Address, Single/Range

0x2794 Destination IP Address, Single/Range

0x27B0 RTP Payload Type, Single/Range

0x27B4 IP Address Criteria, Single/Range

0x2919 NPDI SIP to Username, Single/Range

0x291A NPDI SIP to Hostname, Single/Range

0x2919 NPDI SIP from Username, Single/Range

0x291A NPDI SIP from Hostname, Single/Range

0x2A0E Media Connection Address, Single/Range

Notes

1. The second data format field that occurs after the length can have the following values:

0x01 - Data in Raw Hex Bytes

0x02 - ASCII Characters

0x03 - BCD (all digit-based routes are BCD)

0x04 - Decimal

 

2. The length of the this field is variable. It is equal to the Criteria Length minus the length of the Criteria Header information (for example, all fields after the length and not including the digits and mask fields) divided by the number of digits and mask fields included.

Below is an example of how the Single bit in the Route Property Mask is set (see field 15 in Route Table (0x03) above).

To compute the Length of Field which is equal to 7, do the following:

Criteria Length (20) subtract (-) Length of Criteria Header (6) and divide (/) by number of Digit and Mask fields (2)

2a 0e \ ' Media Connection Criteria Type

03 \' Criteria Data Format: BCD

00 14 \ ' Length

03 \ 'Criteria Data Format: BCD

63 \ ' Offset

00 00 00 00 \ ' Reserved - set to 0x00 0x00 0x00 0x00

04 05 05 06 06 07 08 \ ' Digits string

0f 0f 0f 0f 0f 0f 0f \ ' Mask

Below is an example of how the Range bit in the Route Property Mask is set (see field 15 in Route Table (0x03) above).

To compute the Length of Field which is equal to 1, do the following:

Criteria Length (9) subtract (-) Length of Criteria Header (6) and divide (/) by number of Digit and Mask fields (3)

 

2a 0e \ ' Media Connection Criteria Type

01 \ ' Criteria Data Format

00 09 \ ' Length

04 \ ' Criteria Data Format: Decimal

2c \ ' Offset

00 00 00 00 \ ' Reserved

0a \ ' From digits

cd \ ' To digits

ff \ ' Mask

 

3. The Offset field represents the number of channels to offset outgoing channel from incoming channel.

Route Entry TLV Type entries

0x0009 Address Element Blocks

0x0015 Resource Group ID

0x0062 Resource Group Reorder Method

0x0063 Route Number

0x001B Resource Table ID

0x001C Route Table ID

0x0161 PAD Values

0x03E9 User-defined

 

Resource Group Table (0x04)

The format of the Resource Group Table is shown in the table below.

 

Byte

Field Description

Definition

Message Header

8, 9

PPL Component ID (MSB, LSB)

See PPL Information chapter in API Reference.

10

Table Type

0x04 Resource Group Table

11

Table ID

Assigned by host

Table Data

12, 13

Data[0, 1] Resource Group ID

 

14, 15

Data[2, 3] Special Instructions

0x0001

16, 17

Data[4, 5]

Version Number should be 0x0001

18, 19

Data[6, 7] Number of AIBs

 

20, 21

Data[8, 9] Length of AIBs

 

22+

Data[:] AIB

See AIB Types

:

Data[:] Number of TLVs

The number of Tag/Length/Value entries to follow.

:

Data[:] Length of TLVs

 

:

Data[:] TLVs

See TLV Types

:

Checksum

 

 

Extended State/Event Table Format (0x07)

An Extended State/Event table is a group of valid events that pertain to a given state, the primitives that get invoked upon the occurrence the event, and the next state to transition into in response to the event(s). State/event tables allow for up to 100 states and up to 20 events per state. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Extended State/Event Table format is shown in the table below.

 

Byte

Field Description

Definition

Message Header

8, 9

PPL Component ID (MSB, LSB)

See list of Component IDs in this document.

10

Table Type

0x07 Extended State/Event Table

11

Table ID

Assigned by host

Table Data

12

Data[0,1] Initial State Number

Identifies the current state that the protocol is in. States must be specified in order from 1 to 199. State numbers can be skipped. The initial State Type is assumed to be Normal.

13

Data[2] Number of Events

The number of valid events accepted by the state. Each state can accept up to 120 events. For best performance, events most likely to occur should be placed at the beginning of the list.

14, 15

Data[3,4] Event 1 # (MSB, LSB)

Bytes 14 and 15 are external processing events, such as, Alerting or Answer; or internal decision events. Bytes 16-19 are arguments that relate to events such as, filter timer IDs for line signaling events. See the API Developer’s Guide: PPL for more details.

16, 17

Data[5, 6] Event Data 1 Value (MSB, LSB)

18, 19

Data[7, 8] Event Data 2 Value (MSB, LSB)

20, 21

Data[9, 10] Primitive ID (MSB, LSB)

The primitive invoked when the specified event occurs based on the Primitive Table associated with the event.

22

Data[11, 12] Next State Number

The state that the protocol should enter in response to the indicated event(s).

23

Data[13] Next State Type

0x01 Normal/Wait

0x02 Internal

Repeat Data[2-13] for each event associated with the state.

:

Checksum