CTILINK COM SPECIFICATION


Terminology:

Term Description Associated Methods
Line Device Any device that is associated with a phone number.
DeviceName The name associated with a device, usually an extension number DeviceName
Connection A call associated with a Line Device. There can be any number of connections.
DeviceID An integer uniquely identifying a Line Device
ConnectID In integer that along with a DeviceID uniquely identifies a Connection
Connect Button The button on the CTILink phone bar that can dial, answer and disconnect a call.

ConnectBtnInfo

ConnectBtnClick

Connection Menu The drop-down menu associated with the Connect Button that enables the selection of Line Devices and Connections

ClickConnectionMenuItem

ConnectionMenuItems

Selected Connection The connection on the Connection Menu that is currently selected.

CurrentConnectionState

DialNumber

SetSelectedDevice

GetSelectedDevice

DeviceMenuIndex An integer uniquely identifying the position of a Line Device on the Connection Menu. The first device is 0.

MapMenuIndexToLineDevice

MapLineDeviceToMenuIndex

ConnectMenuIndex An integer uniquely identifying the position of a Connection on the sub-menu of a Line Device. The first connection is 0.
ConnectState An integer with the following possible values: 0 (invalid), 1 (Idle), 2 (Initiating), 3 (Connected), 4 (Hold), 5 (Fail) or 6(Other). CurrentConnectionState
ConnectDetail An integer with the possibled values: 0 (Invalid), 1 (None), 2 (Offering), 3 (Accepted), 4 (Dialtone), 5 (Dialing), 6 (Proceeding), 7 (Ringback), 8 (Initiate), 9 (Alerting), 10 (Connected), 11 (OnHold), 12 (OnHoldPendingConference), 13 (OnHoldPendingTransfer), 14 (Busy), 15 (SpecialInfo), 16 (Conferenced), 17 (Disconnected), 18 (Unknown), 19 (Queued), 20 (ACDCall), 21(OnHoldByAnother), 22 (OutOfService), 23 (CallPickup), 24 (FailError), 25 (FailDND), 26 (FailNoAnswer)

ConnectionData

QueryConnectionData

Hold Button The button on the CTILink phone bar that holds and releases holds.

HoldBtnInfo

HoldBtnClick

Third Party Button The button on the CTILink phone bar that initates consultation calls and conferences calls.

ThirdPartyBtnInfo

ThirdPartyBtnClick

Methods:

Method Name Return Type Arguments Description
ConnectionMenuItems BSTR None

Allows a client to replicate the CTILink connection drop-down menu.

Returns a string representation of the current connection drop-down menu. The format of the string is:

MenuCaption~ParentIndex~ChildIndex~Enabled~Checked~

Where the MenuCaption is the name displayed in the drop-down menu, the ParentIndex is the position of the parent on the menu (0 based), the ChildIndex is the position of the current item relative to the parent, Enabled is 0 if not enabled and 1 if enabled and Checked is 0 if not checked and 1 if checked.

ClickConnectionMenuItem None

ParentPos (Integer [in] )

ChildPos (Integer [in] )

Allows a client to select a menu item on the CTILink connection drop-down menu. ParentPos selects the parent ment item (0 based) and ChildPos selects the child position relative to the parent.
ConnectBtnInfo None

Caption (BSTR * [out] )

Hint (BSTR * [out] )

Enabled (Boolean [out] )

Returns the current state of the connection button where Caption is the caption of the button, Hint is the tool tip displayed when the mouse hovers over it and Enabled indicates whether is the control is enabled
ConnectBtnClick None None "Clicks" the Connect Button. If the line is idle, the Dialer Dialog is displayed. If the line is offering, the call is answered. If the line is proceeding or connected the call is cleared.
HoldBtnInfo None

Caption (BSTR * [out] )

Hint (BSTR * [out] )

Enabled (Boolean [out] )

Checked (Boolean [out] )

Returns the current state of the hold button where Caption is the caption of the button, Hint is the tool tip displayed when the mouse hovers over it, Enabled indicates whether is the control is enabled and Checked indicates if the button is checked or down.
HoldBtnClick None None "Clicks" the hold button, toggling the hold state.
ThirdPartyBtnInfo None

Caption (BSTR * [out] )

Hint (BSTR * [out] )

Enabled (Boolean [out] )

Returns the current state of the third party button where Caption is the caption of the button, Hint is the tool tip displayed when the mouse hovers over it, Enabled indicates whether is the control is enabled and Checked indicates if the button is checked or down.
ThirdPartyBtnClick None None "Clicks" the third party button.
DialNumber None

Number (BSTR [in])

Name (BSTR [in])

Extension (BSTR [in])

Dials Number on the selected connection and displays Name and/or Extension if not empty strings in the CTILink caption bar.
CurrentConnectionState ConnectState (Integer) None Returns the connection state of the currently selected connection.
Notify ID (Integer) Interface (Variant [in] ) Registers a COM interface to allow for event notification. See COM Event Interface methods below for a description of event methods. Returns an ID that is used in ReleaseNotify when the client no longer wishes event notification.
ReleaseNotify None ID (Integer [in] ) Releases an interface identified by ID which was passed in the Notify method.
CreateNotification ID (Integer) ClassID (BSTR [in] ) Same as Notify but ClassID is in the form "serverName.Class" which CTILink can use to instantiate an instance of a COM object.
NumberDevices NumDevs (Integer) None Returns the number of phone devices currently open
NumberSelectedDevices NumDevs (Integer) None

Returns the number of phone devices which are requested to be opened. When CTILink begin opening devices the client app can determine when all devices selected for opening are actually open by comparing NumberDevices with NumberSelectedDevices.

DeviceInfo None

DeviceID (Integer [in] )

DeviceName (BSTR * [out] )

NbrConnects (Integer * [out] )

Returns the DeviceName and number of active connections (NbrConnects) for the device identified by DeviceID.
MapMenuIndexToLineDevice DeviceID(Integer) DeviceMenuIndex (Integer [in] ) Returns the DeviceID corresponding to the position of the device on the CTILink connection menu.
MapLineDeviceToMenuIndex DeviceMenuIndex(Integer) DeviceID (Integer [in] ) Returns the position of the device on the CTILink connection menu (MenuIndex) corresponding to the DeviceID.
LoginAgentToACD None

DeviceID (Integer [in] )

LoginID (BSTR [in] )

Login (Boolean [in] )

Logs the phone identified by DeviceID using LoginID and logs in f Login is true or out if Login is false
MakeAgentBusy None

DeviceID (Integer [in] )

ToBusy (Boolean [in] )

Puts the phone identified by DeviceID into busy if ToBusy is true of off busy if ToBusy is false.
SetSelectedDevice None

DeviceID (Integer [in] )

Index (Integer [in] )

IsConnectID (Boolean [in] )

 

Sets the connection owned by the device identifed by DeviceID as the selected device. If IsConnectID is true the Index is used as the connection Id otherwise it is used as the connection menu index.
GetSelectedDevice None

DeviceMenuIndex (Integer *[out] )

ConnectMenuIndex (Integer*[out] )

ConnectID (Integer *[out] )

Returns the Device Menu Index of the currently selected device on the connection drop-down menu and the connection menu index of the selected child connection menu item and the ConnectID of the current connection. If there is no current connection ConnectID is -1.
QueryAgentStatus Valid (Boolean)

DeviceID (Integer [in] )

 

Queries the ACD feature state for the device identified by DeviceID. The status is returned via the event notification QueryAgentStatusResponse. If DeviceID is invalid, Valid is false otherwise true.
QueryConnectionData Valid (Boolean)

DeviceID (Integer [in] )

ConnectIndex (Integer [in] )

ConnectID (Integer [in] )

IsOutbound (Boolean *out])

ConnectState (Integer *[out] )

ConnectDetail (Integer *[out] )

CallName (BSTR * [out] )

CallNumber (BSTR * [out] )

Extension (BSTR * [out] )

ConnectTime (DATE * [out] )

AssocContact (Variant * [out] )

Returns detailed connection data associated with the device identified by DeviceID. If ConnectIndex is 0 or greater then the connection associated with that connection menu index is returned if ConnectIndex is less than 0 then the connection is identified by the ConnectID. If the connection or device selected does not exist Valid is returned false.
DeviceName Name (BSTR) DeviceID (Integer [in] ) Returns the device name associated with DeviceID
ConnectionData Value (Variant)

DeviceID (Integer [in] )

ConnectID (Integer [in] )

DesiredParam (BSTR [in] )

Returns the connection data associated with the connection identified by DeviceID and ConnectID. If DeviceID is -1 then connection data is returned for the currently selected connection. DesiredParam determines what data is returned. If DesiredParm is "direction" then "Out" is returned if the connection was outbound or "In" if inbound. Other values of DesiredParm are "connect state","connect detail","name","number","extension" and "time". If an invalid DeviceID or ConnectId is passed the return value is "INVALID ID" and if an invalid DesiredParm is passed the return value is "INVALID PARM".
DialConsultationCall None

Number (BSTR[in])

Name (BSTR[in])

Extension (BSTR[in])

Dials a consultation call
ThirdPartyMenuItems BSTR None

Allows a client to replicate the CTILink third party button(Consultation Call button) drop-down menu.

Returns a string representation of the current third party button drop-down menu. The format of the string is:

MenuCaption~ParentIndex~ChildIndex~Enabled~Checked~

Where the MenuCaption is the name displayed in the drop-down menu, the ParentIndex is the position of the parent on the menu (0 based), the ChildIndex is the position of the current item relative to the parent, Enabled is 0 if not enabled and 1 if enabled and Checked is 0 if not checked and 1 if checked.

ClickThirdPartyMenuItem None

ParentPos (Integer [in] )

ChildPos (Integer [in] )

Allows a client to select a menu item on the CTILink third party button drop-down menu. ParentPos selects the parent ment item (0 based) and ChildPos selects the child position relative to the parent.
RefreshPhoneState None None Forces CTILink to send a PhoneStateChanged Event

 

Receiving Phone Events:

Client applications can receive events using three methods.

The first is to pass a COM interface to CTILink through the Notify method or to pass a string that will allow CTILink to create a COM object through the CreateNotification method. In either case, CTILink will call a method on the interface when a phone event occurs. If the client application COM interface does not support the method, CTILink silently ignores the subsequent error so that the client application only needs to support the notification methods it is interested in. This technique is best suited to languages that can create and act on COM interfaces such as C++, Delphi or Visual Basic.

The second technique is to connect to the CTILink interface ICTILinkComServerEvents. This technique is suitable for languages such as C++ or Delphi.

The third involves using the CTILinkBar active X control and connecting to it's events. This technique is best suited to Visual Basic for Applications, VBScritp and JScript.

Following are descriptions of the method events for all three:

COM Interface methods called by CTILink on object passed via the Notify method and methods of ICTILinkComServerEvents:

Method Name Arguments Description
PhoneStateChanged

ConnectBtnHint (BSTR)

ConnectBtnCaption (BSTR)

HoldBtnHint (BSTR)

HoldBtnCaption (BSTR)

ThirdPartyBtnHint (BSTR)

ThirdPartyBtnCaption (BSTR)

ConnectBtnEnabled (Boolean)

HoldBtnEnabled (Boolean)

ThirdPartyBtnEnabled (Boolean)

HoldBtnDown (Boolean)

ThirdPartyBtnHasSubMenu (Boolean)

 

Fired whenever the the CTILink phone bar buttons change. Used when trying to emulate the CTILink phone bar without a need to know more detailed information such as phone states or connection information
ConnectInfoChanged

DeviceID (Integer)

ConnectID (Integer)

IsOutbound (Boolean)

CalledNbr (BSTR)

CallerNbr (BSTR)

CalledName (BSTR)

CallerName (BSTR)

Extension (BSTR)

Fired whenever any information on the connection identified by DeviceID and ConnectID has changed
HaveCallerID

DeviceID (Integer)

AssociatedContact (Variant)

CallerNbr (BSTR)

CalledNbr (BSTR)

CallerName (BSTR)

Fired when a call is received and enough information is available to allow a search of the CallerNbr and CalledNbr. This usually fires before the call is answered. DeviceID identifies the Line Device that received the call, AssociatedContact contains an Outlook Contact Record COM interface (if Outlook is the selected client application) matching the CallerNbr or CalledNbr depending on which number is being searched on, CallerNbr is the ANI and CalledNbr is the DNIS.
ConnectStateChanged

DeviceID (Integer)

ConnectID (Integer)

ConnectState (Integer)

ConnectDetail (Integer)

Fired when the connect state identified by DeviceID, ConnectID has changed.
Shutdown IsOk (Boolean [out] ) Fired when CTILink is closing down. A client application can prevent the shutdown by setting IsOk to false.
ConnectionIDChanged

DeviceID (Integer)

CurConnectID (Integer)

NewConnectID (Integer)

Fires whenever CTILink detects that the phone system has changed the ConnectID

CTILinkBar Active X Interface (ICTILinkBarEvents)

Method Name Arguments Description
OnConnectStateChanged

DeviceID (Integer)

ConnectID (Integer)

ConnectState (Integer)

ConnectDetail (Integer)

StateStr (BSTR)

DetailStr (BSTR)

Fired whenever the connection state or detail has changed for the connection identified by DeviceID and ConnectID. StateStr is a string that contains a displayable description of the ConnectState and DetailStr contains a description of the ConnectDetail
OnConnectInfoChanged

DeviceID (Integer)

ConnectID (Integer)

IsOutbound (Boolean)

CalledNbr (BSTR)

CallerNbr (BSTR)

CalledName (BSTR)

CallerName (BSTR)

Extension (BSTR)

Fired whenever the connection information has changed for the connection identified by DeviceID and ConnectID.
OnLineStateChanged

DeviceID (Integer)

IsOpen (Boolean)

NbrSelectedDevices (Integer)

Fired whenever the line device identified by DeviceID opens or closes. NbrSelectedDevices is the number of devices that are associated with this instance of CTILink.
OnHaveCallerID

DeviceID (Integer)

AssociatedContact (Variant)

CallerNbr (BSTR)

CalledNbr (BSTR)

CallerName (BSTR)

Fired when a call is received an sufficient information is available for the line device identified by DeviceID. AssociatedContact contains an Outlook Contact Record COM interface (if Outlook is the selected client application) matching the CallerNbr or CalledNbr depending on which number is being searched on, CallerNbr is the ANI and CalledNbr is the DNIS.
OnShutdown IsOk (Boolean [in, out] ) Fired when CTILink is about to shutdown. Setting IsOK to false will prevent the shutdown.
OnPhoneStateChanged

ConnectBtnHint (BSTR)

ConnectBtnCaption (BSTR)

HoldBtnHint (BSTR)

HoldBtnCaption (BSTR)

ThirdPartyBtnHint (BSTR)

ThirdPartyBtnCaption (BSTR)

ConnectBtnEnabled (Boolean)

HoldBtnEnabled (Boolean)

ThirdPartyBtnEnabled (Boolean)

HoldBtnDown (Boolean)

ThirdPartyBtnHasSubMenu (Boolean)

Fired whenever the the CTILink phone bar buttons change. Used when trying to emulate the CTILink phone bar without a need to know more detailed information such as phone states or connection information