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

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

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