10Developing a Communications Driver
Developing a Communications Driver
This chapter provides developer guidelines for writing communications drivers using the Siebel Adaptive Communications application programming interface. It includes the following topics:
Required Skills for Adaptive Communications Developer
To develop an interface to Adaptive Communications, take the time to learn about the following:
Siebel Business Applications, from an end-user and development standpoint
Communications concepts and event-handling model
Technologies and development tools for the languages C++ or C
Custom Driver Upgrade Issues
This topic describes issues that might apply if you are supporting or updating custom communications drivers originally written for a Siebel CRM release 7.x that is earlier than version 7.7; that is, for drivers written for Siebel CRM version 7.0.x or version 7.5.x.
Communications drivers for prior Siebel CRM 7.x releases do not work as is with Siebel CRM version 7.7.x or later, unless you follow the guidelines in this topic. Siebel CRM version 7.7.x or later requires version 2 of the Siebel Adaptive Communications API (as did Siebel CRM version 7.5.x). For more information about custom drivers, see Communications Drivers and Third-Party Systems.
Requirements that might apply to your custom communications driver are as follows:
On all supported operating systems, for any communications driver written for Siebel CRM version 7.0.x, you must compile the driver using the current version of the API. A Siebel CRM version 7.0.x communications driver cannot work with Siebel CRM version 7.7.x or later, due to version checking. For drivers from Siebel CRM version 7.5.x, this requirement is already met.
For drivers on all supported operating systems, the driver handle method FreeSCStrParamList must be implemented. For any driver for Siebel CRM version 7.0.x or 7.5.x, if you previously did not implement this method to function as described, then you must implement it and recompile your driver. If you previously implemented this method, then this requirement might not apply. For more information about this method, see Methods of ISC_DRIVER_HANDLE.
For Oracle Solaris, you must use UTF16, in order to support Unicode, rather than UCS4 (as was used in Siebel CRM version 7.0.x). For any driver on this platform for Siebel CRM version 7.0.x, you must modify your driver code and recompile your driver. For drivers from Siebel CRM version 7.5.x, this requirement is already met.
Adaptive Communications Design
Siebel Adaptive Communications is a programmable software layer between Siebel applications and the external communications system that a communications driver is written to support, such as a CTI middleware package or email server.
The Adaptive Communications layer has two main parts:
The client handle, which is how the communications driver can access functionality in the Siebel application
The communications driver (encompassing the driver handle and the service handle), through which communications pass between the Siebel application and the external communications system
This topic contains the following information:
Communications Drivers
A variety of communications drivers are available:
Oracle provides communications drivers for use with standard email servers that support SMTP, IMAP, and POP3; and provides drivers for use with other communications systems. For more information about configuring communications drivers, see Configuring Communications Drivers and Profiles.
For driver parameter, command, and event details for each driver provided with Siebel Business Applications, see the applicable content on each supported driver. For applicable drivers, see also Siebel Email Administration Guide. For information about third-party product support, see the Certifications tab on My Oracle Support.
Siebel CRM customers and vendors of CTI middleware, email servers, and so on, can use Adaptive Communications to write custom drivers to support other communications systems. To find out about communications drivers created by other vendors, refer to the Partners page on the Oracle Web site, http://www.oracle.com.
Drivers can be created that run on Microsoft Windows or on UNIX. For example, drivers on Microsoft Windows might be Dynamic Link Libraries (DLL files), or drivers on UNIX operating systems might be shared object (.so) files. Alternatively, drivers can be created as other types of files than these, such as executable files.
Adaptive Communications Architecture
The communications flow among the elements of Adaptive Communications is shown in the following figure. As shown, the implementations of the driver handle and the service handle together make up the communications driver, along with any other program data and logic built into the driver.
The channel manager initializes the implementation object for the driver handle, which in turn initializes the implementation object for the service handle.
Multiple instances of the client handle and service handle implementation objects might be initialized, such as for each interactive agent session, depending on the driver implementation and on the client deployment. For an overview of the entire communications system, see About Siebel Communications Server Architecture.
Adaptive Communications Event and Command Model
Siebel Adaptive Communications, when it is used to write interactive drivers, such as those used with CTI middleware, uses the concept of events and commands:
A command is a feature of the communications driver that can execute a particular function, such as on an external system like a telephone switch.
Usually, the command, such as a request from the Siebel client to make a call or send a message, is executed with parameters whose values contain associated data, such as the number to call. The communications driver passes the command and associated data to the communications system for execution.
An event is a notification of a communications occurrence that the Siebel client receives from the communications driver along with some data fields, such as notification of an incoming work item, with associated data such as a caller’s telephone number (ANI).
For more information about interactive drivers, see Interactive Drivers.
Once you have written a communications driver, you configure Siebel Communications Server, as described in Configuring Siebel CTI and .
Events and commands that you define in the views in the Administration - Communications screen must be based on what the interactive communications driver supports. Commands, command parameters, events, and event data fields vary among communications drivers, just as they vary among vendors of communications systems, such as CTI middleware vendors.
You can retrieve driver parameter values from the Siebel database. Storing the parameters that you need in the Siebel database allows the administrator to set parameter values appropriately for your communications driver.
You can write a communications driver to support the driver parameters that you require. If you have created a custom driver to function in place of a driver provided with Siebel Business Applications, then you must then create all the driver parameters in the views in the Administration - Communications screen and assign values to them. If you have created a custom driver as an aggregate driver, to extend a Siebel driver, then you can use parameters from the Siebel driver.
The communications driver and the Siebel CRM software, such as Siebel business services and server components, work together to implement the communications behavior for the Siebel application.
Initialization of Communications Drivers
Driver initialization might involve initializing two handles for each communications driver implementation: ISC_DRIVER_HANDLE (the driver handle) and ISC_SERVICE_HANDLE (the service handle).
For drivers loaded on a Siebel Server computer, the driver handle is typically initialized only once, rather than once for each agent session. This depends on your driver implementation.
The driver handle and service handle can be implemented in any appropriate language, but must be implemented together using the same language.
Loading Communications Drivers
The process of loading a communications driver is as follows:
The channel manager invokes the driver handle method APIVersion, to check the driver’s API version. The API version defined in the driver’s header file must match the API version for Communications Server. For more information, see APIVersion.
The channel manager invokes the driver handle method CreateISCDriverInstance, to create the driver instance. The channel string passed to this method is collected from the driver record that is created in the Communications Drivers and Profiles view, in the Administration - Communications screen. For more information, see CreateISCDriverInstance.
The channel manager invokes the driver handle method RequestCommandEventList, to retrieve the list of events and commands this driver supports. For more information, see RequestCommandEventList.
The channel manager invokes the driver handle method RequestService, to create a service object. For more information, see RequestService.
If any listed step fails, then the driver loading fails. If multiple driver profiles must be loaded, then the process is repeated for each profile.
ISC_DRIVER_HANDLE
During initialization of an interactive communications driver, the CreateISCDriverInstance method is called to create the driver handle.
This method uses driver and profile parameter data (parameters prefaced with Driver: or parameters without a prefacing keyword) from the communications configuration, specified in the Communications Drivers and Profiles view.
For more information about the CreateISCDriverInstance method, see CreateISCDriverInstance.
ISC_SERVICE_HANDLE
After the driver handle has been created, the driver handle method RequestService is invoked, to request the driver handle to provide a service. Driver parameters (parameters prefaced with Service: or parameters without a prefacing keyword) are passed, which were specified in the Communications Drivers and Profiles view.
In response to this request, the driver handle returns the service handle (ISC_SERVICE_HANDLE), one instance for each agent. Calling methods of the service handle makes the feature set of the communications system available.
The driver handle and service handle together make up the implementation of the communications driver, along with other program data and logic.
Your implementation of the service handle invokes methods of the client handle, ISC_CLIENT_HANDLE. The client handle is implemented by Oracle.
For more information about the RequestService method, see RequestService.
Driver Parameters and Initialization
For the drivers provided with Siebel Business Applications, each driver parameter might be prefaced with a keyword indicating how it is used. Driver parameters defined for custom Adaptive Communications drivers can also follow this scheme for controlling how parameters are used:
Parameters prefixed with Driver: are sent (with the prefix Driver: removed) to the driver handle when the driver is being initialized. These parameters are sent to the CreateISCDriverInstance method.
Parameters prefaced with Service: are sent (with the prefix Service: removed) to the driver handle when it requests a service (creates the service handle). These parameters are sent to the RequestService method.
Parameters that are not prefixed with either Driver: or Service: (as is the case for most of the drivers provided with Siebel Business Applications) are sent to the driver handle when the driver is being initialized (CreateISCDriverInstance method) and also when the driver handle requests a service (RequestService method).
Driver Event Attributes
The following table lists event attributes that are included by the channel manager for all events processed by the client handle method HandleEvent. These attributes apply to any communications driver that invokes the client handle method HandleEvent, whether for drivers provided with Siebel Business Applications or custom drivers developed by customers or by other vendors.
You can use these attributes with event handler definitions in communications configurations. For more information, see Event Handlers and Work Item Attributes.
The event attributes described in the following table are also available for workflows used in processing inbound communications.
For more information about the HandleEvent client handle method, see HandleEvent.
Table Driver Event Attributes
| Attribute Name | Description |
|---|---|
SiebelChannelProfile |
The name of the applicable profile for the driver. |
SiebelChannelType |
The language-independent value of the channel type. |
SiebelChannelTypeString |
The channel string defined for the driver. |
SiebelDriverEventName |
The device event name as known by the driver. |
SiebelDriverNotifyWhenDone |
The setting of whether the driver requests notification from the client when event-handling is done. The client handle method HandleEvent includes the parameter notifyWhenDone, which is used to request the client to notify the driver when the client has finished handling the event. The client notifies the driver that event handling is done by using the service handle method NotifyEventHandlingFinished. |
SiebelWorkItemID |
The unique work item ID, a value in the form profile_ID##driver_tracking_ID, where profile_ID is the ID of the driver profile and driver_tracking_ID is the work item’s tracking ID, as known by the driver. For example, if the ID of the driver profile is 12-01234, and the driver uses the tracking ID abcdefg for this work item, then 12-01234##abcdefg is the value of SiebelWorkItemID for this work item. |
For events received for each interactive driver, additional data is received as event data fields. #1
Siebel Adaptive Communications API Reference
This topic provides a reference for the methods supported by the Adaptive Communications application programming interface. Siebel Adaptive Communications is a programmable software layer between Siebel applications and the communications system.
For more information for developing a communications driver using Siebel Adaptive Communications, see Adaptive Communications Design.
This topic describes the client, driver, and service handles and the constants used by Adaptive Communications; and describes the methods for these handles.
This topic contains the following information:
Handles for Adaptive Communications
The Adaptive Communications layer includes a set of constants and the three handles described in the following paragraphs. The syntax with which each Adaptive Communications method is expressed is that of a C header file. In the following handle names, ISC stands for Interface for Siebel Communications:
ISC_CLIENT_HANDLE. The client handle, which provides methods called by the communications driver. Oracle has implemented ISC_CLIENT_HANDLE and its methods.
For descriptions of the client handle methods, see Methods of ISC_CLIENT_HANDLE.
ISC_DRIVER_HANDLE. The driver handle, which is created when communications are initialized (for example, when the first user logs in). ISC_DRIVER_HANDLE then creates ISC_SERVICE_HANDLE, from which services are requested. Customers writing communications drivers must implement methods of the driver handle.
For descriptions of the driver handle methods, see Methods of ISC_DRIVER_HANDLE.
ISC_SERVICE_HANDLE. The service handle, which is created by ISC_DRIVER_HANDLE when communications are initialized (for example, when a user logs in). The Siebel client calls ISC_SERVICE_HANDLE methods in order to perform actual communications functions. Customers writing communications drivers must implement methods of the service handle.
For more information about these handles, see Adaptive Communications Design.
For descriptions of the service handle methods, see Methods of ISC_SERVICE_HANDLE.
Constants for Communications Drivers
Each of the following elements enumerates one or more constants. Values for all fields are stored when information about objects is passed back and forth between the Siebel application and the communications driver.
For example, object information is passed in this manner when the client handle method UpdateObjectInformation is invoked. For more information, see UpdateObjectInformation.
SCCommandFlag
Communications commands have dynamic or run-time status, consisting of the bit-flags enumerated by SCCommandFlag. Zero or more bit-flags can apply to a given command at any given time.
enum SCCommandFlag
{
SC_CF_NOTSUPPORTED = 1,
SC_CF_DISABLED = 2,
SC_CF_CHECKED = 4,
SC_CF_BLINKING = 8,
SC_CF_NOPARAMSOK = 16,
SC_CF_STRPARAMSOK = 32
};
Each bit-flag that can be associated with a command is described as follows:
SC_CF_NOTSUPPORTED. The command is not supported.
SC_CF_DISABLED. The command is supported, but is disabled at this time.
SC_CF_CHECKED. The command is in a checked state; for example, when an agent is in Not Ready mode, the command to set the Not Ready state is checked. This flag can be used to specify a toggle state for commands in the communications toolbar or in the Communications submenu of the Tools application-level menu.
SC_CF_BLINKING. Blinking is enabled for communications toolbar buttons, such as those for the Accept Work Item and Resume Work Item commands.
SC_CF_NOPARAMSOK. The command does not require any parameters to execute. For example, the commands for releasing a call and for toggling the Not Ready state do not require parameters.
SC_CF_STRPARAMSOK. The command can be executed by providing a single unnamed string parameter (no named parameter is provided). The command for placing a call, for example, requires only a single parameter. Such commands are invoked when the user types something in the input field in the communications toolbar, such as an extension number, and clicks the command’s button.
SCCommandTypeEx
Communications commands can be specified using either the InvokeCommand or InvokeCommandEx methods of the service handle. The values enumerated by SCCommandTypeEx specify the command type for an invocation of the InvokeCommandEx method. For more information, see InvokeCommandEx.
enum SCCommandTypeEx
{
SC_CT_MAKECALL = 1,
SC_CT_SENDMESSAGE = 2
};
Each command type is described as follows:
SC_CT_MAKECALL. The command to be invoked is a command for placing a phone call. The InvokeCommandEx command includes predefined parameters concerning the phone call to be made.
SC_CT_SENDMESSAGE. The command to be invoked is a command to send an email message. The InvokeCommandEx command includes predefined parameters concerning the email message to be sent.
SCErrorCode
The values enumerated by SCErrorCode specify predefined error codes. The error codes from 0 to 1000 are reserved.
enum SCErrorCode
{
SC_EC_OK = 0,
SC_EC_ERROR = 1,
SC_EC_CMD_NOT_SUPPORTED = 2,
SC_EC_MEDIA_TYPE_NOT_SUPPORTED = 3,
SC_EC_INVALID_HANDLE = 4,
SC_EC_OUT_OF_MEMORY = 5,
SC_EC_NETWORK_ERROR = 6,
SC_EC_LIB_LOAD_ERR = 7,
SC_EC_FUNC_NOT_RESOLVED = 8,
SC_EC_DRIVER_CREATION_ERR = 9,
SC_EC_DRIVER_RELEASE_ERR = 10,
SC_EC_SERVICE_CREATION_ERR = 11,
SC_EC_SERVICE_RELEASE_ERR = 12,
SC_EC_INVALID_ITEM_TRACKING_ID = 13,
SC_EC_CLIENT_INTERFACE_ERR = 14,
SC_EC_SENDMSG_FAILED_RETRY = 15,
SC_EC_IMPOBJ_CREATE_ERR = 16,
SC_EC_INVALID_LICENSE = 17,
SC_EC_WORK_ITEM_WRONG_STATE = 18,
SC_EC_DRIVER_SPECIFIC = 1000
};
Each error code is described as follows:
SC_EC_OK. The operation is successful.
SC_EC_ERROR. The operation failed.
SC_EC_CMD_NOT_SUPPORTED. The command is not supported.
SC_EC_MEDIA_TYPE_NOT_SUPPORTED. The channel type string is not recognized.
SC_EC_INVALID_HANDLE. Invalid handle.
SC_EC_OUT_OF_MEMORY. Out of memory.
SC_EC_NETWORK_ERROR. Networking error.
SC_EC_LIB_LOAD_ERR. Failure on loading the driver file.
SC_EC_FUNC_NOT_RESOLVED. Failure on resolving function address while invoking the command.
SC_EC_DRIVER_CREATION_ERR. Failure on creating the driver handle.
SC_EC_DRIVER_RELEASE_ERR. Failure on releasing the driver handle.
SC_EC_SERVICE_CREATION_ERR. Failure on creating the service handle.
SC_EC_SERVICE_RELEASE_ERR. Failure on releasing the service handle.
SC_EC_INVALID_ITEM_TRACKING_ID. Invalid tracking ID.
SC_EC_CLIENT_INTERFACE_ERR. Failure on invoking the ISC_CLIENT interface.
SC_EC_SENDMSG_FAILED_RETRY. SC_CT_SENDMESSAGE failed, resend later.
SC_EC_IMPOBJ_CREATE_ERR. Unable to create the underlying implementation object.
SC_EC_INVALID_LICENSE. License error, used by the driver to report its license checking.
SC_EC_WORK_ITEM_WRONG_STATE. The work item is in the wrong state for the operation.
SC_EC_DRIVER_SPECIFIC. Specify for driver.
SCObjectProperty
Properties of monitored communications objects.
enum SCObjectProperty
{
SC_OP_ONOFF = 1,
SC_OP_AGENTID = 2,
SC_OP_ISNOTREADY = 4,
SC_OP_ISBUSY = 5,
SC_OP_DESCRIPTION = 7,
SC_OP_TIMEINQUEUE = 9,
SC_OP_QUEUEID = 12,
SC_OP_ISLOGON = 13
};
Each object property is described as follows:
SC_OP_ONOFF. A Boolean value indicating whether teleset control is on or off.
SC_OP_AGENTID. The ID number of an agent, for an agent or DN that is being monitored.
SC_OP_ISNOTREADY. A Boolean value indicating whether an agent has set the Not Ready state, for an agent or DN that is being monitored.
SC_OP_ISBUSY. A Boolean value indicating whether an agent has set the Busy state, for an agent or DN that is being monitored.
SC_OP_DESCRIPTION. A string describing the object that is being monitored.
SC_OP_TIMEINQUEUE. The number of seconds during which the call stayed in the ACD queue before it was answered.
SC_OP_QUEUEID. A string specifying the name of a queue. This is used together with SC_OP_ISLOGON to update the agent’s login status for an ACD queue in the Communications options of the User Preferences screen.
SC_OP_ISLOGON. A value indicating that the agent logged on or logged off.
SCWorkItemMode
Identifies work item modes, for inbound or outbound work items.
enum SCWorkItemMode
{
SC_WM_INBOUND = 1,
SC_WM_OUTBOUND = 2
};
Each work item type is described as follows:
SC_WM_INBOUND. The work item is an inbound item.
SC_WM_OUTBOUND. The work item is an outbound item, initiated by a user.
Data Types for Communications Drivers
The following are data types referenced in this appendix:
struct ISC_KeyValue /* Key-Value element */
{
ISC_STRING paramName;
ISC_STRING paramValue;
};
struct ISC_KVParamList /* List of Key-Value parameter */
{
struct ISC_KeyValue* dataItems;
long len;
};
struct ISC_StrParamList /* List of String */
{
ISC_STRING* dataItems;
long len;
};
struct ISC_LongParamList /* List of "long" */
{
long* dataItems;
long len;
};
Methods of ISC_CLIENT_HANDLE
The client handle, ISC_CLIENT_HANDLE, is implemented by Oracle. The communications driver calls client handle methods in order to communicate with the Siebel application, such as to send communications events and associated data.
When a call to a client handle method is successful, it returns 0 (zero). ISC_RESULT represents the API result type defined for the Siebel Adaptive Communications API.
BeginBatch
Begins a set of client methods to be invoked in a batch when the corresponding EndBatch method is invoked. Using these methods can reduce network overhead. Developers can use these methods at their discretion, subject to the driver implementation design. For more information, see EndBatch.
ISC_RESULT (*BeginBatch) /* in */(ISC_CLIENT_HANDLE handle);
CacheCommandInformation
Notifies the Siebel client about command-status caching.
For the ith command in commandNames, the command description is at the ith position in commandDescriptions, and the command status is at the ith position in commandStatuses. The SCCommandFlags bit flags are used by commandStatuses.
ISC_RESULT (*CacheCommandInformation) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const struct ISC_StrParamList* commandNames, /* in */ const struct ISC_StrParamList* commandDescriptions, /* in */ const struct ISC_LongParamList* commandStatuses);
CleanAllWorkItem
Notifies the Siebel client that all work items for this service session have been removed.
ISC_RESULT (*CleanAllWorkItem) /* in */(ISC_CLIENT_HANDLE handle);
EndBatch
Ends a set of client methods to be invoked in a batch when this method is invoked, given the use of the corresponding BeginBatch method to begin the batch. For more information, see BeginBatch.
ISC_RESULT (*BeginBatch) /* in */(ISC_CLIENT_HANDLE handle);
HandleError
Handles asynchronous errors:
If clntCmdTrackID is not 0 (zero), then it contains the same value that was passed to the service handle method InvokeCommand that caused the error.
If clntCmdTrackID is set to 0 (zero), then the error occurred out of context or the error was associated with a failed call attempt with which no call ID data is associated.
ISC_RESULT (*HandleError) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING clntCmdTrackID, /* in */ const ISC_STRING error);
HandleEvent
Handles the named event received from the communications driver, using the given fields. By calling this method, the communications driver notifies the Siebel client of a communications event, such as a call coming in on the monitored teleset.
If notifyWhenDone is set to True, then the communications driver is notified when event handling is finished. The event’s ID is passed (using the trackingID parameter) in a call to the service handle method NotifyEventHandlingFinished. For more information, see NotifyEventHandlingFinished.
ISC_RESULT (*HandleEvent) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING name, /* in */ const struct ISC_KVParamList* fields, /* in */ ISC_BOOLEAN notifyWhenDone, /* in */ const ISC_STRING trackingID);
IndicateNewWorkItem
Indicates a new incoming call by bringing the Siebel application to the front. If the end user has set the Enable Sound option in the User Preferences screen (Communications options), then the ringin.au file or another user-specified sound file plays.
ISC_RESULT (*IndicateNewWorkItem) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID, /* in */ const ISC_STRING oldTrackingID, /* in */ const ISC_STRING description, /* in */ enum SCWorkItemMode workItemMode);
ShowStatusText
Displays textual status information in the status line of the Siebel client.
ISC_RESULT (*ShowStatusText) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING text);
UpdateObjectInformation
Notifies the Siebel application about status changes of communications objects, for example, that an agent has become busy. Notifications about DN status are used to keep track of when calls end and new calls start. For the object properties that can be provided using datasetInfo, see SCObjectProperty.
ISC_RESULT (*UpdateObjectInformation) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID, /* in */ const ISC_STRING mediaTargetAddr, /* in */ const struct ISC_KVParamList* datasetInfo);
WorkItemReleased
After a work item has been released, such as a phone call disconnected, the driver calls this function.
ISC_RESULT (*WorkItemReleased) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID, /* in */ time_t stopTime);
WorkItemResumed
After a work item has been resumed, such as a phone call resumed from hold at the switch, the driver calls this function.
ISC_RESULT (*WorkItemResumed) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID);
WorkItemStarted
After a work item has been started, such as a phone call connected, the driver calls this function.
ISC_RESULT (*WorkItemStarted) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID, /* in */ const ISC_STRING oldTrackingID, /* in */ const ISC_STRING description, /* in */ const ISC_STRING mediaTargetAddr, /* in */ time_t startTime);
WorkItemSuspended
After a work item has been suspended, such as a phone call put on hold at the switch, the driver calls this function.
ISC_RESULT (*WorkItemSuspended) /* in */(ISC_CLIENT_HANDLE handle, /* in */ const ISC_STRING trackingID);
Methods of ISC_DRIVER_HANDLE
The driver handle, ISC_DRIVER_HANDLE, is implemented in the communications driver. Driver handle methods are invoked to request the driver to create a service handle, among other things. The service handle represents the functionality of the communications system with which you are integrating.
When a call to a driver handle method is successful, it returns 0 (zero). ISC_RESULT represents the API result type defined for the Siebel Adaptive Communications API.
APIVersion
Requests the driver to return the API version (Siebel Communications API, or SCAPI) for which the driver is implemented. The driver must return the SCAPI_VERSION defined in the header file.
ISCAPI long APIVersion();
CreateISCDriverInstance
Requests the driver to create the driver handle ISC_DRIVER_HANDLE and to perform other initialization tasks, such as to connect to the CTI middleware.
ISCAPI ISC_RESULT CreateISCDriverInstance /* in */(const ISC_STRING mediaTypeStr, /* in */ const ISC_STRING languageCode, /* in */ const ISC_STRING connectString, /* in */ const struct ISC_KVParamList* datasetParams, /* out */ ISC_DRIVER_HANDLE* handle);
FreeSCStrParamList
Releases memory that was initially allocated for the driver.
ISCAPI void FreeSCStrParamList /* in */(struct ISC_StrParamList strList);
GetImplementationObject
Returns a data structure for an implementation object, such as might be part of a communications driver implementation. This function might be useful for extending the functionality of an existing driver.
If your communications driver implementation aggregates another communications driver, such that you have an additional object that mediates communication with the driver handle and service handle, then this method can return implementation objects such as the driver handle, service handle, or some other structure.
An aggregate communications driver implementation typically includes a Siebel driver and a separate driver called the aggregate communications driver that extends the main driver’s functionality or replaces part of its functionality.
If you write an aggregate communications driver, then it might be useful to invoke the aggregate driver for certain functions. The aggregate communications driver intercepts certain commands for its special operation and passes other commands on to the existing communications driver.
The aggregate driver must be added to the Communications Drivers and Profiles view, so that the driver can be properly initialized and used.
Writing an aggregate communications driver to work with an existing communications driver can save much time compared with writing a driver from scratch.
ISCAPI ISC_RESULT GetImplementationObject /* in */(ISC_HANDLE key, /* out */ ISC_HANDLE* impObj);
ReleaseISCDriverInstance
Releases the driver handle that was created using CreateISCDriverInstance, release a CTI middleware connection, and so on.
ISCAPI ISC_RESULT ReleaseISCDriverInstance /* in */(ISC_DRIVER_HANDLE handle);
RequestCommandEventList
Returns the list of supported commands or events.
ISCAPI ISC_RESULT RequestCommandEventList /* in */(const ISC_STRING mediaTypeStr, /* out */ struct ISC_StrParamList* commandList, /* out */ struct ISC_StrParamList* eventList);
Request MediaTypeList
Returns the supported channel type.
ISCAPI ISC_RESULT RequestMediaTypeList /* out */(struct ISC_StrParamList* mediaTypeList);
RequestService
Requests the driver to create the service handle ISC_SERVICE_HANDLE and to pass the service type (such as teleset monitoring), user-defined parameters, and the pointer to the Siebel client handle. The driver handle creates the service handle, which in turn communicates with the Siebel application for each agent:
For communications drivers provided with Siebel Business Applications, all parameter data is passed to the communications driver in the datasetParams parameter.
For a customer-implemented communications driver, additional data can be passed to the service handle using the paramString variable.
ISCAPI ISC_RESULT RequestService /* in */(ISC_DRIVER_HANDLE handle, /* in */ const struct ISC_CLIENT_INTERFACE clntInterface, /* in */ const ISC_STRING connectString, /* in */ const struct ISC_KVParamList* datasetParams, /* out */ ISC_SERVICE_HANDLE* serviceHandle);
Methods of ISC_SERVICE_HANDLE
The service handle, ISC_SERVICE_HANDLE, is implemented in the communications driver. Services are returned to the Siebel client in response to a call for the driver handle method RequestService. The service handle methods are called in order to communicate with the communications system, for example, to send commands and associated data. For more information, see RequestService.
When a call to a service handle method is successful, it returns 0 (zero). ISC_RESULT represents the API result type defined for the Siebel Adaptive Communications API.
When a call to a service method fails, the communications driver can call the client handle method HandleError to pass error data. For more information, see HandleError.
AcceptWorkItem
Accepts a work item.
ISCAPI ISC_RESULT AcceptWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID);
HandleQueuedWorkItem
Handles a queued work item.
ISCAPI ISC_RESULT HandleQueuedWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING name, /* in */ const struct ISC_KVParamList* fields, /* in */ const ISC_STRING trackingID);
InvokeCommand
Invokes a command by name, using parameters. A basic ISC_SERVICE_HANDLE implementation must include at least the InvokeCommand method, in order to invoke named commands.
When this method is called, a command is invoked that is to be executed, for example, placing a call, transferring a call, or setting the Not Ready state. Most commands, but not all, are passed from the communications driver to the communications system.
ISCAPI ISC_RESULT InvokeCommand /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING clntCmdTrackID, /* in */ const ISC_STRING name, /* in */ const ISC_STRING stringParam, /* in */ const struct ISC_KVParamList* datasetParam);
InvokeCommandEx
Invokes a command by type, using parameters. The command type is represented by the value of the SCCommandTypeEx constant. You can use this method to invoke commands on an email server or CTI middleware server. The data structure ISC_KVParamList specifies the appropriate predefined parameters, according to the command type. For more information, see SCCommandTypeEx and the description for InvokeCommand.
ISCAPI ISC_RESULT InvokeCommandEx /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING clntCmdTrackID, /* in */ enum SCCommandTypeEx commandType, /* in */ const struct ISC_KVParamList* datasetParam);
NotifyEventHandlingFinished
Notifies the communications driver that the Siebel client has finished handling the event that was sent by the communications driver to the Siebel client using a call for the client handle method HandleEvent. For more information, see HandleEvent.
ISCAPI ISC_RESULT NotifyEventHandlingFinished /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID, /* in */ ISC_BOOLEAN result);
ReleaseISCServiceInstance
Releases the service handle that was created using RequestService, and free resources. No subsequent calls to the driver handle are made. The driver must in turn make no further calls to the client handle.
ISCAPI ISC_RESULT ReleaseISCServiceInstance /* in */(ISC_SERVICE_HANDLE handle);
ReleaseWorkItem
Releases a work item.
ISCAPI ISC_RESULT ReleaseWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID);
ResumeWorkItem
Resumes a work item.
ISCAPI ISC_RESULT ResumeWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID);
RevokeQueuedWorkItem
Revokes a queued work item.
ISCAPI ISC_RESULT RevokeQueuedWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID);
SuspendWorkItem
Suspends a work item.
ISCAPI ISC_RESULT SuspendWorkItem /* in */(ISC_SERVICE_HANDLE handle, /* in */ const ISC_STRING trackingID);
Testing Communications Drivers
The Communications Driver Test Engine (Test Engine) is a standalone tool that simulates parts of a Siebel environment for you to test the reliability and capacity of the communications driver that you develop.
The Test Engine does not test the Communications Server or your communications configuration elements. You can use the Test Engine to test your communications driver when connected to your CTI middleware by specifying appropriate driver parameters in the definition file (DEF) that you develop for testing your communications driver.
Before using the Test Engine, you configure settings for your communications driver. The Test Engine writes the results of the test to log files. You can specify the log file names by configuring the DEF file. For additional information about communications drivers, see Configuring Communications Drivers and Profiles.
The following table describes the format that your DEF file must adhere to in order to simulate multiple calls.
Table Format of Definition File
| This section ... | Must contain ... |
|---|---|
Driver Parameter |
Driver parameters to connect to the CTI middleware. |
Agent#n Where n = the agent’s identifier |
Parameters necessary to initialize agent login. |
Job |
Description of job to simulate. |
Task |
Description of tasks that comprise the job. Enter the device commands here that a communications driver supports to make sure that the commands and the communications driver function correctly. |
The following procedure describes how you run the Test Engine tool to test a communications driver.
To test a communications driver
Copy your DEF file into the
BINsubdirectory of your Siebel Server or Siebel client installation directory.From a command line, navigate to the
BINdirectory identified in Step 1.At the command prompt, execute the following command:
On Windows:
CommDriverTestEngine.exe definition_file language_code
On UNIX:
CommDriverTestEngine definition_file language_code
For example, on Windows:
CommDriverTestEngine.exe anExampleDefinitionFile.def ENU
The Test Engine tests your communications driver and writes the output to the specified log files.