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.

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.

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.

Note	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	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.

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:

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.

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.

Note

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).

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

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.

Note	The GetObjectFromObjectID method performs an AddRef() on the pointer before it is returned to the programmer.

C++ example:

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);

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();
           }
}