Cisco CallManager 3.1 TAPI Developer Guide
Cisco Device Specific Extensions
Downloads: This chapterpdf (PDF - 166.0KB) The complete bookPDF (PDF - 1.96MB) | Feedback

Cisco Device Specific Extensions

Table Of Contents

Cisco Device Specific Extensions

Introduction

Cisco Specific Extensions

CCiscoLineDevSpecific

Description

Header File

Class Detail

Functions

Parameter

Subclasses

Enumeration

Message Waiting

Description

Class Detail

Parameters

Message Waiting Dirn

Description

Class Detail

Parameters

Audio Stream Control

Description

Class Detail

Parameters

Set Status Messages

Description

Class Detail

Parameters

Messages

Description

Enumeration Description


Cisco Device Specific Extensions


Introduction

This chapter describes the Cisco-specific TAPI extensions. It describes how to invoke Cisco-specific TAPI extensions with the lineDevSpecific function and it describes the supported line device specific messages. It also describes a set of classes that can be used when calling lineDevSpecific.

Cisco Specific Extensions

CiscoLineDevSpecific, the CCiscoLineDevSpecific class, is the parent class to four classes.

Table 3-1 lists the four subclasses of CiscoLineDevSpecific.

Table 3-1 Cisco Specific TAPI functions

Cisco Functions
Synopsis

Message Waiting

The CCiscoLineDevSpecificMsgWaiting class is used to turn the message waiting lamp on or off for the line specified by the hLine parameter.

Message Waiting Dirn

The CCiscoLineDevSpecificMsgWaiting class is used to turn the message waiting lamp on or off for the line specified by a parameter and is independent of the hLine parameter.

Audio Stream Control

The CCiscoLineDevSpecificUserControlRTPStream class is used to control the audio stream for a line.

Set Status Messages

The CCiscoLineDevSpecificSetStatusMsgs class is used to control the reporting of certain line device specific messages for a line. Messages, The application receives LINE_DEVSPECIFIC messages to signal when to stop and start streaming RTP audio.


CCiscoLineDevSpecific

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificMsgWaiting
  |
  +-- CCiscoLineDevSpecificMsgWaitingDirn
  |
  +-- CCiscoLineDevSpecificUserControlRTPStream
  |
  +--CCiscoLineDevSpecificSetStatusMsgs

Description

This section provides information on how to perform Cisco TAPI specific functions with the CCiscoLineDevSpecific class, which is the parent class to all the following classes. It is a virtual class and is provided here for informational purposes.

Header File

The file CiscoLineDevSpecific.h contains the constant, structure and class definition for the Cisco line device specific classes.

Class Detail

class CCiscoLineDevSpecific 
  {
  public:
CCicsoLineDevSpecific(DWORD msgType);
virtual ~CCiscoLineDevSpecific();
    DWORD GetMsgType(void) const {return m_MsgType;}
    void* lpParams() {return &m_MsgType;}
    virtual DWORD dwSize() = 0;
  private:
    DWORD m_MsgType;
  };

Functions

lpParms()

function can be used to obtain the pointer to the parameter block

dwSize()

function will give the size of the parameter block area

Parameter

m_MsgType

specifies the type of message.

Subclasses

Each subclass of CCiscoLineDevSpecific has a different value assigned to the parameter m_MsgType. If you are using C instead of C++, this is the first parameter in the structure.

Enumeration

Valid message identifiers are found in the CiscoLineDevSpecificType enumeration.

enum CiscoLineDevSpecificType  {
   SLDST_MSG_WAITING = 1,
   SLDST_MSG_WAITING_DIRN,
   SLDST_USER_CRTL_OF_RTP_STREAM,
   SLDST_SET_STATUS_MESSAGES,
   SLDST_NUM_TYPE
};

Message Waiting

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificMsgWaiting

Description

The CCiscoLineDevSpecificMsgWaiting class is used to turn the message waiting lamp on or off for the line specified by the hLine parameter.

Class Detail

class CCiscoLineDevSpecificMsgWaiting : public CCiscoLineDevSpecific
 {
 public:
  CCiscoLineDevSpecificMsgWaiting() : CCiscoLineDevSpecific(SLDST_MSG_WAITING){}
  virtual ~CCiscoLineDevSpecificMsgWaiting() {}
  virtual DWORD dwSize(void) const {return sizeof(*this)-4;}
  DWORD m_BlinkRate; 
 };

Parameters

DWORD m_MsgType

equals SLDST_MSG_WAITING.

DWORD m_BlinkRate

is any supported PHONELAMPMODE_ constants specified in the phoneSetLamp() function.

Message Waiting Dirn

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificMsgWaitingDirn

Description

The CCiscoLineDevSpecificMsgWaitingDirn class is used to turn the message waiting lamp on or off for the line specified by a parameter and is independent of the hLine parameter.

Class Detail

class CCiscoLineDevSpecificMsgWaitingDirn : public CCiscoLineDevSpecific
 {
 public:
  CCiscoLineDevSpecificMsgWaitingDirn() :  
    CCiscoLineDevSpecific(SLDST_MSG_WAITING_DIRN) {}
  virtual ~CCiscoLineDevSpecificMsgWaitingDirn() {}
  virtual DWORD dwSize(void) const {return sizeof(*this)-4;}
  DWORD m_BlinkRate; 
  char m_Dirn[25];
 };

Parameters

DWORD m_MsgType

equals SLDST_MSG_WAITING_DIRN.

DWORD m_BlinkRate

is as in the CCiscoLineDevSpecificMsgWaiting message.

char m_Dirn[25]

is the directory number for which the message waiting lamp should be set.

Audio Stream Control

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificUserControlRTPStream

Description

The CCiscoLineDevSpecificUserControlRTPStream class is used to control the audio stream of a line. To use this class, the lineNegotiateExtVersion API must be called before opening the line. When calling lineNegotiateExtVersion the highest bit must be set on both the dwExtLowVersion and dwExtHighVersion parameters. This causes the call to lineOpen to behave differently. The line is not actually opened, but waits for a lineDevSpecific call to complete the open with more information. The extra information required is provided in the CCiscoLineDevSpecificUserControlRTPStream class.

Procedure


Step 1 Call lineNegotiateExtVersion for the deviceID of the line to be opened. (OR 0x80000000 with the dwExtLowVersion and dwExtHighVersion parameters)

Step 2 Call lineOpen for the deviceID of the line to be opened.

Step 3 Call lineDevSpecific with a CCiscoLineDevSpecificUserControlRTPStream message in the lpParams parameter.


Class Detail

class CCiscoLineDevSpecificUserControlRTPStream : public CCiscoLineDevSpecific
 {
  public:
  CCiscoLineDevSpecificUserControlRTPStream() :  
    CCiscoLineDevSpecific(SLDST_USER_CRTL_OF_RTP_STREAM),
    m_ReceiveIP(-1), 
    m_ReceivePort(-1), 
    m_NumAffectedDevices(0)
     {
     memset(m_AffectedDeviceID, 0, sizeof(m_AffectedDeviceID));
     }
  virtual ~CCiscoLineDevSpecificUserControlRTPStream() {}
  DWORD m_ReceiveIP;   // UDP audio reception IP
  DWORD m_ReceivePort; // UDP audio reception port
  DWORD m_NumAffectedDevices;
  DWORD m_AffectedDeviceID[10];
  DWORD m_MediaCapCount;
  MEDIA_CAPS m_MediaCaps;
  virtual DWORD dwSize(void) const {return sizeof(*this)-4;}
 };

Parameters

DWORD m_MsgType

Equals SLDST_USER_CRTL_OF_RTP_STREAM

DWORD m_ReceiveIP:

This is the RTP audio reception IP address in network byte order

DWORD m_ReceivePort:

This is the RTP audio reception port in network byte order

DWORD m_NumAffectedDevices:

This value is returned by the TSP. It contains the number of deviceIDs in the m_AffectedDeviceID array which are valid. Any device with multiple directory numbers assigned to it will have multiple TAPI lines, one per directory number.

DWORD m_AffectedDeviceID[10]:

This value is returned by the TSP. It contains the list of deviceIDs for any device affected by this call. Do not call lineDevSpecific for any other device in this list.

DWORD m_mediaCapCount

The number of codecs supported for this line.

MEDIA_CAPS m_MediaCaps -

A data structure with the following format:

typedef struct {

DWORD MediaPayload;

DWORD MaxFramesPerPacket;

DWORD G723BitRate;

} MEDIA_CAPS[MAX_MEDIA_CAPS_PER_DEVICE];

This data structure defines each codec supported on a line. The limit is 18. The following is a description for each member in the MEDIA_CAPS data structure:

MediaPayload is an enumerated integer containing one of the following values.

enum

{

Media_Payload_NonStandard = 1,

Media_Payload_G711Alaw64k = 2,

Media_Payload_G711Alaw56k = 3, // "restricted"

Media_Payload_G711Ulaw64k = 4,

Media_Payload_G711Ulaw56k = 5, // "restricted"

Media_Payload_G722_64k = 6,

Media_Payload_G722_56k = 7,

Media_Payload_G722_48k = 8,

Media_Payload_G7231 = 9,

Media_Payload_G728 = 10,

Media_Payload_G729 = 11,

Media_Payload_G729AnnexA = 12,

Media_Payload_Is11172AudioCap = 13,

Media_Payload_Is13818AudioCap = 14,

Media_Payload_ACy_g729AASSn = 15,

Media_Payload_Data64 = 32,

Media_Payload_Data56 = 33,

Media_Payload_GSM = 80,

Media_Payload_ActiveVoice = 81

} Media_PayloadType;

MaxFramesPerPacket is a 16 bit integer containing the count of compression frames contained in a single RTP packet. Normally this number is set to 1.

G723BitRate is a six byte field which contains either the G.723.1 information bit rate or is ignored. The values for the G.723.1 field are values enumerated as follows.

enum

{

Media_G723BRate_5_3 = 1, //5.3Kbps

Media_G723BRate_6_4 = 2 //6.4Kbps

} Media_G723BitRate;

Set Status Messages

CCiscoLineDevSpecific
|
+-- CCiscoLineDevSpecificSetStatusMsgs

Description

The CCiscoLineDevSpecificSetStatusMsgs class is used to turn on or off the status messages for the line specified by the hLine parameter. The CiscoTSP supports DEVSPECIFIC_MEDIA_STREAM flag. Setting this flag on a line turns on the reporting of media streaming messages for that line. While clearing this flag will turn off the reporting of media streaming messages for that line.


Note This extension is only available if extension version 0x00020001 or higher is negotiated.


Class Detail

class CCiscoLineDevSpecificSetStatusMsgs : public CCiscoLineDevSpecific
{
public:
CCiscoLineDevSpecificSetStatusMsgs() : 
CCiscoLineDevSpecific(SLDST_SET_STATUS_MESSAGES) {}
virtual ~CCiscoLineDevSpecificSetStatusMsgs() {}
DWORD m_DevSpecificStatusMsgsFlag;
virtual DWORD dwSize(void) const {return sizeof(*this)-4;}
};

Parameters

DWORD m_MsgType

equals SLDST_SET_STATUS_MESSAGES.

DWORD m_DevSpecificStatusMsgsFlag

is bit array that identifies for which status changes a LINE_DEVSPECIFIC message will be sent to the application.

The supported values are

#define DEVSPECIFIC_MEDIA_STREAM 0x00000001

Messages

This section describes the line device specific messages supported by the CiscoTSP.

Description

An application receives nonstandard TAPI messages in LINE_DEVSPECIFIC messages. These include messages to signal when to stop and start streaming RTP audio and a message containing the call handle of active calls when the application starts up.

The message type is an enumerated integer with the following values:

enum CiscoLineDevSpecificMsgType
{
  SLDSMT_START_TRANSMISION = 1,
  SLDSMT_STOP_TRANSMISION,
  SLDSMT_START_RECEPTION,
  SLDSMT_STOP_RECEPTION,
  SLDST_LINE_EXISTING_CALL,
  SLDSMT_NUM_TYPE
};

Start Transmission Events

The application receives these messages to signal when to start streaming RTP audio. At extension version 1, the parameters have the following format:

dwParam1 contains the message type

dwParam2 contains the IP address of the remote machine

dwParam3 contains the network byte order IP port of the remote machine to which the RTP stream should be directed in the high-order word and the packet size in milliseconds in the low-order word.

At extension version 2, start transmission has the following format:

dwParam1:from highest order bit to lowest

first two bits blank

precedence value 3 bits

maximum frames per packet 8 bits

G723 bit rate 2 bits

Silence suppression value 1 bit

Compression type 8 bits

Message type 8 bits

dwParam2 contains the IP address of the remote machine

dwParam3 contains the network byte order IP port of the remote machine to which the RTP stream should be directed in the high-order word and the packet size in milliseconds in the low-order word.

Start Reception Events

The application receives these messages to signal when to start streaming RTP audio. At extension version 1, the parameters have the following format:

dwParam1 contains the message type

dwParam2 contains the IP address of the remote machine

dwParam3 contains the network byte order IP port of the remote machine to which the RTP stream should be directed in the high-order word and the packet size in milliseconds in the low-order word.

At extension version 2 start reception has the following format:

dwParam1:from highest order bit to lowest

first 13 bits blank

G723 bit rate 2 bits

Silence suppression value 1 bit

Compression type 8 bits

Message type 8 bits

dwParam2 contains the IP address of the remote machine

dwParam3 contains the network byte order IP port of the remote machine to which the RTP stream should be directed in the high-order word and the packet size in milliseconds in the low-order word.

Stop Transmission Events

When a message is received, the appropriate part of the streaming should be stopped.

Stop Reception Events

When a message is received, the appropriate part of the streaming should be stopped.

Existing Call Events

These events inform the application of existing calls in the PBX when it starts up. The format of the parameters is:

dwParam1 - Message type

dwParam2 - the call object

dwParam3 - the tapi call handle

Enumeration Description

SLDSMT_START_TRANSMISION

When a message is received, the RTP stream transmission should commence.

dwParam2 is the network byte order IP address of the remote machine to which the RTP stream should be directed

dwParam3, the high-order word is the network byte order IP port of the remote machine to which the RTP stream should be directed

dwParam3, the low-order word is the packet size in milliseconds to use

SLDSMT_START_RECEPTION

When a message is received, the RTP stream reception should commence.

dwParam2 is the network byte order IP address of the local machine to use

dwParam3, the high-order word is the network byte order IP port to use

dwParam3, the low-orderhigh-order word is the packet size in milliseconds to use.

SLDSMT_STOP_TRANSMISION

When a message is received, the transmission of the streaming should be stopped.

SLDSMT_STOP_RECEPTION

When a message is received, the reception of the streaming should be stopped.

SLDSMT_LINE_EXISTING_CALL

When the application starts up, this message will inform the application of existing calls in the PBX.