Cisco TAPI Developer Guide for Cisco CallManager 3.3(3)
Cisco Device Specific Extensions
Downloads: This chapterpdf (PDF - 233.0KB) | Feedback

Cisco Device Specific Extensions

Table Of Contents

Cisco Device Specific Extensions

Cisco Specific Extensions

Structures

LINEDEVCAPS Device 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

Swap-Hold/SetupTransfer

Description

Class Details

Parameters

Redirect Reset Original Called ID

Description

Class Details

Parameters

Messages

Description


Cisco Device Specific Extensions


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 lineDevSpecific is called.

Cisco Specific Extensions

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

Table 3-1 lists the subclasses of CiscoLineDevSpecific.

Table 3-1 Cisco-Specific TAPI functions 

Cisco Functions
Synopsis

CCiscoLineDevSpecific

The CCiscoLineDevSpecific class specifies the parent class to the following four classes.

Message Waiting

The CCiscoLineDevSpecificMsgWaiting class turns the message waiting lamp on or off for the line that the hLine parameter specifies.

Message Waiting Dirn

The CCiscoLineDevSpecificMsgWaiting class turns the message waiting lamp on or off for the line that a parameter and remains independent of the hLine parameter specifies.

Audio Stream Control

The CCiscoLineDevSpecificUserControlRTPStream class controls the audio stream for a line.

Set Status Messages

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

Swap-Hold/SetupTransfer

The CCiscoLineDevSpecificSwapHoldSetupTransfer class performs a setupTransfer between a call that is in CONNECTED state and a call that is in ONHOLD state. This function will change the state of the connected call to ONHOLDPENDTRANSFER state and the ONHOLD call to CONNECTED state. This action will then allow a completeTransfer to be performed on the two calls.

Redirect Reset Original Called ID

The CCiscoLineDevSpecificRedirectResetOrigCalled class is used to redirects a call to another party while resetting the original called ID of the call to the destination of the redirect.


Structures

This section describes device-specific extensions that have been made to the TAPI structures that the CiscoTSP supports.

LINEDEVCAPS Device Specific Extensions

Description

The LineDevCaps_DevSpecificData structure describes the device-specific extensions that the CiscoTSP has made to the LINEDEVCAPS structure.

Detail

typedef struct LineDevCaps_DevSpecificData
{
	DWORD m_DevSpecificFlags;
}LINEDEVCAPS_DEV_SPECIFIC_DATA;

Parameters

DWORD m_DevSpecificFlags

A bit array that identifies device specific properties for the line. The bits definition follows:

LINEDEVCAPSDEVSPECIFIC_PARKDN (0x00000001)—Indicates whether this line is a Call Park DN.


Note This extension is only available if extension version 3.0 (0x00030000) or higher is negotiated.


CCiscoLineDevSpecific

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

Description

This section provides information on how to perform Cisco TAPI specific functions with the CCiscoLineDevSpecific class, which represents the parent class to all the following classes. It comprises 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

The CiscoLineDevSpecificType enumeration provides valid message identifiers.

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

Message Waiting

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificMsgWaiting

Description

The CCiscoLineDevSpecificMsgWaiting class turns the message waiting lamp on or off for the line that the hLine parameter specifies.

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

Any supported PHONELAMPMODE_ constants that are specified in the phoneSetLamp() function.

Message Waiting Dirn

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificMsgWaitingDirn

Description

The CCiscoLineDevSpecificMsgWaitingDirn class turns the message waiting lamp on or off for the line that a parameter specifies 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

As in the CCiscoLineDevSpecificMsgWaiting message.

char m_Dirn[25]

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

Audio Stream Control

CCiscoLineDevSpecific
  |
  +-- CCiscoLineDevSpecificUserControlRTPStream

Description

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

Procedure


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

Step 2 Call lineOpen for the deviceID of the line that is 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:

The RTP audio reception IP address in network byte order

DWORD m_ReceivePort:

The RTP audio reception port in network byte order

DWORD m_NumAffectedDevices:

The TSP returns this value. It contains the number of deviceIDs in the m_AffectedDeviceID array that are valid. Any device with multiple directory numbers that are assigned to it will have multiple TAPI lines, one per directory number.

DWORD m_AffectedDeviceID[10]:

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

DWORD m_mediaCapCount

The number of codecs that are 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 that is supported on a line. The limit specifies 18. The following description shows each member in the MEDIA_CAPS data structure:

MediaPayload specifies an enumerated integer that contains one of the following values:

enum

{

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_G729AnnexB = 15,

Media_Payload_G729AnnexAwAnnexB = 16,

Media_Payload_GSM_Full_Rate = 18,

Media_Payload_GSM_Half_Rate = 19,

Media_Payload_GSM_Enhanced_Full_Rate = 20,

Media_Payload_Wide_Band_256k = 25,

Media_Payload_Data64 = 32,

Media_Payload_Data56 = 33,

Media_Payload_GSM = 80,

Media_Payload_G726_32K = 82,

Media_Payload_G726_24K = 83,

Media_Payload_G726_16K = 84,

// Media_Payload_G729_B = 85,

// Media_Payload_G729_B_LOW_COMPLEXITY = 86,

} Media_PayloadType;

Read MaxFramesPerPacket as MaxPacketSize. It specifies a 16-bit integer that is specified in milliseconds. It indicates the maximum desired RTP packet size. Typically, this value gets set to 20.

G723BitRate specifies a 6-byte field that contains either the G.723.1 information bit rate or is ignored. The following list provides values for the G.723.1 field are values.

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 turns on or off the status messages for the line that the hLine parameter specifies. The CiscoTSP supports DEVSPECIFIC_MEDIA_STREAM flag. Setting this flag on a line turns on the reporting of media streaming messages for that line. Clearing this flag will turn off the reporting of media streaming messages for that line.


Note This extension only applies 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

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

The supported values follow:

#define DEVSPECIFIC_MEDIA_STREAM 0x00000001

Swap-Hold/SetupTransfer

CCiscoLineDevSpecific
|
+-- CCiscoLineDevSpecificSwapHoldSetupTransfer

Description

The CCiscoLineDevSpecificSwapHoldSetupTransfer class performs a setupTransfer between a call that is in CONNECTED state and a call that in ONHOLD state. This function will change the state of the connected call to ONHOLDPENDTRANSFER state and the ONHOLD call to CONNECTED state. This will then allow a completeTransfer to be performed on the two calls.


Note This extension only applies if extension version 0x00020002 or higher is negotiated.


Class Details

class CCiscoLineDevSpecificSwapHoldSetupTransfer : public 
CCiscoLineDevSpecific
    {
    public:
      CCiscoLineDevSpecificSwapHoldSetupTransfer() : 
CCiscoLineDevSpecific(SLDST_SWAP_HOLD_SETUP_TRANSFER) {}
      virtual ~CCiscoLineDevSpecificSwapHoldSetupTransfer() {}
      DWORD heldCallID;
      virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // 
subtract out the virtual function table pointer
    };

Parameters

DWORD m_MsgType

Equals SLDST_SWAP_HOLD_SETUP_TRANSFER.

DWORD heldCallID

Equals the callid of the held call that is returned in dwCallID of LPLINECALLINFO.

HCALL hCall (in lineDevSpecific parameter list)

Equals the handle of the connected call.

Redirect Reset Original Called ID

CCiscoLineDevSpecific
|
+-- CCiscoLineDevSpecificRedirectResetOrigCalled

Description

The CCiscoLineDevSpecificRedirectResetOrigCalled class redirects a call to another party while resetting the original called ID of the call to the destination of the redirect.


Note This extension only applies if extension version 0x00020003 or higher is negotiated.


Class Details

class CCiscoLineDevSpecificRedirectResetOrigCalled: public 
CCiscoLineDevSpecific
    {
    public:
      CCiscoLineDevSpecificRedirectResetOrigCalled: 
CCiscoLineDevSpecific(SLDST_REDIRECT_RESET_ORIG_CALLED) {}
      virtual ~CCiscoLineDevSpecificRedirectResetOrigCalled{}
      char m_DestDirn[25]; //redirect destination address
      virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // 
subtract out the virtual function table pointer
    };

Parameters

DWORD m_MsgType

Equals SLDST_REDIRECT_RESET_ORIG_CALLED.

DWORD m_DestDirn

Equals the destination address where the call needs to be redirected.

HCALL hCall (In lineDevSpecific parameter list)

Equals the handle of the connected call.

Messages

This section describes the line device specific messages that the CiscoTSP supports.

Description

An application receives nonstandard TAPI messages in LINE_DEVSPECIFIC messages. These include messages that signal when to stop and start streaming RTP audio and a message that contains 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

SLDSMT_START_TRANSMISION

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

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

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

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

The application receives these messages to signal when to start streaming RTP audio. At extension version 1.0 (0x00010000), 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.0 (0x00020000), 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

SLDSMT_START_RECEPTION

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

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

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

dwParam3, specifies the low-order high-order word that is the packet size in milliseconds to use.

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

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

SLDSMT_STOP_TRANSMISION

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

Stop Reception Events

SLDSMT_STOP_RECEPTION

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

Existing Call Events

SLDSMT_LINE_EXISTING_CALL

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

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

dwParam1 - Message type

dwParam2 - Call object

dwParam3 - TAPI call handle