CIL Coding Conventions
This chapter discusses coding conventions used in the CTI OS Client Interface Library (CIL). Coding
conventions are standard ways of performing common tasks. While the rest of this document discusses the
programming interfaces available with the CIL, this chapter provides useful and practical explanation of
how to program with the CIL– the glue that brings everything together.
One of the design goals of the CTI OS CIL is to make programming as easy and consistent as possible for
client developers. As such, many design decisions about the CIL interfaces were made to keep things simple,
clear, and consistent across various objects, methods, and programming environments.
This chapter discusses the following topics:
•
Data types
•
Asynchronous execution (error codes versus events)
•
Generic interfaces with the Arguments structure
•
Optional and reserved parameters
•
Accessing properties and parameters with GetValue
•
Adding parameters to requests with AddItem
•
Setting properties with SetValue
•
UniqueObjectIDs: how to identify objects
•
Obtaining an object from its UniqueObjectID
•
Using Button Enablement Masks
•
Methods that call AddRef()
•
CTI OS CIL Data Types, page 2
•
Asynchronous Program Execution, page 3
•
CIL Error Codes, page 3
•
COM Error Codes, page 8
•
Generic Interfaces, page 9
•
UniqueObjectID Variable-Length String, page 11
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
1
•
UniqueObjectID to Obtain Pointer or Reference, page 12
•
Button Enablement Masks, page 13
CTI OS CIL Data Types
The CTI OS Client Interface Library is designed to be a single interface, which you can use across multiple
languages and environments (e.g. C++, COM, Visual Basic, Java, and .NET). However, each programming
language has its own native data types. Throughout this document, the interface parameters are listed with
the following standardized data types:
•
STRING: A variable-length string variable. If a maximum length exists, it is listed with the parameter
description.
•
INT: A 32-bit wide integer.
•
UNSIGNED INT: A 32-bit wide unsigned integer.
•
SHORT: A 16-bit wide short integer.
•
UNSIGNED SHORT: A 16-bit wide unsigned short integer.
•
BOOL: A logical true or false variable. Different implementations use variables of different sizes to
represent this type. In COM, the VARIANT_BOOL is used. Tests of variables of this data type must
be against VARIANT_TRUE and VARIANT_FALSE and not simply against 0 or 1.
•
ARGUMENTS: A custom data structure used by CTI OS, which holds a variable-length set of key-value
pairs.
•
ARG: An individual element (value), which can be stored in an ARGUMENTS structure.
The following table describes the appropriate language specific types to which the documented type are
associated.
Table 1: CTI OS CIL Data Type
ARGARGUMENTSBOOLUNSIGNED
SHORT
SHORTUNSIGNED
INT
INTSTRINGDocumented
Data Type
ArgArgumentsboolunsigned shortshortunsigned intlong or intstd::string
or const
char
C++ Type
ArgArgumentsBooleanIntegerIntegerNoneLongStringVisual Basic
6.0 Type
IArg*IArguments *VARIANT_BOOLunsigned shortshortunsigned intlong or intBSTRCOM Type
ArgArgumentsBooleanintshortlongintStringJava Type
ArgArgumentsSystem.BooleanSystem.Int32System.Int16System.Int64System.Int32System.String.NET Type
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
2
CIL Coding Conventions
CTI OS CIL Data Types
Asynchronous Program Execution
The most common programming approach used by applications is synchronous execution. In a synchronous
execution mode, a method call executes all the code required to complete the request and provide return values
as well as error codes. Client-server programming can be synchronous (the client application makes a blocking
request and continues execution when the request is completed) or asynchronous (the client application makes
a request and continues processing immediately, with the result of the request to follow at a later time).
CTI programming is unique in that requests are often serviced by third-party servers or applications, such as
a PBX/ACD in the contact center. The asynchronous nature of CTI programming requires developers to note
the distinction between an error code and the response to a request. In non-CTI programming, developers test
the error codes (return values from method calls) to determine whether a method request succeeded or failed.
However, in a distributed architecture such as CTI OS, success or failure is often determined by some external
server or component such as the PBX/ACD.
The CTI OS Client Interface Library API specifies error codes, which are return values for method calls.
These error codes relate to the success or failure of the method call, but not the success or failure of the
underlying operation. The success of the method call means that the parameters sent were of the correct format,
that internal memory allocations were successful, and that the request was put on the send queue to be
transmitted to the CTI OS Server. Generally, the CIL error code returned from method calls is CIL_OK,
indicating that the method call was successful. However, this does not indicate that the request was actually
serviced by the CTI OS Server or successfully completed at the PBX/ACD.
To determine the success or failure of the underlying telephony operation requested, the CTI programmer
must wait for an event confirming the success or failure of the request. To generalize the message flow model,
most requests made at the CTI OS CIL are answered with a confirmation message and/or an event message.
See the object interface reference in Chapters 8-12 for details on each particular request. This type of response
is called asynchronous—it can arrive at any time after the request is made, but typically requests are services
in sub-second timeframes.
The expected event sequence is described for each method request in the programmer's interface sections of
this document so that programmers know which events to expect. In the event of a request failure, an
eControlFailureConf message is sent to the client; the eControlFailureConf message has a parameter called
MessageType indicating which request failed, and a parameter called ErrorMessage, with a description of the
failure cause.
For example, when sending a MakeCall request, the method typically returns CIL_OK, which means that the
method call was successful. If the underlying make call request is successful, the CIL receives several follow-on
events, such as eBeginCallEvent and eServiceInitiatedEvent. If the request fails, the CIL receives the
eControlFailureConf message.
A common mistake is that developers who have not previously programmed with asynchronous events mistake
the error code returned from a method call for the actual result of the request. The correct semantics are to
interpret the error code as being indicative of the result of the method call, and to interpret the follow-on
events to determine the actual result of the requested operation.
CIL Error Codes
Whenever a method call is invoked by a custom application using the CIL, an error code is returned. The error
codes returned only indicate success or failure of the method call, as indicated in the previous section.
The possible values of the error code returned from C++ and Java CIL methods are defined in the following
table.
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
3
CIL Coding Conventions
Asynchronous Program Execution
The numeric values listed in the following table are subject to change. Use the error code enumerations
to check a given error code, rather than rely on a specific numeric value.
Note
Table 2: CIL Error Codes
DescriptionNumeric
Value
CIL Error Code
The method succeeded. The request to silent monitor
the call was successfully initiated.
1CIL_OK
The method failed.0CIL_FAIL
There is no implementation available for this method.-99E_CTIOS_METHOD_NO_
IMPLEMENTED
One or more properties are invalid.-100E_CTIOS_INVALID_ PROPERTY
A conflict when setting session mode.-101E_CTIOS_MODE_CONFLICT
The Event ID is not valid.-102E_CTIOS_INVALID_ EVENTID
The Argument is not valid.-103E_CTIOS_INVALID_ ARGUMENT
The Session is not valid.-104E_CTIOS_INVALID_ SESSION
An unexpected error has occurred.-105E_CTIOS_UNEXPECTED
There is not enough memory available and the
creation of CCtiOsObject failed.
-106E_CTIOS_OBJ_ALLOCATION_FAILED
There is not enough memory available and the
creation of an array of references to objects of type
CCtiOsObject failed.
-107E_CTIOS_ARRAYREF_
ALLOCATION_FAILED
There is not enough memory available and the
creation of an object of type Arguments failed.
-108E_CTIOS_ARGUMENT_
ALLOCATION_FAILED
There are no CTI OS Objects capable of processing
an incoming event.
-109E_CTIOS_TARGET_ OBJECT_
NOT_FOUND
An error occurred while accessing a property's
attributes, System may be running out of memory.
-110E_CTIOS_PROP_
ATTRIBUTES_ACCESS_ FAILED
The object type is not one of the following predefined
types CAgent, CCall, CSkillGroups, or CWaitObject.
-111E_CTIOS_INVALID_ OBJECT_TYPE
No valid agent.-112E_CTIOS_INVALID_AGENT
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
4
CIL Coding Conventions
CIL Error Codes
DescriptionNumeric
Value
CIL Error Code
No valid call.-113E_CTIOS_INVALID_CALL
The session is recovering from a connection failure
and started the Fail Over procedure.
-114E_CTIOS_IN_FAILOVER
Indicates that the desktop type specified in the request
for DeskSettings download is neither Agent or
Supervisor.
-115E_CTIOS_INVALID_ DESKTOP_TYPE
Missing a required argument.-116E_CTIOS_MISSING_ ARGUMENT
Call is not on hold.-117E_CTIOS_CALL_NOT_ON_ HOLD
Call is already on hold.-118E_CTIOS_CALL_ALREADY_
ON_HOLD
Call is not in alert state, it can not be answered.-119E_CTIOS_CALL_NOT_ ALERTING
Agent is not logged in.-120E_CTIOS_AGENT_NOT_ LOGIN
The input parameter is invalid.-121E_CTIOS_INVALID_
METHOD_PARAMETER
The cause of this error is unknown.-122E_CTIOS_UNKNOWN
Failed to allocate new memory.-123E_CTIOS_OUT_OF_ MEMORY
The specified port is not available for use.-124E_CTIOS_PORT_ UNAVAILABLE
The Silent Monitor session was terminated
abnormally.
-125E_CTIOS_SM_SESSION_
TERMINATED_ ABNORMALLY
The request was rejected because there is an active
silent monitor session in progress.
-126E_CTIOS_SM_REJECTED_
ALREADY_IN_SESSION
The packet sniffer is not present in the system; verify
installation.
-127E_CTIOS_SM_PACKET_
SNIFFER_NOT_INSTALLED
An error occurred in the packet sniffer.-128E_CTIOS_PACKET_ SNIFFER_FAILED
A CTI OS socket call failed.-129E_CTIOS_SOCKET_CALL_ FAILED
EVVBU Media Termination component in the system,
verify installation.
-130E_CTIOS_MEDIA_
TERMINATION_NOT_ INSTALLED
Specified CODEC is not supported.-131E_CTIOS_MT_UNKNOWN_ CODEC
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
5
CIL Coding Conventions
CIL Error Codes
DescriptionNumeric
Value
CIL Error Code
An error occurred in the Media Termination Packet
Decoder.
-132E_CTIOS_MEDIA_
TERMINATION_FAILED
The Sniffer has not received any IP packets.-133E_CTIOS_SNIFFER_NO_
PACKETS_RECEIVED
The Sniffer failed to open the networking device.-134E_CTIOS_SNIFFER_
FAILED_TO_OPEN_DEVICE
The Sniffer failed when setting the packet filter.-135E_CTIOS_SNIFFER_
FAILED_TO_SET_FILTER
The packet filter expression is incorrect.-136E_CTIOS_ERROR_IN_
PACKET_FILTER
The IP Address specified for the monitored device
(IP Phone) is not valid.
-137E_CTIOS_INVALID_
MONITORED_IP_ADDRESS
Invalid Sniffer object.-138E_CTIOS_INVALID_
SNIFFER_OBJECT
Invalid Decoder object.-139E_CTIOS_INVALID_
DECODER_OBJECT
There are no Silent Monitor Sessions in progress.-140E_CTIOS_NO_SM_
SESSION_IN_PROGRESS
The specified Silent Monitor session does not exist.-141E_CTIOS_INVALID_
SILENT_MONITOR_ SESSION
Silent Monitor Session was not removed from the
collection.
-142E_CTIOS_FAILED_
REMOVING_SILENT_
MONITOR_SESSION
There is no information available about the IP Phone.-143E_CTIOS_IP_PHONE_
INFORMATION_NOT_ AVAILABLE
The peer application is not enabled for Silent Monitor.-144E_CTIOS_PEER_NOT_
ENABLED_FOR_SILENT_ MONITOR
This application is not enabled for Silent Monitor.-145E_CTIOS_NOT_ENABLED_
FOR_SILENT_MONITOR
There are no pending requests to be processed.-146E_CTIOS_NO_PENDING_REQUEST
There is already an established session.-147E_CTIOS_ALREADY_IN_SESSION
The session mode is already set.-148E_CTIOS_MODE_SET_ALREADY
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
6
CIL Coding Conventions
CIL Error Codes
DescriptionNumeric
Value
CIL Error Code
The session mode is not set yet.-149E_CTIOS_MODE_NOT_SET
The object is not in the correct state.-150E_CTIOS_INVALID_OBJECT_STATE
This error occurs when a request to initiate CTI OS
silent monitor is made and CTI OS is configured to
use CCM silent monitor. This error also occurs when
a request to initiate CCM silent monitor is made and
CTI OS is configured to use CTI OS silent monitor.
-151E_CTIOS_INVALID_SILENT_MONITOR_MODE
CoCreateInstance failed to create a COM object
wrapper for a CIL Object (Session, Agent, Call, Skill,
etc.).
-200E_CTIOS_COM_OBJ_
ALLOCATION_FAILED
A COM component failed to access data from the
registry.
-201E_CTIOS_COM_
CORRUPTED_REGISTRY
The Dial Pad common dialog was not created and
CoCreateInstance failed.
-202E_CTIOS_COM_DIALPAD_
FAIL_TO_LOAD
Failed converting COM pointer to C++ pointer.-203E_CTIOS_COM_CONV_
COMPTR_TO_CPPPTR_ FAILED
The MS COM library is not initialized. Invoke
CoInitialize(...).
-204E_CTIOS_COM_NOT_ INITIALIZED
A disconnect is already pending.-300E_CTIOS_SESSION_
DISCONNECT_PENDING
The session is not connected.-301E_CTIOS_SESSION_NOT_
CONNECTED
The call to Connect failed because the session is not
in a disconnected state. The session may be connected
or a previous call to Disconnect may not yet be
complete.
-351E_CTIOS_SESSION_NOT_DISCONNECTED
An object for this agent already exists in the session.-900E_CTIOS_AGENT_
ALREADY_IN_SESSION
Session must be disconnected before operation.-901E_CTIOS_SET_AGENT_
SESSION_DISCONNECT_ REQUIRED
Could not send message. Session may not be
connected.
-902E_CTIOS_SERVICE_SEND_MESSAGE_FAILED
An object for this call is already set as current in the
session.
-903E_CTIOS_CALL_ALREADY_CURRENT_IN_SESSION
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
7
CIL Coding Conventions
CIL Error Codes
DescriptionNumeric
Value
CIL Error Code
The AgentID and/or PeripheralID provided to a Login
call do not match the properties set on the Agent
object when SetAgent() was called.
-904E_CTIOS_LOGIN_ INCONSISTENT_
ARGUMENTS
If a method that is supposed to trigger an event returns an error code, check this return value before
continuing to wait for events. Depending on the error code, the event you were waiting for may not be
triggered.
Note
COM Error Codes
For applications using the CTI OS CIL for COM, the Microsoft COM layer adds a level of error detection
and provides additional error codes, called HRESULTs. For COM method calls in C++, the HRESULT is
returned from the method call, and indicates success or failure of the method call. The CIL error code is also
returned, but as an [out, retval] parameter. For example:
// COM Example in C++
int errorCode = 0;
HRESULT hr = pCall->Answer(&errorCode);
if (errorCode=CIL_FAILED)
printf(“An error has occurred while answering the call.”)
In Visual Basic, HRESULT values are hidden under the covers. When an error occurs, a Visual Basic exception
is thrown, which can be caught using the On Error: construct. The CIL error code is returned as the result of
the method call:
' VB example:
On Error GoTo Error_handler
Dim errorCode as Long
ErrorCode = pCall.Answer
If ErrorCode = CIL_FAILED
Debug.print “An error has occurred.”
The complete set of HRESULT values is defined by Microsoft in the header file winerror.h. The most common
HRESULT values that CTI OS developers see are listed in the following table:
Table 3: COM Error Codes
DescriptionNumeric ValueCOM Error Code
The method succeeded.0x00000000S_OK
The method succeeded, but something unusual
happened.
0x00000001S_FALSE
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
8
CIL Coding Conventions
COM Error Codes
DescriptionNumeric ValueCOM Error Code
The method failed.0x80000008E_FAILED
The class was not found in the registry. You must run
regsvr32.exe on the DLL file to register it.
0x80040143REG_DB_E_
CLASSNOTREG
Generic Interfaces
One of the main design goals of CTI OS was to enable future enhancements to the CTI OS feature set without
breaking existing interfaces. To accomplish this, a parameter for almost every method and event is an Arguments
array containing the actual parameters needed. Therefore, parameters can be added or deleted in future versions
without affecting the signature of the method or event. This provides the benefit to developers that code
developed to work with one version of the CTI OS developer toolkit works with future versions without
requiring any code changes on the client side (except to take advantage of new features). For example, CTI
OS automatically sends a new parameter in the Arguments array for an event, without requiring an interface
or library code change. The dilemma of creating a generic interface is solved by using generic mechanisms
to send parameters with events and request, and to access properties.
Arguments
The CTI OS developer's toolkit makes extensive use of a new data structure (class) called Arguments.
Arguments is a structure of key-value pairs that supports a variable number of parameters and accepts any
user-defined parameter names. For any given event, the Arguments structure allows the CTI OS Server to
send the CIL any new parameters without requiring client side changes. Similarly, for any request, the
programmer can send any new parameters without any changes to the underlying layers.
Example of using Arguments in a Visual Basic MakeCall request:
Dim args As New Arguments
args.AddItem "DialedNumber", dialthis.Text
If Not 0 = Len(callvar1.Text) Then
' set callvar1
args.AddItem "CallVariable1", callvar1.Text
End If
' send makecall request
m_Agent.MakeCall args, errorcode
Java example:
Arguments args = new Arguments();
args.SetValue(CtiOs_IkeywordIDs.CTIOS_DIALEDNUMBER, "12345");
args.SetValue(CtiOs_IkeywordIDs.CTIOS_CALLVARIABLE1, "MyData");
int iRet = m_Agent.MakeCall(args);
The Arguments structure can store and retrieve all native C/C++, Visual Basic, and .NET, and Java types, as
well as nested Arguments structures.
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
9
CIL Coding Conventions
Generic Interfaces
GetValue Method to Access Properties and Parameters
CTI OS makes extensive use of generic data abstraction. The CTI OS CIL objects, as well as the Arguments
structure, store all data by key-value pair. Properties and data values in CTI OS are accessible through a
generic mechanism called GetValue. For a list of the different GetValue methods, see CtiOs Object or Helper
Classes The GetValue mechanism provides for the retrieval of any data element based on its name. This
enables the future enhancement of the data set provided for event parameters and object properties without
requiring any interface changes to support new parameters or properties. GetValue supports use of string
keywords, as shown in the following examples:
// C++string sAgentID;
args.GetValueString("AgentID", &sAgentID);
`Visual Basic
Dim sAgentID As String
sAgentID = args.GetValueString "AgentID"
//Java
String sID = args.GetValueString(CtiOs_IkeywordIDs.CTIOS_AGENTID);
Integer IPeriph =
args.GetValueIntObj(CtiOs_IkeywordIDs.CTIOS_PERIPHERALID);
if (IPeriph == null)
// Error accessing Peripheral ID! Handle Error here
else
iPeriph = IPeriph.intValue();
CTI OS defines a set of well-known keywords for event parameters and properties. The well-known keywords
are of type string and are listed throughout this document with the methods and events for which they are
valid. The complete set of valid keywords are listed in the C++ header file, ctioskeywords.h, and are provided
in the COM (Visual Basic) type library as well. Java CIL keywords are listed in the Javadoc in the description
of the CtiOs_IKeywordIDs interface.
SetValue Method to Set Object Properties and Request Parameters
The CIL also provides an extensible mechanism to set properties on CTI OS Client Interface Objects. The
SetValue mechanism, available on the CIL Interface Objects (as well as the CTI OS Arguments class), enables
setting properties of any known type to the object as a key-value pair.
SetValue, similar to GetValue and AddItem, supports string keywords and enumerated names:
// C++
Agent a;
a.SetValue("AgentID", "22866");
a.SetValue(CTIOS_AGENTID, "22866"); // alternative
a.SetValue(ekwAgentID, "22866"); // alternative
`Visual Basic
Dim a As Agent
a.SetValue "AgentID", "22866"
//Java. Note use of the CTIOS_AGENTID version of keywords.
String sAgentID = "22866";
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
10
CIL Coding Conventions
GetValue Method to Access Properties and Parameters
Args.SetValue("AgentID", sAgentID);
Args.SetValue(CtiOs_IkeywordIDs.CTIOS_AGENTID, sAgentID); // alternative
Args.SetValue(ekwAgentID, sAgentID);
The complete syntax and usage of the GetValue, AddItem, and SetValue methods is detailed in CtiOs Object
The Arguments structure is detailed in Helper Classes
UniqueObjectID Variable-Length String
The CTI OS Server creates and manages the CTI OS objects, representing all interactions for the contact
center. The CTI OS Server and CIL use the UniqueObjectID field to match up a CTI OS object on the CIL
with the corresponding object on the Server.
The UniqueObjectID is a variable-length string that can uniquely identify the object within the current context
of the CTI OS Server and the Unified CCE and CTI Interlink Advanced. The UniqueObjectID comprises an
object type (for example, call, agent, skillgroup, and so on), and two or more additional identifying fields.
The following table explains the composition of the UniqueObjectID.
Table 4: UniqueObjectID Components
ExplanationSample UniqueObjectIDObject Type
The Call object is uniquely identified by its
PeripheralID (5000, generated by Unified ICM),
ConnectionCallID (202, generated by the
PBX/ACD), and its ConnectionDeviceID (23901,
generated by the PBX/ACD).
call.5000.202.23901Call Object
The Agent object is uniquely identified by its
PeripheralID (5000, generated by Unified ICM),
and its agent ID.
agent.5000.22866Agent Object
The device object is uniquely identified by its
PeripheralID (5000, generated by Unified ICM),
and its instrument number (configured by the
PBX/ACD).
device.5000.23901Device Object (for
events only; no CIL
object)
The skill group object is uniquely identified by its
PeripheralID (5000, generated by Unified ICM),
and its SkillGroupNumber (configured by the
PBX/ACD).
skillgroup.5000.77SkillGroup Object
The team object is uniquely identified by its
PeripheralID (5000, generated by Unified ICM),
and its TeamID (5001, also generated by Unified
ICM).
team.5000.5001Team Object (for
events only; no CIL
object)
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
11
CIL Coding Conventions
UniqueObjectID Variable-Length String
The CTI OS UniqueObjectID is not the same as the Unified ICM globally unique 64 bit key used in the
ICM historical databases (called the ICMEnterpriseUniqueID), which exists only for calls. The
ICMEnterpriseUniqueID stays with the call even when the call is transferred between call center sites,
while the UniqueObjectID for a call is specific to its site (by PeripheralID, ConnectionCallID, and
ConnectionDeviceID).
Note
The ICMEnterpriseUniqueID in CTI OS is a variable-length string with the form
“icm.routercallkeyday.routercallkeycallid”
where routercallkeyday is the field Day in the Unified ICM Route_Call_Detail and Termination_Call_Detail
tables, and routercallkeycallid is the field RouterCallKey in the Unified ICM Route_Call_Detail and
Termination_Call_Detail tables.
The CTI OS server enables certain types of monitor mode applications that track the pre-call notification event
(eTranslationRouteEvent or eAgentPrecallEvent) and seeks to match the call data with the arrival of an
eCallBeginEvent.
To do so, the application receives the pre-call notification for calls routed by Unified ICM, (either pre-route,
post-route, or translation route), and creates a record (object) using the ICMEnterpriseUniqueID field as the
unique key. Later, when the call arrives at the ACD, and is queued or targeted (by the ACD) for a specific
agent, the application can match the saved record (object) with the incoming call by the ICMEnterpriseUniqueID
field. The following events contain the ICMEnterpriseUniqueID that can associate a call with the saved call
information:
•
eCallBeginEvent
•
eCallDataUpdateEvent
•
eSnapshotCallConf
•
eCallEndEvent
UniqueObjectID to Obtain Pointer or Reference
Client applications written to take advantage of the CIL can use the UniqueObjectID to obtain a pointer (in
C++ or COM for C++) or a reference (in other languages) to the underlying object.
The CIL Session object provides easy access to the object collections via several methods, including
GetObjectFromObjectID. GetObjectFromObjectID takes as a parameter the string UniqueObjectID of the
desired object, and returns a pointer to the object. Because this mechanism is generic and does not contain
specific information about the object type retrieved, the pointer (or reference) returned is a pointer or reference
to the base class: a CCtiosObject* in C++, an Object in Visual Basic, an IDispatch* in COM for C++, or
CtiOsObject in .NET and Java.
The GetObjectFromObjectID method performs an AddRef() on the pointer before it is returned to the
programmer.
Note
C++ example:
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
12
CIL Coding Conventions
UniqueObjectID to Obtain Pointer or Reference
string sUniqueObjectID = "call.5000.101.23901";
Ccall * pCall = NULL;
m_pSession->GetObjectFromObjectID(sUniqueObjectID,
(CCtiOsObject**)&pCall);
pCall->Clear();
pCall->Release(); // release our reference to this object
pCall = NULL;
Java example:
String sUID = "call.5000.101.23901";
Call rCall = (Call) m_Session.GetObjectFromObjectID(sUID);
Button Enablement Masks
The CTI OS Server provides a rich object-level interface to the CTI interactions of the contact center. One of
the features the CTI OS Server provides is to evaluate all of the telephony events, and map them to the features
permitted by the Cisco CallManager implementation. The CTI OS Server provides a peripheral-independent
mechanism for clients to determine which requests are valid at any given time by using a bitmask to indicate
which requests are permitted.
For example, the only valid time to answer a call is when the ENABLE_ANSWER bit in the enablement mask
is set to the on position. The following C++ example depicts this case:
void EventSink::OnCallDeliveredEvent(Arguments& args)
{
unsigned int unBitMask = 0;
if (args.IsValid(“EnablementMask”))
{
args.GetValueInt(“EnablementMask”, & unBitMask)
//do bitwise comparison
If(unBitMask & ENABLE_ANSWER)
m_AnswerButton.Enable();
}
}
Visual Basic.NET Example
Private Sub m_session_OnAgentStateChange(ByVal pIArguments As
Cisco.CTIOSCLIENTLib.Arguments) Handles m_session.OnAgentStateChange
Dim bitmask As Integer
'Determine the agent's button enablement and update the buttons
on the form
bitmask = m_Agent.GetValueInt("EnablementMask")
btnReady.Enabled = False
btnNotReady.Enabled = False
btnLogout.Enabled = False
btnStartMonitoring.Enabled = False
If bitmask And
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
13
CIL Coding Conventions
Button Enablement Masks
Cisco.CTIOSCLIENTLib.enumCTIOS_EnablementMasks.ENABLE_READY Then
btnReady.Enabled = True
End If
If bitmask And
Cisco.CTIOSCLIENTLib.enumCTIOS_EnablementMasks.ENABLE_NOTREADY Then
btnNotReady.Enabled = True
End If
If bitmask And
Cisco.CTIOSCLIENTLib.enumCTIOS_EnablementMasks.ENABLE_NOTREADY_WITH_REASON
Then
btnNotReady.Enabled = True
End If
If bitmask And
Cisco.CTIOSCLIENTLib.enumCTIOS_EnablementMasks.ENABLE_LOGOUT Then
btnLogout.Enabled = True
End If
If bitmask And
Cisco.CTIOSCLIENTLib.enumCTIOS_EnablementMasks.ENABLE_LOGOUT_WITH_REASON
Then
btnLogout.Enabled = True
End If
End Sub
The advantage of using this approach is that all of the peripheral-specific details of enabling and disabling
buttons is determined in a central location—at the CTI OS Server. This allows future new features to be
enabled, and software bugs to be corrected in a central location, which is a great benefit for deploying future
releases.
Note
•
You must use the button enablement mask generated by CTI OS Server in all cases where Cisco
provides button enablement masks. This prevents application impact if changes are made to the event
flow.
•
Cisco makes no guarantees that the event flow will remain consistent across versions of software.
The button enablement feature is intended for use in agent mode applications and not for monitor
mode applications.
Warning
For any given event, the CTI OS Server calculates the appropriate button enablement bitmask and sends it to
the CIL with the event parameters. The button enablement bit masks are discussed in detail in Event Interfaces
and Events You can use these masks to write a custom softphone-type application without writing custom
code to enable and disable buttons. This approach is also used internally for the CTI OS ActiveX softphone
controls.
CTI OS Developer Guide for Cisco Unified ICM/Unified Contact Center Enterprise, Release 11.6(1)
14
CIL Coding Conventions
Visual Basic.NET Example
