You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > Collect Digit String 0x00BC

Collect Digit String 0x00BC

SwitchKit Name

CollectDigitString

Type

EXS API and SwitchKit API message

Description

Collect Digit String 0x00BC

This message instructs the CSP to attach a digit receiver to the specified channel.

NOTE: The digit receiver collects digit strings only if the digits are either DTMF or MFR1, or if the call is in a state other than idle, out of service, or busied out

Once the receiver has collected the digits, the CSP sends a Call Processing Event message with the value 0x02 (Digits) in the Call Processing Event field. If an error occurs, the CSP sends a Call Processing Event message and indicates the error using the Status field.

If the host sends this message and specifies a channel to which a digit receiver is already attached, the CSP sends the host a response with a status of 0x30 (DSP Resource Already Allocated). The channel is not affected.

The CSP releases the digit receiver from the channel when one of the following occurs:

The CSP sends a Call Processing Event message

The call is released

The CSP receives a DSP Service Cancel message from the host

Sent by

Host Application

SwitchKit Code

C Structure

typedef struct {

unsigned short Span;

UBYTE Channel;

UBYTE Mode;

UBYTE MaxDigits;

UBYTE NumTermChars;

UBYTE ConfigBits;

unsigned short TermChars;

unsigned short InterDigitTimer;

unsigned short FirstDigitTimer;

unsigned short CompletionTimer;

unsigned short MinReceiveDigitDuration;

UBYTE AddressSignallingType;

UBYTE NumDigitStrings;

unsigned short ResumeDigitCltnTimer;

} XL_CollectDigitString;

C++ Class

class XLC_CollectDigitString : public XLC_OneChannelOutbound {

public:

unsigned short getSpan() const;

void setSpan(unsigned short x);

UBYTE getChannel() const;

void setChannel(UBYTE x);

UBYTE getMode() const;

void setMode(UBYTE x);

UBYTE getMaxDigits() const;

void setMaxDigits(UBYTE x);

UBYTE getNumTermChars() const;

void setNumTermChars(UBYTE x);

UBYTE getConfigBits() const;

void setConfigBits(UBYTE x);

unsigned short getTermChars() const;

void setTermChars(unsigned short x);

unsigned short getInterDigitTimer() const;

void setInterDigitTimer(unsigned short x);

unsigned short getFirstDigitTimer() const;

void setFirstDigitTimer(unsigned short x);

unsigned short getCompletionTimer() const;

void setCompletionTimer(unsigned short x);

unsigned short getMinReceiveDigitDuration() const;

void setMinReceiveDigitDuration(unsigned short x);

UBYTE getAddressSignallingType() const;

void setAddressSignallingType(UBYTE x);

UBYTE getNumDigitStrings() const;

void setNumDigitStrings(UBYTE x);

unsigned short getResumeDigitCltnTimer() const;

void setResumeDigitCltnTimer(unsigned short x);

};

Overview of message

The following table provides an overview of this message. The table following it provides the detail for each byte.

MESSAGE (White) | RESPONSE (Gray)
Byte | Field Description | Byte | Field Description
0 | Frame (0xFE) | 0 | Frame (0xFE)
1, 2 | Length (0xNNNN) | 1, 2 | Length (0x0005)
3, 4 | Message Type (0x00BC) | 3, 4 | Message Type (0x00BC)
5 | Reserved (0x00) | 5 | Reserved (0x00)
6 | Sequence Number | 6 | Same Sequence Number
7 | Logical Node ID | 7 | Logical Node ID
: | AIB (Starting with byte 0) | 8, 9 | Status (MSB, LSB) 0x0002 DSP Receiver Request Timeout
10 | Checksum
: | Mode
: | Max Digits
: | Number of Terminating Characters
: | Configuration Bits
: | Terminating Characters (MSB, LSB)
: | Interdigit Timer (MSB, LSB)
: | First Digit Timer (MSB, LSB)
: | Completion Timer (MSB, LSB)
: | Minimum Receive Digit Duration Timer (MSB, LSB)
: | Address Signaling Type
: | Number of Digit Strings
: | Resume Digit Collection Timer (MSB, LSB)
: | Checksum

Hex API Format - Detailed

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 (0x00BC) | 3, 4 | Message Type (0x00BC)
5 | Reserved (0x00) | 5 | Reserved (0x00)
6 | Sequence Number | 6 | Same Sequence Number
7 | Logical Node ID | 7 | Logical Node ID
: | AIB Address Method 0x00 - Individual AEs | 8, 9 | Status MSB, LSB
10 | Checksum
Number of AEs to follow
AE 0x0D Channel
: | Mode 0x01 Fixed Number of Digits 0x02 Use Terminating Characters 0x03 Use KP_ST Characters 0x04 Use Fixed Number of Digits or Terminating Characters 0x05 Reserved 0x06 Reserved 0x07 Reserved 0x08 Fixed or Indefinite Number of Digits If the first digit detected is zero, the Indefinite Number of Digits method is used and the Completion Timer or Interdigit Timer is used (whichever expires first) to terminate digit collection. If the first digit collected is not zero, the Fixed Number of Digits method is used. This method is used to help facilitate collecting digit strings on channels that process national and international calls.
: | Max Digits Maximum number of digits to collect (0100) This field is valid only if the Mode field value is either 0x01 (Fixed Number of Digits) or 0x04 (Use Fixed Number of Digits or Term Chars); otherwise, it is ignored.
: | Number of Terminating Characters Number of terminating characters to collect (04). This field is valid only if the Mode field value is either 0x02 (Use Terminating Characters) or 0x04 (Use Fixed Number of Digits or Term Chars); otherwise, it must be 0x00.
: | Configuration Bits Bit 0 Report Digit at Falling Edge 0 Digit is reported at its rising edge when the digit is first pressed or if it is present on the line at the time the receiver is attached. 1 Digit is reported at its falling edge when the digit is first released. 1 First Digit Collected 0 Do not inform the host that the first digit was collected. 1 Inform the host that the first digit was collected. Use the Call Processing Event message. The first digit will also be reported in the Call Processing Event message with the remaining digits. 2 Ignore # Character 0 Do not ignore the "#" character as the first digit. 1 Ignore the "#" character as the first digit. 3 Suspend Digit Collection 0 Do not suspend digit collection. 1 Suspend digit collection upon outpulsing digits. The following requires that one DSP-2, DSP-ONE or MFDSP card be configured with both DTMF Transmission and DTMF Reception. Channels with this feature enabled will only have access to DTMF Receivers on cards which also have DTMF Transmitters configured. 4 Cancel Prompting Tone or Recorded Announcement 0 Prompting tone or RAN is cancelled on receipt of the first digit. 1 Prompting tone or recorded announcement continues. 5 Detect Leading Silence (only used for rising edge detection) 0 Do not require leading silence before reporting valid rising edge digit. 1 Require detection of leading silence before reporting the first valid rising edge digit. Digits on the line at time of receiver attachment will not be reported. 6 Cancel Recording 0 Recording is cancelled on receipt of the first digit 1 Recording continues 7 Detect DTMF Frequencies 0 DTMF detection logic checks the two individual DTMF frequencies and the total of both frequencies that make up a DTMFdigit before reporting the detected digit. 1 DTMF detection logic only checks the total frequency of the two individual DTMF frequencies that make up a DTMFdigit before reporting the detected digit. (Default)
: | Terminating Characters MSB, LSB Use this two-byte field only if the value of the Mode field is either 0x02 (Use Terminating Characters) or 0x04 (Use Fixed Number of Digits or Term Chars). The terminating characters are stored as nibbles. You can define up to four terminating characters, as shown below. MSB Bit 03 Terminating Character 2 47 Terminating Character 1 LSB Bit 03 Terminating Character 4 47 Terminating Character 3
: | Interdigit Timer MSB, LSB NOTE: Timers are in 10 ms units. The maximum time to wait between digits after the first one is received. The value 0xFFFF disables this timer.
: | First Digit Timer MSB, LSB The maximum time to wait for the first digit of a string (in 10 ms units). The value 0xFFFF disables this timer.
: | Completion Timer MSB, LSB The maximum time to wait for the entire string after the first digit is detected. The value 0xFFFF disables this timer.
: | Minimum Receive Digit Duration Timer MSB, LSB The minimum time a digit must be detected before it is declared valid. The value must be at least 30 ms, which is the default.
: | Address Signaling Type The address signaling type must be the same for both strings within a stage, but may differ between stages. 0x01 DTMF 0x02 MFR1 0x14 DTMF and Dial Pulse Receiver 0x15 Dial Pulse Receiver
: | Number of Digit Strings Number of digit strings to collect (1 or 2, usually 1 unless strings are KP/ST framed)
: | Resume Digit Collection Timer MSB, LSB The amount of time to wait after outpulsing is complete to resume digit collection.
: | Checksum

Digital Signal Processor
A computer, attached to the Excel platform through an RS-232 or Ethernet link, from which you run the telecommunications application that controls the Excel platform.
Range of channels provided by T1 or E1 transmission service. A physical span is a group of channels taking up a single physical wire. A logical span is a group of channels taking up less than a single logical wire, or carried over more than one physical wire.
A group of data bits in a specific format, with a flag at each end to indicate the beginning and the end of the frame.
See Address Information Block.
Most Significant Bit
Least Significant Bit
See Recorded Announcements.