-
Cisco Unified TAPI Developers Guide for Cisco Unified Communications Manager Release 7.1(2)
-
Preface
-
Cisco Unified TAPI Overview and Concepts
-
New and Changed Information
-
Features Supported by TAPI
-
Cisco Unified TAPI Installation
-
Basic TAPI Implementation
-
Cisco Device-Specific Extensions
-
Cisco Unified TAPI Examples
-
Message Sequence Charts
-
Cisco Unified TAPI Interfaces
-
Troubleshooting Cisco Unified TAPI
-
Cisco Unified TAPI Operations-by-Release
-
Supported CTI Devices
-
Feedback
Table Of Contents
Cisco Device-Specific Extensions
Cisco Line Device Specific Extensions
Redirect Reset Original Called ID
Setting RTP Parameters for Call
Redirect Set Original Called ID
Redirect with Feature Priority
Set RTP Parameters for IPv6 Calls
Cisco Line Device Feature Extensions
Do-Not-Disturb Change Notification Event
Cisco Phone Device-Specific Extensions
CCiscoPhoneDevSpecificDataPassThrough
CCiscoPhoneDevSpecificDeacquire
CCiscoPhoneDevSpecificGetRTPSnapshot
LINECALLINFO_DEVSPECIFICDATA Events
Cisco Device-Specific Extensions
This chapter describes the Cisco device-specific TAPI extensions. CiscoLineDevSpecific and the CCiscoPhoneDevSpecific class represent the parent class. This chapter describes how to invoke the Cisco device-specific TAPI extensions with the lineDevSpecific function. It also describes a set of classes that you can use when you call phoneDevSpecific. It contains the following sections:
•
Cisco Line Device Specific Extensions
•
•
Cisco Line Device Specific Extensions
Table 6-1 lists the subclasses of Cisco Line Device-Specific Extensions. This section contains all of the extensions in the table and descriptions of the following data structures:
LINEDEVCAPS
Cisco TSP implements several line device-specific extensions and uses the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of the LINEDEVCAPS data structure for those extensions. The the Cisco_LineDevCaps_Ext structure in the CiscoLineDevSpecificMsg.h header file defines the DevSpecific area layout. Cisco TSP organizes the data in that structure based on the extension version in which the data was introduced:
// LINEDEVCAPS Dev Specific extention //typedef struct Cisco_LineDevCaps_Ext{Cisco_LineDevCaps_Ext00030000 ext30;Cisco_LineDevCaps_Ext00060000 ext60;Cisco_LineDevCaps_Ext00070000 ext70;Cisco_LineDevCaps_Ext00080000 ext80;} CISCO_LINEDEVCAPS_EXT;For a specific line device, the extension area will include a portion of this structure starting from the beginning and up to the extension version that an application negotiated.
The individual extension version substructure definitions follow:
// LINEDEVCAPS 00030000 extention //typedef struct Cisco_LineDevCaps_Ext00030000{DWORD dwLineTypeFlags;} CISCO_LINEDEVCAPS_EXT00030000;// LINEDEVCAPS 00060000 extention //typedef struct Cisco_LineDevCaps_Ext00060000{DWORD dwLocale;} CISCO_LINEDEVCAPS_EXT00060000;// LINEDEVCAPS 00070000 extention //typedef struct Cisco_LineDevCaps_Ext00070000{DWORD dwPartitionOffset;DWORD dwPartitionSize;} CISCO_LINEDEVCAPS_EXT00070000;// LINEDEVCAPS 00080000 extention //typedef struct Cisco_LineDevCaps_Ext00080000{DWORD dwLineDevCaps_DevSpecificFlags; // LINEFEATURE_DEVSPECIFICDWORD dwLineDevCaps_DevSpecificFeatureFlags; // LINEFEATURE_DEVSPECIFICFEATRECORD_TYPE_INFO recordTypeInfo;INTERCOM_SPEEDDIAL_INFO intercomSpeedDialInfo;} CISCO_LINEDEVCAPS_EXT00080000;See the CiscoLineDevSpecificMsg.h header file for additional information on the DevSpecific structure layout and data.
Detail
A
typedef struct LineDevCaps_DevSpecificData{DWORD m_DevSpecificFlags;}LINEDEVCAPS_DEV_SPECIFIC_DATA;
Note
B
typedef struct LocaleInfo{DWORD Locale; //This will have the locale info of the deviceDWORD PartitionOffset;DWORD PartitionSize; //This will have the partition info of the line.} LOCALE_INFO;
Note
C
typedef struct PartitionInfo{DWORD PartitionOffset;DWORD PartitionSize; //This will have the partition info of the line.} PARTITION_INFO;
Note
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
DWORD Locale
This entity identifies the locale information for the device. The typical values could be:
enum{ENGLISH_UNITED_STATES = 1,FRENCH_FRANCE = 2,GERMAN_GERMANY = 3,RUSSIAN_RUSSIAN_FEDERATION = 5,SPANISH_SPAIN = 6,ITALIAN_ITALY = 7,DUTCH_NETHERLANDS = 8,NORWEGIAN_NORWAY = 9,PORGUGUESE_PORTUGAL = 10,SWEDISH_SWEDEN = 11,DANISH_DENMARK = 12,JAPANESE_JAPAN = 13,HUNGARAIN_HUNGARY = 14,POLISH_POLAND = 15,GREEK_GREECE = 16,CHINESE_TAIWAN = 19,CHINESE_CHINA = 20,KOREAN_KOREA_REPUBLIC = 21,FINNISH_FINLAND = 22,PORTUGUESE_BRAZIL = 23,CHINESE_HONG_KONG = 24,SLOVAK_SLOVAKIA = 25,CZECH_CZECH_REPUBLIC = 26,BULGARIAN_BULGARIA = 27,CROATIAN_CROATIA = 28,SLOVENIAN_SLOVENIA = 29,ROMANIAN_ROMANIA = 30,CATALAN_SPAIN = 32,ENGLISH_UNITED_KINGDOM = 33,ARABIC_UNITED_ARAB_EMIRATES = 35,ARABIC_OMAN = 36,ARABIC_SAUDI_ARABIA = 37,ARABIC_KUWAIT = 38,HEBREW_ISRAEL = 39,SERBIAN_REPUBLIC_OF_SERBIA = 40,SERBIAN_REPUBLIC_OF_MONTENEGRO = 41,THAI_THAILAND = 42,ARABIC_ALGERIA = 47,ARABIC_BAHRAIN = 48,ARABIC_EGYPT = 49,ARABIC_IRAQ = 50,ARABIC_JORDAN = 51,ARABIC_LEBANON = 52,ARABIC_MOROCCO = 53,ARABIC_QATAR = 54,ARABIC_TUNISIA = 55,}LINECALLINFO
Cisco TSP implements several line device-specific extensions and uses the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of the LINECALLINFO data structure for those extensions. The Cisco_LineCallInfo_Ext structure in the CiscoLineDevSpecificMsg.h header file defines DevSpecific area layout. Cisco TSP organizes the data in that structure based on the extension version in which the data was introduced:
// LINECALLINFO Dev Specific extention //typedef struct Cisco_LineCallInfo_Ext{Cisco_LineCallInfo_Ext00060000 ext60;Cisco_LineCallInfo_Ext00070000 ext70;Cisco_LineCallInfo_Ext00080000 ext80;} CISCO_LINECALLINFO_EXT;For a specific line device, the extension area includes a portion of this structure starting from the beginning and up to the extension version that an application negotiated.
The individual extension version substructure definitions follow:
// LINECALLINFO 00060000 extention //typedef struct Cisco_LineCallInfo_Ext00060000{TSP_UNICODE_PARTY_NAMES unicodePartyNames;} CISCO_LINECALLINFO_EXT00060000;// LINECALLINFO 00070000 extention //typedef struct Cisco_LineCallInfo_Ext00070000{DWORD SRTPKeyInfoStructureOffset; // offset from base of LINECALLINFODWORD SRTPKeyInfoStructureSize; // includes variable length data total sizeDWORD SRTPKeyInfoStructureElementCount;DWORD SRTPKeyInfoStructureElementFixedSize;DWORD DSCPInformationOffset; // offset from base of LINECALLINFODWORD DSCPInformationSize; // fixed size of the DSCPInformation structureDWORD DSCPInformationElementCount;DWORD DSCPInformationElementFixedSize;DWORD CallPartitionInfoOffset; // offset from base of LINECALLINFODWORD CallPartitionInfoSize; // fixed size of the CallPartitionInformation structureDWORD CallPartitionInfoElementCount;DWORD CallPartitionInfoElementFixedSize;DWORD ExtendedCallInfoOffset; // ===> ExtendedCallInfo { }DWORD ExtendedCallInfoSize; //DWORD ExtendedCallInfoElementCount; //DWORD ExtendedCallInfoElementSize; //} CISCO_LINECALLINFO_EXT00070000;// LINEDEVCAPS 00080000 extention //typedef struct Cisco_LineDevCaps_Ext00080000{DWORD dwLineDevCaps_DevSpecificFlags; // LINEFEATURE_DEVSPECIFICDWORD dwLineDevCaps_DevSpecificFeatureFlags; // LINEFEATURE_DEVSPECIFICFEATRECORD_TYPE_INFO recordTypeInfo;INTERCOM_SPEEDDIAL_INFO intercomSpeedDialInfo;} CISCO_LINEDEVCAPS_EXT00080000;// LINECALLINFO 00080001 extension //// ---------------------------------typedef struct Cisco_LineCallInfo_Ext00080001{DWORD CPNInfoOffset; //array of structure of CPNInfo structureDWORD CPNInfoSize;DWORD CPNInfoElementCount;DWORD CPNInfoElementFixedSize;};See the CiscoLineDevSpecificMsg.h header file for additional information on the DevSpecific structure layout and data.
Details
The TSP_Unicode_Party_names structure and SRTP info structure describe the device-specific extensions that the Cisco Unified TSP made to the LINECALLINFO structure. DSCPValueForAudioCalls will contain the DSCP value that CTI sent in the StartTransmissionEvent.
ExtendedCallInfo structure has extra call information. For Cisco Unified Communications Manager Release 7.0(1), the ExtendedCallReason field belongs to the ExtendedCallInfo structure.
CallAttributeInfo contains the information about attributeType (Monitoring, Monitored, Recorder,securityStatus) and PartyInfo (Dn,Partition,DeviceName)
CCMCallID contains CCM Call identifier value.
CallingPartyIPAddress contains the IP address of the calling party if the calling party device supports it.
CallSecurityStatus structure contains the overall security status of the call for two-party call as well as conference call.
DWORD TapiCallerPartyUnicodeNameOffset;DWORD TapiCallerPartyUnicodeNameSize;DWORD TapiCallerPartyLocale;DWORD TapiCalledPartyUnicodeNameOffset;DWORD TapiCalledPartyUnicodeNameSize;DWORD TapiCalledPartyLocale;DWORD TapiConnectedPartyUnicodeNameOffset;DWORD TapiConnectedPartyUnicodeNameSize;DWORD TapiConnectedPartyLocale;DWORD TapiRedirectionPartyUnicodeNameOffset;DWORD TapiRedirectionPartyUnicodeNameSize;DWORD TapiRedirectionPartyLocale;DWORD TapiRedirectingPartyUnicodeNameOffset;DWORD TapiRedirectingPartyUnicodeNameSize;DWORD TapiRedirectingPartyLocale;DWORD SRTPKeyInfoStructureOffset; // offset from base of LINECALLINFODWORD SRTPKeyInfoStructureSize; // includes variable length data total sizeDWORD SRTPKeyInfoStructureElementCount;DWORD SRTPKeyInfoStructureElementFixedSize;DWORD DSCPValueInformationOffset;DWORD DSCPValueInformationSize;DWORD DSCPValueInformationElementCount;DWORD DSCPValueInformationElementFixedSize;DWORD PartitionInformationOffset; // offset from base of LINECALLINFODWORD PartitionInformationSize; // includes variable length data total sizeDWORD PartitionInformationElementCount;DWORD PartitionInformationElementFixedSize;DWORD ExtendedCallInfoOffset;DWORD ExtendedCallInfoSize;DWORD ExtendedCallInfoElementCount;DWORD ExtendedCallInfoElementSize;DWORD CallAttrtibuteInfoOffset;DWORD CallAttrtibuteInfoSize;DWORD CallAttrtibuteInfoElementCount;DWORD CallAttrtibuteInfoElementSize;DWORD CallingPartyIPAddress;DWORD CCMCallIDInfoOffset;DWORD CCMCallIDInfoSize;DWORD CCMCallIDInfoElementCount;DWORD CCMCallIDInfoElementFixedSize;DWORD CallSecurityStatusOffset;DWORD CallSecurityStatusSize;DWORD CallSecurityStatusElementCount;DWORD CallSecurityStatusElementFixedSize;typedef struct SRTPKeyInfoStructure{SRTPKeyInformation TransmissionSRTPInfo;SRTPKeyInformation ReceptionSRTPInfo;} SRTPKeyInfoStructure;typedef struct SRTPKeyInformation{DWORD IsSRTPDataAvailable;DWORD SecureMediaIndicator; // CiscoSecurityIndicatorDWORD MasterKeyOffset;DWORD MasterKeySize;DWORD MasterSaltOffset;DWORD MasterSaltSize;DWORD AlgorithmID; // CiscoSRTPAlgorithmIDsDWORD IsMKIPresent;DWORD KeyDerivationRate;} SRTPKeyInformation;enum CiscoSRTPAlgorithmIDs{SRTP_NO_ENCRYPTION=0,SRTP_AES_128_COUNTER=1};enum CiscoSecurityIndicator{SRTP_MEDIA_ENCRYPT_KEYS_AVAILABLE,SRTP_MEDIA_ENCRYPT_USER_NOT_AUTH,SRTP_MEDIA_ENCRYPT_KEYS_UNAVAILABLE,SRTP_MEDIA_NOT_ENCRYPTED};If isSRTPInfoavailable is set to false, applications should ignore the rest of the information from SRTPKeyInformation.
If MasterKeySize or MasterSlatSize is set to 0, applications should ignore the corresponding MasterKeyOffset or MasterSaltOffset.
typedef struct DSCPValueInformation{DWORD DSCPValueForAudioCalls;}typedef struct PartitionInformation{DWORD CallerIDPartitionOffset;DWORD CallerIDPartitionSize;DWORD CalledIDPartitionOffset;DWORD CalledIDPartitionSize;DWORD ConnecetedIDPartitionOffset;DWORD ConnecetedIDPartitionSize;DWORD RedirectionIDPartitionOffset;DWORD RedirectionIDPartitionSize;DWORD RedirectingIDPartitionOffset;DWORD RedirectingIDPartitionSize;} PartitionInformation;Struct ExtendedCallInfo{DWORD ExtendedCallReason ;DWORD CallerIDURLOffset; // CallPartySipURLInfoDWORD CallerIDURISize;DWORD CalledIDURLOffset; // CallPartySipURLInfoDWORD CalledIDURISize;DWORD ConnectedIDURIOffset; // CallPartySipURLInfoDWORD ConnectedIDURISize;DWORD RedirectionIDURIOffset; // CallPartySipURLInfoDWORD RedirectionIDURISize;DWORD RedirectingIDURIOffset; // CallPartySipURLInfoDWORD RedirectingIDURISize;}Struct CallPartySipURLInfo{DWORD dwUserOffset; //sip user stringDWORD dwUserSize;DWORD dwHostOffset; //host name stringDWORD dwHostSize;DWORD dwPort; // integer port numberDWORD dwTransportType; // SIP_TRANS_TYPEDWORD dwURLType; // SIP_URL_TYPE}enum {CTI_SIP_TRANSPORT_TCP=1,CTI_SIP_TRANSPORT_UDP,CTI_SIP_TRANSPORT_TLS} SIP_TRANS_TYPE;enum {CTI_NO_URL = 0,CTI_SIP_URL,CTI_TEL_URL} SIP_URL_TYPE;typedef struct CallAttributeInfo{DWORD CallAttributeType,DWORD PartyDNOffset,DWORD PartyDNSize,DWORD PartyPartitionOffset,DWORD PartyPartitionSize,DWORD DeviceNameOffset,DWORD DeviceNameSize,DWORD OverallCallSecurityStatus}typedef struct CCMCallHandleInformation{DWORD CCMCallID;}enum{enum{CallAttribute_Regular = 0,CallAttribute_SilentMonitorCall .CallAttribute_SilentMonitorCall_Target ,CallAttribute_RecordedCall_Automatic ,CallAttribute_RecordedCall_AppControlled} CallAttributeTypetypedef struct CallSecurityStausInfo{DWORD CallSecurityStaus} CallSecurityStausInfoenum CallSecurityStausValue{CallSecurityStatus_UnknownCallSecurityStatus_NonSecure = 0,CallSecurityStatus_Secure}enum OverallCallSecurityStausValue{CallSecurityStatus_UnknownCallSecurityStatus_NonSecure = 0,CallSecurityStatus_Secure}};typedef struct CPNInfo{DWORD CallerPartyNumberType; //refer to CiscoNumberTypeDWORD CalledPartyNumberType;DWORD ConnectedIdNumberType;DWORD RedirectingPartyNumberType;DWORD RedirectionPartyNumberType;DWORD ModifiedCallingPartySize;DWORD ModifiedCallingPartyOffset;DWORD ModifiedCalledPartySize;DWORD ModifiedCalledPartyOffset;DWORD ModifiedConnectedIdSize;DWORD ModifiedConnectedIdOffset;DWORD ModifiedRedirectingPartySize;DWORD ModifiedRedirectingPartyOffset;DWORD ModifiedRedirectionPartySize;DWORD ModifiedRedirectionPartyOffset;DWORD GlobalizedCallingPartySize;DWORD GlobalizedCallingPartyOffset;} CPNInfo;enum CiscoNumberType {NumberType_Unknown = 0, // UNKNOWN_NUMBERNumberType_International = 1, // INTERNATIONAL_NUMBERNumberType_National = 2, // NATIONAL_NUMBERNumberType_NetSpecificNum = 3, // NET_SPECIFIC_NUMBERNumberType_Subscriber = 4, // SUBSCRIBER_NUMBERNumberType_Abbreviated = 6 // ABBREVIATED_NUMBER};Parameters
To indicate that partition information exists in the LINECALLINFO structure, the system fires a LINECALLINFOSTATE_DEVSPECIFIC event. The bit map indicating the change is defined as the following:
SLDST_NUMBER_TYPE_CHANGED 0x00000080
SLDST_GLOBALIZED_CALLING_PARTY_CHANGED 0x00000100
All available bitmap values of dwParam3 for LINECALLINFOSTATE_DEVSPECIFIC event are:
SLDST_SRTP_INFO 0x00000001
SLDST_QOS_INFO 0x00000002
SLDST_PARTITION_INFO 0x00000004
SLDST_EXTENDED_CALL_INFO 0x00000008
SLDST_CALL_ATTRIBUTE_INFO 0x00000010 //M&R
SLDST_CCM_CALL_ID 0x00000020 //M&R
SLDST_SECURITY_STATUS_INFO 0x00000040 //SecureConf
SLDST_NUMBER_TYPE_CHANGED 0x00000080 //CPN
SLDST_GLOBALIZED_CALLING_PARTY_CHANGED 0x00000100 //CPN
SLDST_FAR_END_IP_ADDRESS_CHANGED 0x00000200 //IPv6 new
Also, whenever a change occurs in the partition information, the system fires a LINEDEVSPECIFIC event that indicates which exact field in the devSpecific portion of the LINECALLINFO changed as shown below. This event fires only if the application has negotiated 7.0 extension version or higher.
LINEDEVSPECIFIC{hDevice = hcall //call handle for which the info has changed.dwParam1 = SLDSMT_LINECALLINFO_DEVSPECIFICDATA //indicates DevSpecific portion's changeddwParam2 = SLDST_SRTP_INFO | SLDST_QOS_INFO |SLDST_PARTITION_INFO | SLDST_EXTENDED_CALL_INFO | SLDST_CALL_ATTRIBUTE_INFO|SLDST_CCM_CALLID| SLDST_CALL_SECURITY_STATUSdwParam3 = ...dwParam3 will be security indicator if dwParam2 has bit set for SLDST_SRTP_INFO}SLDST_SRTP_INFO = 0x00000001SLDST_QOS_INFO = 0x00000002SLDST_PARTITION_INFO = 0x00000004SLDST_EXTENDED_CALL_INFO = 0x00000008SLDST_CALL_ATTRIBUTE_INFO = 0x00000010SLDST_CCM_CALLID = 0x00000020SLDST_CALL_SECURITY_STATUS=0x00000040LINEDEVSTATUS
Cisco TSP implements several line device-specific extensions and uses the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of the LINEDEVSTATUS data structure for those extensions. Cisco TSP defines the DevSpecific area layout in the Cisco_LineDevStatus_Ext structure in the CiscoLineDevSpecificMsg.h header file. The extension version in which the data was introduced provides basis for how the data in that structure is organized.
// LINEDEVSTATUS Dev Specific extention //typedef struct Cisco_LineDevStatus_Ext{Cisco_LineDevStatus_Ext00060000 ext60;Cisco_LineDevStatus_Ext00070000 ext70;Cisco_LineDevStatus_Ext00080000 ext80;} CISCO_LINEDEVSTATUS_EXT;For a specific line device, the extension area will include a portion of this structure, starting from the beginning and up to the extension version that an application negotiated.
Detail
The individual extension version substructure definitions follow:
// LINEDEVSTATUS 00060000 extention //typedef struct Cisco_LineDevStatus_Ext00060000{DWORD dwSupportedEncoding;} CISCO_LINEDEVSTATUS_EXT00060000;// LINEDEVSTATUS 00070000 extention //typedef struct Cisco_LineDevStatus_Ext00070000{char lpszAlternateScript[MAX_ALTERNATE_SCRIPT_SIZE];// An empty string means there is no alternate script configured// or the phone does not support alternate scripts} CISCO_LINEDEVSTATUS_EXT00070000;// LINEDEVSTATUS 00080000 extention //typedef struct CiscoLineDevStatus_DoNotDisturb{DWORD m_LineDevStatus_DoNotDisturbOption;DWORD m_LineDevStatus_DoNotDisturbStatus;} CISCOLINEDEVSTATUS_DONOTDISTURB;You can find additional information on the DevSpecific structure layout and data in the CiscoLineDevSpecificMsg.h header file.
The CiscoLineDevStatus_DoNotDisturb structure belongs to the LINEDEVSTATUS_DEV_SPECIFIC_DATA structure and gets used to reflect the current state of the Do Not Disturb feature.
Parameters
DWORD dwSupportEncoding
This parameter indicates the Support Encoding for the Unicode Party names that are being sent in device-specific extension of the LINECALLINFO structure.
The typical values could be
enum {UnknownEncoding = 0, // Unknown encodingNotApplicableEncoding = 1, // Encoding not applicable to this deviceAsciiEncoding = 2, // ASCII encodingUcs2UnicodeEncoding = 3 // UCS-2 Unicode encoding}
Note
LPCSTR lpszAlternateScript
This parameter specifies the alternate script that the device supports. An empty string indicates the device does not support or is not configured with an alternate script.
The only supported script in this release is "Kanji" for the Japanese locale.
m_LineDevStatus_DoNotDisturbOption
This field contains DND option that is configured for the device and can comprise one of the following enum values:
enum CiscoDoNotDisturbOption {DoNotDisturbOption_NONE = 0,DoNotDisturbOption_RINGEROFF = 1,DoNotDisturbOption_REJECT = 2};m_LineDevStatus_ DoNotDisturbStatus field contains current DND status on the device and can be one of the following enum values:enum CiscoDoNotDisturbStatus {DoNotDisturbStatus_UNKNOWN = 0,DoNotDisturbStatus_ENABLED = 1,DoNotDisturbStatus_DISABLED = 2};
Note
CCiscoLineDevSpecific
This section provides information on how to perform Cisco Unified 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.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificMsgWaiting|+-- CCiscoLineDevSpecificMsgWaitingDirn|+-- CCiscoLineDevSpecificUserControlRTPStream|+--CciscoLineDevSpecificSetStatusMsgs|+--CCiscoLineDevSpecificRedirectResetOrigCalled|+--CCiscoLineDevSpecificPortRegistrationPerCall|+--CciscoLineDevSpecificSetRTPParamsForCall|+--CCiscoLineDevSpecificRedirectSetOrigCalled|+--CCiscoLineDevSpecificJoin|+--CciscoLineDevSpecificUserSetSRTPAlgorithmID|+--CCiscoLineDevSpecificAcquire|+--CciscoLineDevSpecificDeacquire|+-- CciscoLineDevSpecificSendLineOpen|+-- CCiscoLineDevSpecificSetIntercomSpeedDial|+-- CCiscoLineDevSpecificTalkBack|+-- CciscoLineRedirectWithFeaturePriority|+--CCiscoLineDevSpecificStartCallMonitoringReq|+--CCiscoLineDevSpecificStartCallRecordingReq|+--CCiscoLineDevSpecificStopCallRecordingReq|+-- CciscoLineDevSpecificDirectTransfer|+-- CCiscoLineDevSpecificMsgSummary|+-- CCiscoLineDevSpecificMsgSummaryDirnHeader 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()
You can use function 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 includes a different value that is assigned to the parameter m_MsgType. If you are using C instead of C++, this represents 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_NUM_TYPE,SLDST_SWAP_HOLD_SETUP_TRANSFER, // Not Supported in Cisco TSP 3.4 and BeyondSLDST_REDIRECT_RESET_ORIG_CALLED,SLDST_USER_RECEIVE_RTP_INFO,SLDST_USER_SET_RTP_INFO,SLDST_JOIN,SLDST_USER_SET_SRTP_ALGORITHM_ID,SLDST_SEND_LINE_OPEN,};Message Waiting
The CCiscoLineDevSpecificMsgWaiting class turns the message waiting lamp on or off for the line that the hLine parameter specifies.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificMsgWaitingClass 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.
Note
Message Waiting Dirn
The CCiscoLineDevSpecificMsgWaitingDirn class turns the message waiting lamp on or off for the line that a parameter specifies and remains independent of the hLine parameter.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificMsgWaitingDirnClass 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
Specifies SLDST_MSG_WAITING_DIRN.
DWORD m_BlinkRate
As in the CCiscoLineDevSpecificMsgWaiting message.
Note
char m_Dirn[25]
The directory number for which the message waiting lamp should be set.
Message Summary
Use the CCiscoLineDevSpecificMsgSummary class to turn the message waiting lamp on or off as well as to provide voice and fax message counts for the line specified by the hLine parameter.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificMsgSummaryClass Detail
class CCiscoLineDevSpecificMsgSummary : public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificMsgSummary() : CCiscoLineDevSpecific(SLDST_MSG_SUMMARY){}virtual ~CCiscoLineDevSpecificMsgSummary() {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;}DWORD m_BlinkRate;MSG_SUMMARY m_MessageSummary;};Parameters
DWORD m_MsgType
equals SLDST_MSG_SUMMARY.
DWORD m_BlinkRate
is any supported PHONELAMPMODE_ constants specified in the phoneSetLamp() function.
MSG_SUMMARY m_MessageSummary
A data structure with the following format:
typedef struct {DWORD m_voiceCounts; // indicates if new voice counts are// provided. True=counts will be displayed// on supported phones.DWORD m_totalNewVoiceMsgs; // specifies the total number of new// voice messages. This number includes all// the high and normal priority voice// messages that are new.DWORD m_totalOldVoiceMsgs; // specifies the total number of old// voice messages. This number includes all// high and normal priority voice messages// that are old.DWORD m_highPriorityVoiceCounts; // indicates if old voice// counts are provided. True=counts will be// displayed on supported phones.DWORD m_newHighPriorityVoiceMsgs; //specifies the number of new// high priority voice messages.DWORD m_oldHighPriorityVoiceMsgs; //specifies the number of old// high priority voice messages.DWORD m_faxCounts; // indicates if new fax counts are// provided. True=counts will be displayed// on supported phones.DWORD m_totalNewFaxMsgs; // specifies the total number of new// fax messages. This number includes all// the high and normal priority fax// messages that are new.DWORD m_totalOldFaxMsgs; // specifies the total number of old// fax messages. This number includes all// high and normal priority fax messages// that are old.DWORD m_highPriorityFaxCounts; // indicates if old fax counts// are provided. True=counts will be// displayed on supported phones.DWORD m_newHighPriorityFaxMsgs; // specifies the number of new// high priority fax messages.DWORD m_oldHighPriorityFaxMsgs; // specifies the number of old// high priority fax messages.} MSG_SUMMARY;Message Summary Dirn
Use the CCiscoLineDevSpecificMsgSummaryDirn class to turn the message waiting lamp on or off and to provide voice and fax message counts for the line specified by a parameter and is independent of the hLine parameter.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificMsgSummaryDirnClass Detail
class CCiscoLineDevSpecificMsgSummaryDirn : public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificMsgSummaryDirn() : CCiscoLineDevSpecific(SLDST_MSG_SUMMARY_DIRN) {}virtual ~CCiscoLineDevSpecificMsgSummaryDirn() {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;}DWORD m_BlinkRate;char m_Dirn[25];MSG_SUMMARY m_MessageSummary;};Parameters
DWORD m_MsgType
equals SLDST_MSG_SUMMARY_DIRN.
DWORD m_BlinkRate
is as in the CCiscoLineDevSpecificMsgSummary message.
char m_Dirn[25]
is the directory number for which the message waiting lamp should be set.
MSG_SUMMARY m_MessageSummary
A data structure with the following format:
typedef struct {
DWORD m_voiceCounts; // indicates if new voice counts are
// provided. True=counts will be displayed
// on supported phones.
DWORD m_totalNewVoiceMsgs; // specifies the total number of new
// voice messages. This number includes all
// the high and normal priority voice
// messages that are new.
DWORD m_totalOldVoiceMsgs; // specifies the total number of old
// voice messages. This number includes all
// high and normal priority voice messages
// that are old.
DWORD m_highPriorityVoiceCounts; // indicates if old voice
// counts are provided. True=counts will be
// displayed on supported phones.
DWORD m_newHighPriorityVoiceMsgs; //specifies the number of new
// high priority voice messages.
DWORD m_oldHighPriorityVoiceMsgs; //specifies the number of old
// high priority voice messages.
DWORD m_faxCounts; // indicates if new fax counts are
// provided. True=counts will be displayed
// on supported phones.
DWORD m_totalNewFaxMsgs; // specifies the total number of new
// fax messages. This number includes all
// the high and normal priority fax
// messages that are new.
DWORD m_totalOldFaxMsgs; // specifies the total number of old
// fax messages. This number includes all
// high and normal priority fax messages
// that are old.
DWORD m_highPriorityFaxCounts; // indicates if old fax counts
// are provided. True=counts will be
// displayed on supported phones.
DWORD m_newHighPriorityFaxMsgs; // specifies the number of new
// high priority fax messages.
DWORD m_oldHighPriorityFaxMsgs; // specifies the number of old
// high priority fax messages.
} MSG_SUMMARY;
Audio Stream Control
The CCiscoLineDevSpecificUserControlRTPStream class controls the audio stream of a line. To use this class you must call the lineNegotiateExtVersion API before opening the line. When lineNegotiateExtVersion is called ensure the highest bit is 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.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificUserControlRTPStreamProcedure
Step 1
Step 2
Step 3
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 IPDWORD m_ReceivePort; // UDP audio reception portDWORD 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 indicates the maximum desired RTP packet size in milliseconds. Typically, this value gets set to 20.
G723BitRate specifies a 6-byte field that contains either the G.723.1 information bit rate, or it gets ignored. The following list provides values for the G.723.1 field values:
enum{Media_G723BRate_5_3 = 1, //5.3KbpsMedia_G723BRate_6_4 = 2 //6.4Kbps} Media_G723BitRate;Set Status Messages
Use the CCiscoLineDevSpecificSetStatusMsgs class to turn on or off the status messages for the line that the hLine parameter specifies. The Cisco Unified TSP supports the following flags:
•
•
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificSetStatusMsgsClass 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
Identifies which status changes cause a LINE_DEVSPECIFIC message to be sent to the application.
The supported values follow:
#define DEVSPECIFIC_MEDIA_STREAM 0x00000001#define DEVSPECIFIC_CALL_TONE_CHANGED 0x00000002#define CALL_DEVSPECIFIC_RTP_EVENTS 0x00000003#define DEVSPECIFIC_IDLE_TRANSFER_REASON 0x00000004#define DEVSPECIFIC_SPEEDDIAL_CHANGED 0x00000008#define DEVSPECIFIC_PARK_STATUS 0x00000080Swap-Hold/SetupTransfer
Note
The CCiscoLineDevSpecificSwapHoldSetupTransfer class gets used to perform a SetupTransfer between a call that is in CONNECTED state and a call that is in the ONHOLD state. This function changes the state of the connected call to ONHOLDPENDTRANSFER state and the ONHOLD call to CONNECTED state. This allows a CompleteTransfer to be performed on the two calls. In Cisco Unified TSP 4.0 and later, the TSP allows applications to use lineCompleteTransfer() to transfer the calls without having to use the CCiscoLineDevSpecificSwapHoldSetupTransfer function. Therefore, this function returns LINEERR_OPERATIONUNAVAIL in Cisco Unified TSP 4.0 and beyond.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificSwapHoldSetupTransfer
Note
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|+-- CCiscoLineDevSpecificRedirectResetOrigCalledDescription
The CCiscoLineDevSpecificRedirectResetOrigCalled class redirects a call to another party while it resets the original called ID of the call to the destination of the redirect.
Note
Class Details
class CCiscoLineDevSpecificRedirectResetOrigCalled: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificRedirectResetOrigCalled: CCiscoLineDevSpecific(SLDST_REDIRECT_RESET_ORIG_CALLED) {}virtual ~CCiscoLineDevSpecificRedirectResetOrigCalled{}char m_DestDirn[25]; //redirect destination addressvirtual 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.
Port Registration per Call
The CCiscoLineDevSpecificPortRegistrationPerCall class registers the CTI Port for the RTP parameters on a per-call basis. With this request, the application receives the new lineDevSpecific event that requests that it needs to set the RTP parameters for the call.
To use this class, ensure the lineNegotiateExtVersion API is called before opening the line. When calling lineNegotiateExtVersion, ensure the highest bit is 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 extra information required is provided in the CciscoLineDevSpecificPortRegistrationPerCall class.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificPortRegistrationPerCallProcedure
Step 1
Step 2
Step 3
Note
Class Details
class CCiscoLineDevSpecificPortRegistrationPerCall: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificPortRegistrationPerCall () :CCiscoLineDevSpecific(SLDST_USER_RECEIVE_RTP_INFO),m_RecieveIP(-1), m_RecievePort(-1), m_NumAffectedDevices(0){memset((char*)m_AffectedDeviceID, 0, sizeof(m_AffectedDeviceID));}virtual ~ CCiscoLineDevSpecificPortRegistrationPerCall () {}DWORD m_NumAffectedDevices;DWORD m_AffectedDeviceID[10];DWORD m_MediaCapCount;MEDIA_CAPS m_MediaCaps;virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_USER_RECEIVE_RTP_INFO
DWORD m_NumAffectedDevices:
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]:
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 applies for each member in the MEDIA_CAPS data structure:
MediaPayload is 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;MaxFramesPerPacket should read as MaxPacketSize and comprises a 16 bit integer that is specified in milliseconds. It indicates the RTP packet size. Typically, this value gets set to 20.
G723BitRate comprises a six byte field that contains either the G.723.1 information bit rate, or gets ignored. The values for the G.723.1 field comprises values that are enumerated as follows.
enum{Media_G723BRate_5_3 = 1, //5.3KbpsMedia_G723BRate_6_4 = 2 //6.4Kbps} Media_G723BitRate;Setting RTP Parameters for Call
The CCiscoLineDevSpecificSetRTPParamsForCall class sets the RTP parameters for a specific call.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificSetRTPParamsForCallClass Details
class CciscoLineDevSpecificSetRTPParamsForCall: public CCiscoLineDevSpecific{public:CciscoLineDevSpecificSetRTPParamsForCall () :CCiscoLineDevSpecific(SLDST_USER_SET_RTP_INFO) {}virtual ~ CciscoLineDevSpecificSetRTPParamsForCall () {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointerDWORD m_RecieveIP; // UDP audio reception IPDWORD m_RecievePort; // UDP audio reception port};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_RTP_INFO
DWORD m_ReceiveIP
This specifies the RTP audio reception IP address in the network byte order to set for the call.
DWORD m_ReceivePort
This specifies the RTP audio reception port in the network byte order to set for the call.
Redirect Set Original Called ID
The CCiscoLineDevSpecificRedirectSetOrigCalled class redirects a call to another party while it sets the original called ID of the call to any other party.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificRedirectSetOrigCalledClass Details
class CCiscoLineDevSpecificRedirectSetOrigCalled: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificRedirectSetOrigCalled () : CCiscoLineDevSpecific(SLDST_REDIRECT_SET_ORIG_CALLED) {}virtual ~ CCiscoLineDevSpecificRedirectSetOrigCalled () {}char m_DestDirn[25];char m_SetOriginalCalledTo[25];// subtract virtual function table pointervirtual DWORD dwSize(void) const {return (sizeof (*this) - 4) ;}Parameters
DWORD m_MsgType
Equals SLDST_REDIRECT_SET_ORIG_CALLED
char m_DestDirn[25]
Indicates the destination of the redirect. If this request is being used to transfer to voice mail, set this field to the voice mail pilot number of the DN of the line for the voice mail, to which you want to transfer.
char m_SetOriginalCalledTo[25]
Indicates the DN to which the OriginalCalledParty needs to be set. If this request is being used to transfer to voice mail, set this field to the DN of the line for the voice mail, to which you want to transfer.
HCALL hCall (in lineDevSpecific parameter list)
Equals the handle of the connected call.
Join
The CCiscoLineDevSpecificJoin class joins two or more calls into one conference call. Each call that is being joined can be in the ONHOLD or the CONNECTED call state.
The Cisco Unified Communications Manager may succeed in joining some calls that are specified in the Join request, but not all. In this case, the Join request will succeed and the Cisco Unified Communications Manager attempts to join as many calls as possible.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificJoinClass Details
class CCiscoLineDevSpecificJoin : public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificJoin () : CCiscoLineDevSpecific(SLDST_JOIN) {}virtual ~ CCiscoLineDevSpecificJoin () {}DWORD m_CallIDsToJoinCount;CALLIDS_TO_JOIN m_CallIDsToJoin;virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_JOIN
DWORD m_CallIDsToJoinCount
The number of callIDs that are contained in the m_CallIDsToJoin parameter.
CALLIDS_TO_JOIN m_CallIDsToJoin
A data structure that contains an array of dwCallIDs to join with the following format:
typedef struct {DWORD CallID; // dwCallID to Join} CALLIDS_TO_JOIN[MAX_CALLIDS_TO_JOIN];where MAX_CALLIDS_TO_JOIN is defined as:
const DWORD MAX_CALLIDS_TO_JOIN = 14;HCALL hCall (in LineDevSpecific parameter list)
Equals the handle of the call that is being joined with callIDsToJoin to create the conference.
Set User SRTP Algorithm IDs
The CciscoLineDevSpecificUserSetSRTPAlgorithmID class gets used to allow applications to set SRTP algorithm IDs. To use this class, ensure the lineNegotiateExtVersion API is called before opening the line. When calling lineNegotiateExtVersion, ensure the highest bit or second highest bit is set on both the dwExtLowVersion and dwExtHighVersion parameters. This causes the call to lineOpen to behave differently. The line does not actually opens, but waits for a lineDevSpecific call to complete the open with more information. Provide the extra information that is required in the CciscoLineDevSpecificUserSetSRTPAlgorithmID class.
Note
CCiscoLineDevSpecific|+-- CciscoLineDevSpecificUserSetSRTPAlgorithmIDProcedure
Step 1
Step 2
Step 3
Step 4
Class Detail
class CciscoLineDevSpecificUserSetSRTPAlgorithmID: public CCiscoLineDevSpecific{public:CciscoLineDevSpecificUserSetSRTPAlgorithmID () :CCiscoLineDevSpecific(SLDST_USER_SET_SRTP_ALGORITHM_ID),m_SRTPAlgorithmCount(0),m_SRTP_Fixed_Element_Size(4){}virtual ~ CciscoLineDevSpecificUserSetSRTPAlgorithmID () {}DWORD m_SRTPAlgorithmCount; //Maximum is MAX_CISCO_SRTP_ALGORITHM_IDSDWORD m_SRTP_Fixed_Element_Size;//Should be size of DWORD, it should be always 4.DWORD m_SRTPAlgorithm_Offset; //offset from beginning of the message buffervirtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Supported Algorithm Constants
enum CiscoSRTPAlgorithmIDs{SRTP_NO_ENCRYPTION=0,SRTP_AES_128_COUNTER=1};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_SRTP_ALGORITHM_ID
DWORD m_SRTPAlgorithmCount
This numbers of algorithm IDs that are specified in this message.
DWORD m_SRTP_Fixed_Element_Size
Should be size of DWORD, it should be always 4.
DWORD m_SRTPAlgorithm_Offset
Offset from the beginning of the message buffer. This is offset where you start put algorithm ID array.
Note
Explicit Acquire
The CCiscoLineDevSpecificAcquire class gets used to explicitly acquire any CTI controllable device.
If a Superprovider application needs to open any CTI Controllable device on the Cisco Unified Communications Manager system, the application should explicitly acquire that device by using the above interface. After successful response, it can open the device as usual.
Note
CCiscoLineDevSpecific|+--CCiscoLineDevSpecificAcquireClass Details
class CCiscoLineDevSpecificAcquire : public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificAcquire () : CCiscoLineDevSpecific(SLDST_ACQUIRE) {}virtual ~ CCiscoLineDevSpecificAcquire () {}char m_DeviceName[16];virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_ACQUIRE
m_DeviceName[16]
The DeviceName that needs to be explicitly acquired.
Explicit De-Acquire
The CCiscoLineDevSpecificDeacquire class is used to explicitly de-acquire the explicitly acquired device.
If a Superprovider application has explicitly acquired any CTI Controllable device on the Cisco Unified Communications Manager system, then the application should explicitly De-acquire that device by using the above interface.
Note
CCiscoLineDevSpecific|+--CCiscoLineDevSpecificDeacquireClass Details
class CCiscoLineDevSpecificDeacquire : public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificDeacquire () : CCiscoLineDevSpecific(SLDST_ACQUIRE) {}virtual ~ CCiscoLineDevSpecificDeacquire () {}char m_DeviceName[16];virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_DEACQUIRE
char m_DeviceName[16]
The DeviceName that needs to be explicitly de-acquired.
Redirect FAC CMC
The CCiscoLineDevSpecificRedirectFACCMC class is used to redirect a call to another party that requires a FAC, CMC, or both.
Note
CCiscoLineDevSpecific | +--CCiscoLineDevSpecificRedirectFACCMCIf the FAC is invalid, the TSP will return a new device-specific error code LINEERR_INVALIDFAC. If the CMC is invalid, the TSP will return a new device-specific error code LINEERR_INVALIDCMC.
Class Detail
class CCiscoLineDevSpecificRedirectFACCMC: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificRedirectFACCMC () : CCiscoLineDevSpecific(SLDST_REDIRECT_FAC_CMC) {}virtual ~ CCiscoLineDevSpecificRedirectFACCMC () {}char m_DestDirn[49];char m_FAC[17];char m_CMC[17];// subtract virtual function table pointervirtual DWORD dwSize(void) const {return (sizeof (*this) - 4) ;}Parameters
DWORD m_MsgType
Equals SLDST_REDIRECT_FAC_CMC
char m_DestDirn[49]
Indicates the destination of the redirect.
char m_FAC[17]
Indicates the FAC digits. If the application does not want to pass any FAC digits, it must set this parameter to a NULL string.
char m_CMC[17]
Indicates the CMC digits. If the application does not want to pass any CMC digits, it must set this parameter to a NULL string.
HCALL hCall (in lineDevSpecific parameter list)
Equals the handle of the call to be redirected.
Blind Transfer FAC CMC
The CCiscoLineDevSpecificBlindTransferFACCMC class is used to blind transfer a call to another party that requires a FAC, CMC, or both. If the FAC is invalid, the TSP will return a new device specific error code LINEERR_INVALIDFAC. If the CMC is invalid, the TSP will return a new device specific error code LINEERR_INVALIDCMC.
Note
CCiscoLineDevSpecific|+--CCiscoLineDevSpecificBlindTransferFACCMCClass Detail
class CCiscoLineDevSpecificBlindTransferFACCMC: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificBlindTransferFACCMC () : CCiscoLineDevSpecific(SLDST_BLIND_TRANSFER_FAC_CMC) {}virtual ~ CCiscoLineDevSpecificBlindTransferFACCMC () {}char m_DestDirn[49];char m_FAC[17];char m_CMC[17];// subtract virtual function table pointervirtual DWORD dwSize(void) const {return (sizeof (*this) - 4) ;}Parameters
DWORD m_MsgType
Equals SLDST_BLIND_TRANSFER_FAC_CMC
char m_DestDirn[49]
Indicates the destination of the blind transfer.
char m_FAC[17]
Indicates the FAC digits. If the application does not want to pass any FAC digits, it must set this parameter to a NULL string.
char m_CMC[17]
Indicates the CMC digits. If the application does not want to pass any CMC digits, it must set this parameter to a NULL string.
HCALL hCall (in lineDevSpecific parameter list)
Equals the handle of the call that is to be blind transferred.
CTI Port Third Party Monitor
The CCiscoLineDevSpecificCTIPortThirdPartyMonitor class is used for opening CTI ports in third- party mode.
To use this class, ensure the lineNegotiateExtVersion API is called before opening the line. When calling lineNegotiateExtVersion, ensure the highest bit is 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. Provide the extra information that is required in the CCiscoLineDevSpecificCTIPortThirdPartyMonitor class.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificCTIPortThirdPartyMonitorProcedure
Step 1
Step 2
Step 3
Note
Class Detail
class CCiscoLineDevSpecificCTIPortThirdPartyMonitor: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificCTIPortThirdPartyMonitor () :CCiscoLineDevSpecific(SLDST_CTI_PORT_THIRD_PARTY_MONITOR) {}virtual ~ CCiscoLineDevSpecificCTIPortThirdPartyMonitor () {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
equals SLDST_CTI_PORT_THIRD_PARTY_MONITOR
Send Line Open
The CciscoLineDevSpecificSendLineOpen class is used for general delayed open purpose. To use this class, ensure the lineNegotiateExtVersion API is called before opening the line. When calling lineNegotiateExtVersion, ensure the second highest bit is 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 extra information required is provided in the CciscoLineDevSpecificUserSetSRTPAlgorithmID class.
CCiscoLineDevSpecific|+-- CciscoLineDevSpecificSendLineOpenProcedure
Step 1
Step 2
Step 3
Step 4
Note
Class Detail
class CciscoLineDevSpecificSendLineOpen: public CCiscoLineDevSpecific{public:CciscoLineDevSpecificSendLineOpen () :CCiscoLineDevSpecific(SLDST_SEND_LINE_OPEN) {}virtual ~ CciscoLineDevSpecificSendLineOpen () {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Set Intercom SpeedDial
Use the CciscoLineSetIntercomSpeeddial class to allow application to set or reset SpeedDial/Label on an intercom line.
Note
CCiscoLineDevSpecific|+-- CciscoLineSetIntercomSpeeddialProcedure
Step 1
Step 2
Step 3
Step 4
Class Detail
class CciscoLineSetIntercomSpeeddial: public CCiscoLineDevSpecific{public:CciscoLineSetIntercomSpeeddial () :CCiscoLineDevSpecific(SLDST_LINE_SET_INTERCOM_SPEEDDIAL) {}virtual ~ CciscoLineSetIntercomSpeeddial () {}DWORD SetOption; //0=clear app value, 1= set App Valuechar Intercom_DN[MAX_DIRN];char Intercom_Ascii_Label[MAX_DIRN];wchar_t Intercom_Unicode_Label[MAX_DIRN];virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_INTERCOM_SPEEDDIAL
DWORD SetOption
Use this parameter to indicate whether the application wants to set a new intercom speed dial value or clear the previous value. 0 = clear, 1 = set.
Char Intercom_DN [MAX_DIRN]
A DN array that indicates the intercom target
Char Intercom_Ascii_Label[MAX_DIRN]
Indicates the ASCII value of the intercom line label
Wchar_tIntercom_Unicode_Label[MAX_DIRN]
Indicates the Unicode value of the intercom line label
MAX_DIRN is defined as 25.
Intercom Talk Back
Use the CCiscoLineDevSpecificTalkBack class to allow application to initiate talk back on an incoming intercom call on an intercom line.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificTalkBackClass Detail
class CCiscoLineDevSpecificTalkBack: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificTalkBack () :CCiscoLineDevSpecific(SLDST_INTERCOM_TALKBACK) {}virtual ~ CCiscoLineDevSpecificTalkBack () {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Redirect with Feature Priority
CciscoLineRedirectWithFeaturePriority enables an application to redirect calls with specified feature priorities. The following is the structure of CciscoLineDevSpecific:
CCiscoLineDevSpecific|+-- CciscoLineRedirectWithFeaturePriority
Note
Detail
class CciscoLineRedirectWithFeaturePriority: public CCiscoLineDevSpecific{public:CciscoLineRedirectWithFeaturePriority() :CCiscoLineDevSpecific(SLDST_REDIRECT_WITH_FEATURE_PRIORITY) {}virtual ~ CciscoLineRedirectWithFeaturePriority () {}CiscoDoNotDisturbFeaturePriority FeaturePriority;char m_DestDirn[25];virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_REDIRECT_WITH_FEATURE_PRIORITY
enum CiscoDoNotDisturbFeaturePriority {CallPriority_NORMAL = 1, CallPriority_URGENT = 2, CallPriority_EMERGENCY = 3};
This identifies the priorities.
char m_DestDirn[25];
This is redirect destination.
Start Call Monitoring
Use CCiscoLineDevSpecificStartCallMonitoring to allow application to send a start monitoring request for the active call on a line.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificStartCallMonitoringClass Detail
class CCiscoLineDevSpecificStartCallMonitoring: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificStartCallMonitoring () : CCiscoLineDevSpecific(SLDST_START_CALL_MONITORING) {}virtual ~ CCiscoLineDevSpecificStartCallMonitoring () {}DWORD m_PermanentLineID ;DWORD m_MonitorMode;DWORD m_ToneDirection;// subtract out the virtual function table pointervirtual DWORD dwSize(void) const {return sizeof(*this)-4;}} ;Parameters
DWORD m_MsgType
Equals SLDST_START_MONITORING
DWORD m_ PermanentLineID
The permanent lineID of the line whose active call has to be monitored.
DWORD MonitorMode
This can have the following enum value:
enum{MonitorMode_None = 0,MonitorMode_Silent = 1,MonitorMode_Whisper = 2, // Not usedMonitorMode_Active = 3 // Not used} MonitorMode;
Note
DWORD PlayToneDirection
This parameter specifies whether a tone should play at the agent or customer phone when monitoring starts. It can have following enum values:
enum{PlayToneDirection_LocalOnly = 0,PlayToneDirection_RemoteOnly,PlayToneDirection_BothLocalAndRemote,PlayToneDirection_NoLocalOrRemote} PlayToneDirectionReturn Values
- LINERR_OPERATIONFAILED- LINEERR_OPERATIONUNAVAIL- LINEERR_RESOURCEUNAVAIL- LINEERR_BIB_RESOURCE_UNAVAIL- LINERR_PENDING_REQUEST- LINEERR_OPERATION_ALREADY_INPROGRESS- LINEERR_ALREADY_IN_REQUESTED_STATE- LINEERR_PRIMARY_CALL_INVALID- LINEERR_PRIMARY_CALL_STATE_INVALIDStart Call Recording
Use CCiscoLineDevSpecificStartCallRecording to allow applications to send a recording request for the active call on that line.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificStartCallRecordingClass Detail
class CCiscoLineDevSpecificStartCallRecording: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificStartCallRecording () : CCiscoLineDevSpecific(SLDST_START_CALL_RECORDING) {}virtual ~ CCiscoLineDevSpecificStartCallRecording () {}DWORD m_ToneDirection;// subtract out the virtual function table pointervirtual DWORD dwSize(void) const {return sizeof(*this)-4;}} ;Parameters
DWORD m_MsgType
Equals SLDST_START_RECORDING
DWORD PlayToneDirection
This parameter specifies whether a tone should play at the agent or customer phone when recording starts. It can have following enum values:
enum{PlayToneDirection_NoLocalOrRemote = 0,PlayToneDirection_LocalOnly,PlayToneDirection_RemoteOnly,PlayToneDirection_BothLocalAndRemote} PlayToneDirectionReturn Values
- LINERR_OPERATIONFAILED- LINEERR_OPERATIONUNAVAIL- LINEERR_INVALCALLHANDLE- LINEERR_BIB_RESOURCE_UNAVAIL- LINERR_PENDING_REQUEST- LINERR_OPERATION_ALREADY_INPROGRESSStopCall Recording
Use CCiscoLineDevSpecificStopCallRecording to allow application to stop recording a call on that line.
Note
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificStopCallRecordingClass Detail
class CCiscoLineDevSpecificStopCallRecording: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificStopCallRecording () : CCiscoLineDevSpecific(SLDST_STOP_CALL_RECORDING) {}virtual ~ CCiscoLineDevSpecificStopCallRecording () {}// subtract out the virtual function table pointervirtual DWORD dwSize(void) const {return sizeof(*this)-4;}} ;Parameters
DWORD m_MsgType
Equals SLDST_STOP_RECORDING
Return Values
- LINERR_OPERATIONFAILED- LINEERR_OPERATIONUNAVAIL- LINEERR_INVALCALLHANDLE- LINERR_PENDING_REQUESTSet IP Address Mode
Use CCiscoLineDevSpecificSetIPAddressMode to enable the application to set the address mode during registration. To use this class, ensure that lineNegotiateExtVersion API is called before opening the line. When calling lineNegotiateExtVersion, ensure the highest bit or second highest is 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. Provide the extra information required in the CCiscoLineDevSpecificSetIPAddressMode class.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificSetIPAddressMode
Note
Procedure
Step 1
Step 2
Step 3
Supported Address Modes
enum CiscoIPAddressMode
{IP_ADDRESS_V4=1,IP_ADDRESS_V6=2,IP_ADDRESS_V4_V6=3};Class Detail
class CCiscoLineDevSpecificSetIPAddressMode: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificSetIPAddressMode () :CCiscoLineDevSpecific(SLDST_USER_SET_IP_ADDRESS_MODE),m_IPAddressMode(0){}virtual ~ CCiscoLineDevSpecificSetIPAddressMode () {}int m_ IPAddressMode; //Addressing Mode to be specifiedvirtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_IP_ADDRESS_MODE
int m_ IPAddressMode
This specifies the Addressing mode with which user wants the CTI Port/RP registered.
Set IPv6 Address
Use CCiscoLineDevSpecificSetIPv6Address class to allow the application to set IPv6 address during static registration. To use this class, ensure the lineNegotiateExtVersion API must be called before opening the line. When calling lineNegotiateExtVersion, ensure the highest bit or second highest 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 extra information required is provided in the CCiscoLineDevSpecificSetIPv6Address class.
CCiscoLineDevSpecific|+-- CCiscoLineDevSpecificSetIPv6Address
Note
Procedure
Step 1
Step 2
Step 3
Step 4
Class Detail
class CCiscoLineDevSpecificSetIPv6Address: public CCiscoLineDevSpecific{public:CCiscoLineDevSpecificSetIPv6Address () :CCiscoLineDevSpecific(SLDST_USER_SET_IPv6_ADDRESS),m_ReceiveIPv6Address(-1), m_ReceivePort(-1){}virtual ~ CCiscoLineDevSpecificSetIPv6Address () {}char m_ReceiveIPv6Address[16]; //Ipv6 address that user wants to specifyDWORD m_ReceivePort;virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_IPv6_ADDRESS
char m_ReceiveIPv6Address[16]
User has to specify the IPv6 address to register the CTI Port with
DWORD m_ReceivePort
This specifies the port number for the user to register the CTI Port.
Set RTP Parameters for IPv6 Calls
Use CciscoLineDevSpecificSetRTPParamsForCallIPv6 class to set the RTP parameters for calls for which you must specify IPv6 address.
Note
Class Detail
class CciscoLineDevSpecificSetRTPParamsForCallIPv6: public CCiscoLineDevSpecific{public:CciscoLineDevSpecificSetRTPParamsForCallIPv6 () :CCiscoLineDevSpecific(SLDST_USER_SET_RTP_INFO_IPv6) {}virtual ~ CciscoLineDevSpecificSetRTPParamsForCallIPv6 () {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;} // subtract out the virtual function table pointerchar m_RecieveIPv6[16]; // UDP audio reception IPv6DWORD m_RecievePort // UDP audio reception port};Parameters
DWORD m_MsgType
Equals SLDST_USER_SET_RTP_INFO_IPv6
DWORD m_ReceiveIPv6
This is the RTP audio reception IPv6 address to set for the call
DWORD m_RecievePort
This is the RTP audio reception port to set for the call.
Direct Transfer
Use the CciscoLineDevSpecificDirectTransfer to transfer calls across lines or on the same line.
CCiscoLineDevSpecific|+-- CciscoLineDevSpecificDirectTransfer
Note
Class Detail
class CciscoLineDevSpecificDirectTransfer: public CCiscoLineDevSpecific{public:CciscoLineDevSpecificDirectTransfer () : CCiscoLineDevSpecific(SLDST_DIRECT_TRANSFER) {}virtual ~ CciscoLineDevSpecificDirectTransfer () {}DWORD m_CallIDsToTransfer;virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
equals SLDST_ DIRECT_TRANSFER
DWORD m_CallIDsToTransfer
Consult dwCallID to be transferred
HCALL hCall (in LineDevSpecific parameter list)
Equals the handle of the call that is being transferred.
Cisco Line Device Feature Extensions
CCiscoLineDevSpecificFeature represents the parent class. Currently, it consist of only one subclass: CCiscoLineDevSpecificFeature_DoNotDisturb, which allows applications to enable and disable the Do-Not-Disturb feature on a device.
This section describes line device feature-specific extensions to the TAPI structures that Cisco TSP supports, and it contains the following structure:
•
LINEDEVCAPS
The CiscoLineDevCaps_DevSpecificFlags structure contains line device capability extension flags that describe the Cisco line device specific extensions for device capabilities. The m_LineDevCaps_DevSpecificFeatureFlags field in that structure reflects extended device feature capabilities. Currently, Cisco TSP uses only the LINEDEVCAPS_DEVSPECIFICFEATURE_DONOTDISTURB (0x00000001) bit in that field.
// Line device capability extention flagstypedef struct CiscoLineDevCaps_DevSpecificFlags{DWORD m_LineDevCaps_DevSpecificFlags; // LINEFEATURE_DEVSPECIFICDWORD m_LineDevCaps_DevSpecificFeatureFlags; // LINEFEATURE_DEVSPECIFICFEAT} CISCOLINEDEVCAPS_DEVSPECIFICFLAGS;// Bit assignments#define LINEDEVCAPS_DEVSPECIFICFEATURE_DONOTDISTURB 0x00000001 // Ext 00080000LINEDEVSTATUS
The LINEDEVSTATUS_DEV_SPECIFIC_DATA structure contains data for all device-specific extensions that Cisco TSP added to the TAPI LINEDEVSTATUS structure. The CiscoLineDevStatus_DoNotDisturb structure belongs to the LINEDEVSTATUS_DEV_SPECIFIC_DATA structure and reflects the current state of the Do-Not-Disturb feature.
Note
// LINEDEVSTATUS 00080000 extention //// ---------------------------------typedef struct CiscoLineDevStatus_DoNotDisturb{DWORD m_LineDevStatus_DoNotDisturbOption;DWORD m_LineDevStatus_DoNotDisturbStatus;} CISCOLINEDEVSTATUS_DONOTDISTURB;The m_LineDevStatus_DoNotDisturbOption field contains DND option that is configured for the device and can comprise one of the following enum values:
enum CiscoDoNotDisturbOption {DoNotDisturbOption_NONE = 0,DoNotDisturbOption_RINGEROFF = 1,DoNotDisturbOption_REJECT = 2};The m_LineDevStatus_ DoNotDisturbStatus field contains current DND status on the device and can comprise one of the following enum values:
enum CiscoDoNotDisturbStatus {DoNotDisturbStatus_UNKNOWN = 0,DoNotDisturbStatus_ENABLED = 1,DoNotDisturbStatus_DISABLED = 2};CCiscoLineDevSpecificFeature
This section provides information on how to invoke Cisco-specific TAPI extensions with the CCiscoLineDevSpecificFeature class, which represents the parent class to all the following classes.
Note
CCiscoLineDevSpecificFeatureHeader File
The file CiscoLineDevSpecific.h contains the corresponding constant, structure, and class definitions for the Cisco lineDevSpecificFeature extension classes.
Class Detail
class CCiscoLineDevSpecificFeature{public:CCicsoLineDevSpecificFeature(const DWORD msgType): m_MsgType(msgType) {;}virtual ~ CCicsoLineDevSpecificFeature() {;}DWORD GetMsgType(void) const {return m_MsgType;}void* lpParams(void) const {return (void*)&m_MsgType;}virtual DWORD dwSize(void) const = 0;private:DWORD m_MsgType;};Functions
lpParms()
Function that can be used to obtain a pointer to the parameter block
dwSize()
Function that returns size of the parameter block area
Parameter
m_MsgType
Specifies the type of message. The parameter value uniquely identifies the feature to invoke on the device. The PHONEBUTTONFUNCTION_ TAPI_Constants definition lists the valid feature identifiers. Currently, the only recognized value specifies PHONEBUTTONFUNCTION_DONOTDISTURB (0x0000001A).
Each subclass of CCiscoLineDevSpecificFeature includes a unique value that is assigned to the m_MsgType parameter.
Subclasses
Each subclass of CCiscoLineDevSpecificFeature carries a unique value that is assigned to the m_MsgType parameter. If you are using C instead of C++, this represents the first parameter in the structure.
Do-Not-Disturb
Use the CCiscoLineDevSpecificFeature_DoNotDisturb class in conjunction with the request to enable or disable the DND feature on a device.
The Do-Not-Disturb feature gives phone users the ability to go into a Do Not Disturb (DND) state on the phone when they are away from their phones or simply do not want to answer the incoming calls. A phone softkey, DND, allows users to enable or disable this feature.
CCiscoLineDevSpecificFeature|+-- CCiscoLineDevSpecificFeature_DoNotDisturbClass Detail
class CCiscoLineDevSpecificFeature_DoNotDisturb : public CCiscoLineDevSpecificFeature{public:CCiscoLineDevSpecificFeature_DoNotDisturb(): CCiscoLineDevSpecificFeature(PHONEBUTTONFUNCTION_DONOTDISTURB),m_Operation((CiscoDoNotDisturbOperation)0) {}virtual ~CCiscoLineDevSpecificFeature_DoNotDisturb() {}virtual DWORD dwSize(void) const {return sizeof(*this)-4;}CiscoDoNotDisturbOperation m_Operation;};Parameters
DWORD m_MsgType
Equals PHONEBUTTONFUNCTION_DONOTDISTURB.
CiscoDoNotDisturbOperation m_Operation
Specifies a requested operation and can comprise one of the following enum values:
enum CiscoDoNotDisturbOperation {DoNotDisturbOperation_ENABLE = 1,DoNotDisturbOperation_DISABLE = 2};Do-Not-Disturb Change Notification Event
Cisco TSP notifies applications via the LINE_DEVSPECIFICFEATURE message about changes in the DND configuration or status. To receive change notifications, an application needs to enable the DEVSPECIFIC_DONOTDISTURB_CHANGED message flag with a lineDevSpecific SLDST_SET_STATUS_MESSAGES request.
The LINE_DEVSPECIFICFEATURE message notifies the application about device-specific events that occur on a line device. In the case of a Do-Not-Disturb Change Notification, the message includes information about the type of change that occurred on a device and the resulting feature status or configured option.
Message Details
LINE_DEVSPECIFICFEATUREdwDevice = (DWORD) hLine;dwCallbackInstance = (DWORD) hCallback;dwParam1 = (DWORD) PHONEBUTTONFUNCTION_DONOTDISTURB;dwParam2 = (DWORD) typeOfChange;dwParam3 = (DWORD) currentValue;enum CiscoDoNotDisturbOption {DoNotDisturbOption_NONE = 0,DoNotDisturbOption_RINGEROFF = 1,DoNotDisturbOption_REJECT = 2};enum CiscoDoNotDisturbStatus {DoNotDisturbStatus_UNKNOWN = 0,DoNotDisturbStatus_ENABLED = 1,DoNotDisturbStatus_DISABLED = 2};enum CiscoDoNotDisturbNotification {DoNotDisturb_STATUS_CHANGED = 1,DoNotDisturb_OPTION_CHANGED = 2};Parameters
dwDevice
A handle to a line device
dwCallbackInstance
The callback instance that is supplied when the line is opened
dwParam1
Always equal to PHONEBUTTONFUNCTION_DONOTDISTURB for the Do-Not-Disturb change notification
dwParam2
Indicates type of change and can comprise one of the following enum values:
enum CiscoDoNotDisturbNotification {DoNotDisturb_STATUS_CHANGED = 1,DoNotDisturb_OPTION_CHANGED = 2};dwParam3
If the dwParm2 indicates status change with the value DoNotDisturb_STATUS_CHANGED, this parameter can comprise one of the following enum values:
enum CiscoDoNotDisturbStatus {DoNotDisturbStatus_UNKNOWN = 0,DoNotDisturbStatus_ENABLED = 1,DoNotDisturbStatus_DISABLED = 2};If the dwParm2 indicates option change with the value DoNotDisturb_OPTION_CHANGED, this parameter can comprise one of the following enum values:
enum CiscoDoNotDisturbOption {DoNotDisturbOption_NONE = 0,DoNotDisturbOption_RINGEROFF = 1,DoNotDisturbOption_REJECT = 2};Cisco Phone Device-Specific Extensions
Table 6-2 lists the subclasses of CiscoPhoneDevSpecific.
CCiscoPhoneDevSpecific
This section provides information on how to perform Cisco TAPI-specific functions with the CCiscoPhoneDevSpecific class, which represents the parent class to all the following classes.
Note
CCiscoPhoneDevSpecific|+-- CCiscoPhoneDevSpecificDataPassThroughHeader File
The file CiscoLineDevSpecific.h contains the constant, structure, and class definition for the Cisco phone device-specific classes.
Class Detail
class CCiscoPhoneDevSpecific{public :CCiscoPhoneDevSpecific(DWORD msgType):m_MsgType(msgType) {;}virtual ~CCiscoPhoneDevSpecific() {;}DWORD GetMsgType (void) const { return m_MsgType;}void *lpParams(void) const {return (void*)&m_MsgType;}virtual DWORD dwSize(void) const = 0;private :DWORD m_MsgType ;}Functions
lpParms()
Function that can be used to obtain the pointer to the parameter block
dwSize()
Function that will give the size of the parameter block area
Parameter
m_MsgType
Specifies the type of message.
Subclasses
Each subclass of CCiscoPhoneDevSpecific represents a different value that is assigned to the parameter m_MsgType. If you are using C instead of C++, this represents the first parameter in the structure.
Enumeration
The CiscoPhoneDevSpecificType enumeration includes valid message identifiers.
enum CiscoLineDevSpecificType {CPDST_DEVICE_DATA_PASSTHROUGH_REQUEST = 1};CCiscoPhoneDevSpecificDataPassThrough
XSI-enabled IP phones allow applications to directly communicate with the phone and access XSI features (for example, manipulate display, get user input, play tone, and so on). To allow TAPI applications to have access to some of these XSI capabilities without having to setup and maintain an independent connection directly to the phone, TAPI will provide the ability to send device data through the CTI interface. This feature gets exposed as a Cisco Unified TSP device-specific extension.
PhoneDevSpecificDataPassthrough request only gets supported for the IP phone devices. Application must open a TAPI phone device with minimum extension version 0x00030000 to make use of this feature.
The CCiscoPhoneDevSpecificDataPassThrough class is used to send the device-specific data to CTI- controlled IP phone devices.
Note
CCiscoPhoneDevSpecific|+-- CCiscoPhoneDevSpecificDataPassThroughClass Detail
class CCiscoPhoneDevSpecificDataPassThrough : public CCiscoPhoneDevSpecific{public:CCiscoPhoneDevSpecificDataPassThrough () :CCiscoPhoneDevSpecific(CPDST_DEVICE_DATA_PASSTHROUGH_REQUEST){memset((char*)m_DeviceData, 0, sizeof(m_DeviceData)) ;}virtual ~CCiscoPhoneDevSpecificDataPassThrough() {;}// data size determined by MAX_DEVICE_DATA_PASSTHROUGH_SIZETCHAR m_DeviceData[MAX_DEVICE_DATA_PASSTHROUGH_SIZE] ;// subtract out the virtual funciton table pointer sizevirtual DWORD dwSize (void) const {return (sizeof (*this)-4) ;}}Parameters
DWORD m_MsgType
Equals CPDST_DEVICE_DATA_PASSTHROUGH_REQUEST.
DWORD m_DeviceData
This character buffer contains the XML data that is to be sent to phone device.
Note
A phone can pass data to an application and it can get retrieved by using PhoneGetStatus (PHONESTATUS:devSpecificData). See PHONESTATUS description for further details.
CCiscoPhoneDevSpecificAcquire
The CCiscoPhoneDevSpecificAcquire class gets used to explicitly acquire any CTI controllable device.
If a Super-provider application needs to open any CTI-controllable device on the Cisco Unified Communications Manager system, the application should explicitly acquire that device by using the preceding interface. After successful response, it can open the device as usual.
Note
CCiscoPhoneDevSpecific|+-- CCiscoPhoneDevSpecificAcquireClass Details
class CCiscoPhoneDevSpecific Acquire : public CCiscoPhoneDevSpecific{public:CCiscoPhoneDevSpecificAcquire () : CCiscoPhoneDevSpecific (CPDST_ACQUIRE) {}virtual ~ CCiscoPhoneDevSpecificAcquire () {}char m_DeviceName[16];virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals CPDST_ACQUIRE
char m_DeviceName[16]
The DeviceName that needs to be explicitly acquired.
CCiscoPhoneDevSpecificDeacquire
The CCiscoPhoneDevSpecificDeacquire class gets used to explicitly de-acquire an explicitly acquired device.
If a SuperProvider application explicitly acquired any CTI-controllable device on the Unified Communications Manager system, the application should explicitly de-acquire that device by using this interface.
Note
CCiscoPhoneDevSpecific|+-- CCiscoPhoneDevSpecificDeacquireClass Details
class CCiscoPhoneDevSpecificDeacquire : public CCiscoPhoneDevSpecific{public:CCiscoPhoneDevSpecificDeacquire () : CCiscoPhoneDevSpecific (CPDST_ACQUIRE) {}virtual ~ CCiscoPhoneDevSpecificDeacquire () {}char m_DeviceName[16];virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals CPDST_DEACQUIRE
char m_DeviceName[16]
The DeviceName that needs to be explicitly de-acquired.
CCiscoPhoneDevSpecificGetRTPSnapshot
The CCiscoPhoneDevSpecificGetRTPSnapshot class gets used to request Call RTP snapshot event from the device. There will be LineCallDevSpecific event for each call on the device.
Note
CCiscoPhoneDevSpecific|+-- CCiscoPhoneDevSpecificGetRTPSnapshotClass Details
class CCiscoPhoneDevSpecificGetRTPSnapshot: public CCiscoPhoneDevSpecific{public:CCiscoPhoneDevSpecificGetRTPSnapshot () : CCiscoPhoneDevSpecific (CPDST_REQUEST_RTP_SNAPSHOT_INFO) {}virtual ~ CCiscoPhoneDevSpecificGetRTPSnapshot () {}char m_DeviceName[16];virtual DWORD dwSize(void) const {return sizeof(*this)-4;}// subtract out the virtual function table pointer};Parameters
DWORD m_MsgType
Equals CPDST_DEACQUIRE
char m_DeviceName[16]
The DeviceName that needs to be explicitly de-acquired.
Messages
This section describes the line device specific messages that the Cisco Unified TSP supports. An application receives nonstandard TAPI messages in the following LINE_DEVSPECIFIC messages:
•
•
•
•
The message type represents an enumerated integer with the following values:
enum CiscoLineDevSpecificMsgType{SLDSMT_START_TRANSMISION = 1,SLDSMT_STOP_TRANSMISION,SLDSMT_START_RECEPTION,SLDSMT_STOP_RECEPTION,SLDSMT_LINE_EXISTING_CALL,SLDSMT_OPEN_LOGICAL_CHANNEL,SLDSMT_CALL_TONE_CHANGED,SLDSMT_LINECALLINFO_DEVSPECIFICDATA,SLDSMT_NUM_TYPE,SLDSMT_LINE_PROPERTY_CHANGED,SLDSMT_MONITORING_STARTED,SLDSMT_MONITORING_ENDED,SLDSMT_RECORDING_STARTED,SLDSMT_RECORDING_ENDED};Start Transmission Events
SLDSMT_START_TRANSMISION
When a message is received, the RTP stream transmission starts and:
•
•
•
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:
•
•
•
At extension version 2.0 (0x00020000), start transmission uses the following format:
•
•
•
•
•
•
•
•
•
•
At extension version 4.0 (0x00040000), start transmission has the following format:
•
•
–
–
–
–
–
–
–
•
•
Start Reception Events
SLDSMT_START_RECEPTION
When a message is received, the RTP stream reception starts and:
•
•
•
When a message is received, the RTP stream reception should commence.
At extension version 1, the parameters have the following format:
•
•
•
At extension version 2 start reception uses the following format:
•
•
•
•
•
•
•
•
At extension version 4.0 (0x00040000), start reception uses the following format:
•
•
–
–
–
–
–
•
•
Stop Transmission Events
SLDSMT_STOP_TRANSMISION
When a message is received, transmission of the streaming should stop.
At extension version 1.0 (0x00010000), stop transmission uses the following format:
•
At extension version 4.0 (0x00040000), stop transmission uses the following format:
•
•
Stop Reception Events
SLDSMT_STOP_RECEPTION
When a message is received, reception of the streaming should stop.
At extension version 1.0 (0x00010000), stop reception uses the following format:
•
At extension version 4.0 (0x00040000), stop reception uses the following format:
•
•
Existing Call Events
SLDSMT_LINE_EXISTING_CALL
These events inform the application of existing calls in the PBX when it starts up. The format of the parameters follows:
•
•
•
Open Logical Channel Events
SLDSMT_OPEN_LOGICAL_CHANNEL
When a call has media established at a CTI Port or Route Point that is registered for Dynamic Port Registration, receipt of this message indicates that an IP address and UDP port number need to be set for the call.
Note
The following format of the parameters applies:
•
•
•
•
At extension version 9.0 (0x00090000), start transmission has the following format:
•
•
•
•
•
•
•
•
LINECALLINFO_DEVSPECIFICDATA Events
SLDSMT_LINECALLINFO_DEVSPECIFICDATA
This message indicates DEVSPECIFICDATA information changed in the DEVSPECIFIC portion of the LINECALLINFO structure for SRTP, QoS, Partition support, call security status, CallAttributeInfo, and CCM CallID.
Note
The following format applies for the parameters:
•
•
SLDSMT_LINECALLINFO_DEVSPECIFICDATA\•
SLDST_SRTP_INFO | SLDST_QOS_INFO | SLDST_PARTITION_INFO | SLDST_EXTENDED_CALL_INFO|SLDST_CALL_SECURITY_STATUS|SLDST_CALL_ATTRIBUTE_INFO |SLDST_CCM_CALLIDThe bit mask values follow:
SLDST_SRTP_INFO = 0x00000001SLDST_QOS_INFO = 0x00000002SLDST_PARTITION_INFO = 0x00000004SLDST_EXTENDED_CALL_INFO = 0x00000008SLDST_CALL_ATTRIBUTE_INFO = 0x00000010SLDST_CCM_CALLID = 0x00000020|SLDST_CALL_SECURITY_STATUS=0x00000040For example, if there are changes in SRTP and QoS but not in Partition, then both the SLDST_SRTP_INFO and SLDST_QOS_INFO bits will be set. The value for dwParam2 = SLDST_SRTP_INFO | SLDST_QOS_INFO = 0x00000011.
•
If a change occurs in the SRTP Information, this field would contain the CiscoSecurityIndicator.
enum CiscoSecurityIndicator{SRTP_MEDIA_ENCRYPT_KEYS_AVAILABLE,SRTP_MEDIA_ENCRYPT_USER_NOT_AUTH,SRTP_MEDIA_ENCRYPT_KEYS_UNAVAILABLE,SRTP_MEDIA_NOT_ENCRYPTED};
Note
Call Tone Changed Events
SLDSMT_CALL_TONE_CHANGED
When a tone change occurs on a call, receipt of this message indicates the tone and the feature that caused the tone change.
Note
The format of the parameters follows:
•
•
•
•
–
–
Note
