INFO

SwyxIt! v4.3/v4.4/v5.0x/v6.0/v6.01 Client SDK (kb2636)

The information in this article applies to:

  • SwyxIt! v5.03
  • SwyxIt! v6.01
  • SwyxIt! v6.00
  • SwyxIt! v5.02
  • SwyxIt! v5.01
  • SwyxIt! v5.00
  • SwyxIt! v4.40
  • SwyxIt! v4.30

[ Summary | Information | Links ]


Summary

SwyxIt! provides two interfaces for call control:

  • Client SDK (a COM Interface)
  • TAPI (SwyxIt! TSP supports TAPI 2.x)

If there are no special reasons (e.g. an existing TAPI application) for using TAPI, we really recommend to use the Client SDK. Using Client SDK you may use any call control options of SwyxIt!.


Information

The SwyxIT! Client SDK is version dependent. Further SDK versions can be found here:

 

The central module on a client PC is the Client Line Manager (CLMgr.exe). All applications like SwyxIt!, Swyx Client TSP, Swyx Outlook Addin and third party applications are running on top of the Client Line Manager. For this the Client Line Manager provides a COM interface one can use for controlling lines (establish calls, switch lines, ...). In this way several applications may use the same lines simultaneously. A call may be established using Outlook Addin and can be switched using SwyxIt! later on. Actions like hook off, dialling or switching are initiated by functions of the COM interfaces, state changes of lines will be signalled as COM events or window messages to a window or thread of the client application.

The Client SDK includes a documented interface definition (CLMgrPub.idl) and some example applications in Visual C++, Visual Basic and Visual Basic Script. This documentation explains some general aspects. Please use the idl file as reference.

Directory PublicInterface:

CLMgrPub.idl:
Definition of the public interface
CLMgrPubTypes.c:
Definition of the required GUIDs (for Visual C++)
CLMgrPubTypes.h:
Some types and enumerations for return values

Directory Samples:

Visual Basic Call Info:
Simple Visual Basic Application
Displays information about the selected line.
Visual Basic Simple:
Simple Visual Basic Application
Displays information about the selected line.
Allows simple call control.
Visual Basic Script:
Very simple example.
Explains how to just dial a number.
Visual C++ Simple:
Simple Visual C++ Application
Dialog based MFC Application
Displays information about the selected line.
Allows simple call control.
Visual C++ PlayToRtp:
Simple Visual C++ Application
Dialog based MFC Application
Recording and playback of voice stream.
Visual C++ Call Log:
Simple Visual C++ Application
Dialog based MFC Application
Logs incoming and outgoing calls
Visual C++ Chat:
Simple Visual C++ Application
Dialog based MFC Application
Exchange chat messages between SwyxIt! client PCs
Visual C++ ATL PlugIn:
Enhanced Visual C++ Application
Based on Active Template Library.
Explains the implementation of a Line Manager Plugin.
Provides name resolution for SwyxIt!.
Visual C++ WakeUp:
Simpple Visual C++ Application
Example for establishing wake-up calls using SwyxIt!
Visual Studio.Net C# Simple:
Simple C# Application
Shows how to call Client SDK COM Api methods from a .Net Application
Visual Studio.Net C# IpPbxMPC:
C# Application
ControlsWinamp or Windows Media Player or other media player applications.
Pauses music during phone calls.

Using Client SDK from several programming languages

Visual Basic

With Visual Basic 6 the Client SDK can be added to a project using menu Project\References. Check the library "CLMgr 2.0 Type Library". Afterwards the Object Browser will list all available objects and methods for library CLMGRLib. Due to technical reasons you will see many more objects and interfaces than you can use. From Visual Basic you can use the objects ClientLineMgr and ClientLine and its methods and properties. Only the object ClientLineMgr will be created by your application:

Public WithEvents PhoneLineMgr As CLMGRLib.ClientLineMgr
Set PhoneLineMgr = CreateObject("CLMgr.ClientLineMgr")

ClientLine objects are not created directly, but you will access the line by calling appropriate ClientLineMgr functions. The following example retrieves the selected line and puts it on hold:

Public PhoneLineFocus As Object
Set PhoneLineFocus = PhoneLineMgr.DispSelectedLine
PhoneLineFocus.DispHold

Now follows a selection of methods and properties of the ClientLineMgr object. You will find a detailed description in file CLMgrPub.idl. Though reading an idl-file is uncommon for Visual Basic developers, you will understand it when comparing it with the methods listed in the object browser.

Log on/off

All applications that are registering to the SwyxServer have to call the following functions:
On start: PubInit and PubRegisterUser
On termination: PubReleaseUser
Otherwise the Client Line Manager would not shut down and the user could keep logged on to the SwyxServer.

Important: Log on/off is not required for most applications. As long SwyxIt! is running, it will take care of log on/off and your application should not log on/off. As long SwyxIt! is running and logged on all methods of the Client SDK can be used.Nevertheless, the example "Visual Basic Simple" will show how to log on/off.

Initializing: DispInit(ServerName As String) As LongReturn code 0: no error. Otherwise the result is a HRESULT error code.

Log on: DispRegisterUser(UserName As String) As LongReturn code: user id. If 0 is returned, an error occurred.

Log off: DispReleaseUser(UserId As Long) As Long

Access to lines, switch lines, ...

Access line no. iLineNumber. First line has index 0! DispGetLine(iLineNumber As Long) As Object

Number of selected line. First line has index 0! DispSelectedLineNumber As Long

Access selected line: DispSelectedLine As Object

Switch to line iLineNumber. First line has index 0! DispSelectLineNumber(iLineNumber As Long) As Long

Switch to line ClientLine DispSelectLine(pIClientLine As ClientLine) As Long

Dial a number on arbitrary line DispSimpleDialEx(dialstring As String) As LongReturn code 0: the number has been dialled. Otherwise an error occurred.

On a line you can hook off, dial, put on hold, ...:

Hook off: DispHookOff

Hook on: DispHookOn

Press hook: DispPressHook

Dial: DispDial(dialstring As String)

Put on hold: DispHold

Activate from Hold: DispActivate

Transfer two lines: DispTransferCall(pITargetLine As Object);

Get line state: DispState As Long

0: not active
1: hook off, internal dial tone
2: hook off, external dial tone (public line)
3: incoming call, ringing
4: dialling
5: outgoing call, ringing on destination
6: outgoing call, knocking (second call) on destination
7: outgoing call, destination or ISDN busy. More details in property DispDiscReason
8: active
9: on hold
10: active conference
11: conference on hold
12: terminated. More details in property DispDiscReason
13: transferring. Blind call transfer in progress
14: disabled. Wrap up time. Line does not signal incoming calls
15: direct call. Incoming Intercom call, connection is established, micro is muted

 

Dial string acknowledged by server: DispAcknowledgedDialstring As String

Phone number of peer: DispPeerNumber As String

Name of peer: DispPeerName As String

Reason for busy / terminated: DispDiscReason As Long

0: nothing special
1: peer was busy
2: peer rejected call
3: call was cancelled
4: call was transferred
5: call was added to conference on other line
6: peer did not pick up, timeout
7: call was already picked up from other phone
8: direct call to peer was not allowed
9: invalid number was dialed
10: destination is unreachable
11: call was redirected
12: call routing failed, possible script error (script of peer)
13: permission for call was denied due to call restrictions
14: no line available (public ISDN network)
15: no gateway channel available
16: number of destination has changed
17: destination is incompatible (compression)

 

Further functions and properties are documented in file CLMgrPub.idl.

Receiving Line Manager events with Visual Basic:

Define a ClientLineMgr object: Public WithEvents PhoneLineMgr As CLMGRLib.ClientLineMgr

Create an object: Set PhoneLineMgr = CreateObject("CLMgr.ClientLineMgr")

Add the following function to your code, that will receive the events. The meaning of parameter param is explained in file CLMgrPubTypes.h.

Sub PhoneLineMgr_DispOnLineMgrNotification(ByVal msg As Long, ByVal param As Long)
 Select Case msg
  Case PubCLMgrLineStateChangedMessage
  Case PubCLMgrLineSelectionChangedMessage
  Case PubCLMgrLineDetailsChangedMessage
  Case PubCLMgrCallDetailsMessage
  Case PubCLMgrServerDownMessage
  Case PubCLMgrServerUpMessage
  Case PubCLMgrWaveDeviceChanged
  Case PubCLMgrGroupCallNotificationMessage
  Case PubCLMgrClientShutDownRequest
  Case PubCLMgrNameKeyStateChangedMessage
  Case PubCLMgrNumberOfLinesChangedMessage
  Case PubCLMgrClientShutDownRequest
  Case PubCLMgrPowerSuspendMessage
  Case PubCLMgrPowerResumeMessage
  Case PubCLMgrHandsetStateChangedMessage
 End Select
End Sub

Visual Basic Script

The same interface will be used as with Visual Basic, but receiving events will not be possible.

Defining objects: Dim PhoneLineMgr : Set PhoneLineMgr = Nothing
Dim PhoneLineFocus : Set PhoneLineFocus = Nothing
Dim errval

Create the ClientLineMgr object: Set PhoneLineMgr = Wscript.CreateObject("CLMgr.ClientLineMgr")

Dial a number: errval = PhoneLineMgr.DispSimpleDial("001191")

Get line in focus: Set PhoneLineFocus = PhoneLineMgr.DispSelectedLine

Put line on hold: PhoneLineFocus.DispHold

For further details read the paragraph about Visual Basic.

Visual C++

Example "Visual C++ Simple"

For Visual C++ add the files CLMgrPubTypes.h, CLMgrPubTypes.c und CLMgrPub.idl to your project. You may create a Client Line Manager object (CLSID_ClientLineMgr) and use its interfaces IClientLineMgrPub and IClientLineMgrPub2. The Client Line Manager object provides methods for accessing lines. Using the line interface IClientLinePub you may initiate actions on a line or retrieve line details. This will be shown in the first example "Visual C++ Simple".

Following a selection of methods of the ClientLineMgr object. A detailed documentation is given in file CLMgrPub.idl.

Log on/off

All applications that are registering to the SwyxServer have to call the following functions:
On start: PubInit and PubRegisterUser
On termination: PubReleaseUser
Otherwise the Client Line Manager would not shut down and the user could keep logged on to the SwyxServer.

Important: Log on/off is not required for most applications. As long SwyxIt! is running, it will take care of log on/off and your application should not log on/off. As long SwyxIt! is running and logged on all methods of the Client SDK can be used.Nevertheless, the example "Visual C++ Simple" will show how to log on/off.

Initializing: HRESULT PubInit([in] BSTR ServerName);
Return code 0: no error. Otherwise the result is a HRESULT error code.

Log on: HRESULT PubRegisterUser([in] BSTR UserName, [out] long *pUserId);Return code: user id. If 0 is returned, an error occurred.

Log off: HRESULT PubReleaseUser([in] long UserId);

Access to lines, switch lines, ...

Access line no. iLineNumber. First line has index 0! HRESULT PubGetLine([in] long iLineNumber, [out] IClientLinePub** ppIClientLinePub);

Number of selected line. First line has index 0! HRESULT PubGetSelectedLineNumber([out] long *piLineNumber);

Access selected line: HRESULT PubGetSelectedLine([out] IClientLinePub** ppIClientLine);

Switch to line iLineNumber. First line has index 0! HRESULT PubSelectLineNumber([in] long iLineNumber);

Switch to line pIClientLine HRESULT PubSelectLine([in] IClientLinePub* pIClientLine);

Dial a number on arbitrary line HRESULT PubSimpleDial([in] BSTR dialstring);
Return code 0: the number has been dialled. Otherwise an error occurred.

On a line you can hook off, dial, put on hold, ...:

Hook off: HRESULT PubHookOff();

Hook on: HRESULT PubHookOn();

Press hook: HRESULT PubPressHook();

Dial: HRESULT PubDial([in] BSTR dialstring);

Put on hold: HRESULT PubHold();

Activate from Hold: HRESULT PubActivate();

Transfer two lines: HRESULT PubTransferCall([in] IClientLinePub* pITargetLine);

Get line state: HRESULT PubGetState([out] long *piState);

PubLSInactive:
not active
PubLSHookOffInternal:
hook off, internal dial tone
PubLSHookOffExternal:
hook off, external dial tone (public line)
PubLSRinging:
incoming call, ringing
PubLSDialing:
dialling
PubLSAlerting:
outgoing call, ringing on destination
PubLSKnocking:
outgoing call, knocking (second call) on destination
PubLSBusy:
outgoing call, destination or ISDN busy. More details in PubCLMgrLineDetails
PubLSActive:
active
PubLSOnHold:
on hold
PubLSConferenceActive:
active conference
PubLSConferenceOnHold:
conference on hold
PubLSTerminated:
terminated. More details in PubCLMgrLineDetails
PubLSTransferring:
Call is being transferred
PubLSDisabled:
Line is disabled (wrap up time)
PubLSDirectCall:
Incoming intecom call, connection is established, micro is muted

 

Reason for busy / terminated:

PubSCl3DRNormal:
nothing special
PubSCl3DRBusy:
peer was busy
PubSCl3DRRejected:
peer rejected call
PubSCl3DRCancelled:
call was cancelled
PubSCl3DRTransferred:
call was transferred
PubSCl3DRJoinedConference:
call was added to conference on other line
PubSCl3DRNoAnswer:
peer did not pick up, timeout
PubSCl3DRTooLate:
call was already picked up from other phone
PubSCl3DRDirectCallImpossible:
direct call to peer was not allowed
PubSCl3DRWrongNumber:
invalid number was dialed
PubSCl3DRUnreachable:
destination is unreachable
PubSCl3DRCallDiverted:
call was redirected
PubSCl3DRCallRoutingFailed:
call routing failed, possible script error (script of peer)
PubSCl3DRPermissionDenied:
permission for call was denied due to call restrictions
PubSCl3DRNetworkCongestion:
no line available (public ISDN network)
PubSCl3DRNoChannelAvailable:
no gateway channel available
PubSCl3DRNumberChanged:
number of destination has changed
PubSCl3DRIncompatibleDestination:
destination is incompatible (compression)

 

Further functions are documented in file CLMgrPub.idl.

Events from the Line Manager can be received both as COM events or as window messages. The example "Visual C++ Simple" shows both ways. The build targets "Win32 Debug Using Event Sink" and "Win32 Release Using Event Sink" define USE_EVENT_SINK and use connection points and COM events. In the other case the main window will be registered as target for window messages.

The window messages will be handled in function CMfcClientDlg::OnClientLineManagerEvent(WPARAM wParam, LPARAM lParam)the COM events land in function CCLMgrEventSink::DispOnLineMgrNotification(long msg, long param)The class CCLMgrEventSink may be used modified in your project.

Example "Visual C++ Call Log"

The example "Visual C++ Call Log" shows a MFC client that logs calls. This client runs besides SwyxIt! and does not log on nor off. Here too there are two build targets "Win32 Debug Using Event Sink" and "Win32 Release Using Event Sink" showing both usage of connection points and COM events. The class CCLMgrEventSink may be used modified in your project.

Example "Visual C++ PlayToRtp"

The example "Visual C++ PlayToRtp" shows a MFC client that plays and records wave files to resp. from RTP.

Example "Visual C++ ATL PlugIn"

The example "Visual C++ ATL PlugIn" shows an ATL based client. It implements a Client Line Manager PlugIn that provides name resolution for SwyxIt!. For unknown peer numbers the Client Line Manager will ask all installed PlugIns for a matching name resolution. So you will be able to provide name resolution based on your own database application. This client too will not register with the SwyxServer.

For a customization one has to replace the GUIDs and friendly class names PlugInSample.MyResolver etc. in the files PlugInSample.idl and MyResolver.rgs with new GUIDs and names in order to avoid conflicts with other 3rd party applications based on the Client SDK. But never change any GUID from the files CLMgrPub.idl and CLMgrPubTypes.c!

In file PlugInSample.cpp the functions for registration and deregistration of the PlugIn are implemented. In order to be loaded by the Client Line Manager, the PlugIn writes its class ID into the Line Managers registry HKLM\SOFTWARE\Swyx\Client Line Manager\CurrentVersion\Options\PlugIns\{GUID}

The actual PlugIn object CMyResolver is defined and declared in the files MyResolver.cpp and MyResolver.h. The Das PlugIn object implements the interfaces IClientAddInLoader, IClientResolverAddIn and IClientLineMgrEventsDisp. The interface IClientAddInLoader will be used by the Line Manager on loading and releasing the PlugIn, the interface IClientResolverAddIn provides name resolution. The interface IClientLineMgrEventsDisp finally receives the Line Manager events.

When loading the PlugIn, the Line Manager calls the functions IClientAddInLoader::Initialize, IClientAddInLoader::GetName and IClientAddInLoader::GetVersion. Before releasing the interface IClientAddInLoader and unloading the PlugIn, the Line Manager calls the method IClientAddInLoader::UnInitialize. The PlugIn has then a chance for clean up memory and other resources.

In the example implementation of CMyResolver::Initialize the PlugIn registers an event sink towards the Line Manager for receiving events. The Line Manager interface pointer pIClientLineMgrPub will be stored in the global interface table. Using its cookie m_dwCLMgrCookie the pointer will be retrieved on demand from the global interface table and automatically marshalled into the current thread context. You will find the used helper functions in the files githelp.cpp and githelp.h. This effort is required as soon as a COM interface pointer is used from multiple threads. GetName are GetVersion unspectacular. In the implementation of CMyResolver::UnInitialize the event sink will be released, that's always a good idea.

Line Manager events drop in in function CMyResolver::DispOnLineMgrNotification. Your PlugIn could e.g. write journal entries into a database or trigger a database application for popping up contact information.

In CMyResolver::GetPreferredNumberStyle the PlugIn can ask for a phone number format to be used for name resolution. Usually one would use the format PubCLMgrNumberStyleFull (like 0004923147770 or 0023147770). For any number to be resolved the Client Line Manager will call CMyResolver::ResolveNumber.

Visual C++ WakeUp

This example explains how to use SwyxIt! to establish wake-up calls. Per registry key a special Multi-Line dial mode can be enabled:

  • No implicit line selection
  • If a line is selected explicitly, the previous selected line does not become disconnected on hold
  • The mediastreaming is not linked to the local sound device
  • No local, line related sounds are played
  • No recording of conversations. The transferred call can be recorded, of course, by the transfer target.
  • Hook off/on per local handset will be ignored

 

Enable the Multi-Line dial mode using reg file "MultiLineDialMode.reg". The reg file will set as well the key "CancelBlindTransferOnVoicemail" to 0 for allowing blind call transfer (forward) to a voicemail announcement. Within SwyxIt! one should disable pop up during connection for avoiding annoying pop ups.

The sample allows to dial on all available lines simultaneously. The jobs are read from file JobsToDo.txt. Every line corresponds to a call to do, described by three strings, separated by ';': The first string is the number to be dialed. On connect the call will be transferred to the number given in the second string. The third string is a counter for the retries. When clicking on start in the sample application, the dialling will be initiated after a short timeout. Clicking on stop will abort the process. In a second file all successful calls will be listed. The file JobsToDo.txt lists all not yet successful call and the current number of retries.

Visual Studio.Net C# Simple

This simple example shows how to call Client SDK COM API function from a .Net application. It's a simple Windows Forms application written in C# with Visual Studio.Net 2003. To use the Client SDK COM Api in a .Net Application add the "CLMGR 2.0 Type Library" as reference to your project. Visual Studio.Net 2003 generates a runtime callable wrapper for the COM API which provides a namespace CLMGRLib which allows calling the COM API function and allows consuming events via delegates.

 

Visual Studio.Net C# IpPbxMPC

This example is a complete C# application named IpPBX Media Player Controller. It can be used to control a media player such as Winamp or Windows Media Player. Whenever not all SwyxIt! lines are inactive IpPBXMPC sends the configured player a "pause" command. When all SwyxIt! lines become inactive again, the player gets an "unpause" command from IpPbxMPC. Alternatively the active state of one or more speed dial keys can be used, too. This works with SwyxPhone L420, too, if you use SwyxIt! v4.20 in CTI-Mode to control the SwyxPhone.

 

Consuming events in a C# Application

The Client SDK COM API ClientLineMgrClass supports the .Net framework's delegate/event mechanism. See function ConnectAndLogin() in Form1.cs, for an example on how to use this mechanism to receive LineManager events:
clmgr = new ClientLineMgrClass(); clmgr.DispOnLineMgrNotification +=
   new CLMGRLib.IClientLineMgrEventsDisp_ DispOnLineMgrNotificationEventHandler (this.OnLineMgrNotification);
This creates a delegate which is added to the DispOnLineMgrNotification event of clmgr. Whenever the line manager sends an event the following function is called in the C# application
public void OnLineMgrNotification(System.Int32 msg, System.Int32 param)

Replacing SwyxIt!

If you would like to replace SwyxIt!.exe by an own application (but who would really like to do this?), your application has to implement full call control. Otherwise the user would not have the chance to accept a second call or put a call on hold. Usually it is recommended, that your application just runs beside SwyxIt! for dialling or call monitoring.

The behaviour of the Client Line Managers towards other call control applications can be configured in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\SWYX\Client Line Manager\CurrentVersion\Options

 

DWORD "LaunchCallControlApplication"activates (1, default) or deactivates (0) launching of a call control application in case of hook off. If no application should be launched on hook off, set this value to 0.

DWORD "AlternateCallControl"activates (1) or deactivates (0, default) launching of an alternate call control application. If your own application should be launched instead of SwyxIt!, set this value to 1.

String "AlternateCallControlApplication"provides the full path to the alternate call control application. In this case AlternateCallControl has to be set to 1. The path can include command line options.

To avoid that your alternate application is launched multiple times, your application has to open a named semaphore with name ALTERNATEPHONECLIENTRUNNING. The Client Line Manger will launch your application only if this semaphore does not yet exist:

//use semaphore for checking running instance
HANDLE hSemaphore=OpenSemaphore(SYNCHRONIZE, FALSE, "ALTERNATEPHONECLIENTRUNNING");
if(hSemaphore)
{
 CloseHandle(hSemaphore);
}
else
{
 //no running instance, launch call control application
 WinExec(m_pLineMgr->m_sFullCallControlClientPath.c_str(), SW_SHOW);
}


Links

As far as software supplied or used by us, includes open source elements the additional terms under https://www.swyx.com/open-source apply in addition. An overview which products from the Swyx portfolio include open source elements and which open source license is relevant can be found under https://www.swyx.com/open-source.

The third-party contact information included in this article is provided to help you find the technical support you need. This contact information is subject to change without notice. Swyx in no way guarantees the accuracy of this third-party contact information nor is responsible for it's content.


Comment

Comment on this article



If we have any follow-up questions, where can we contact you?

E-Mail Address (optional)


Note

This feedback form can't be used for support requests. Those requests must be directed to your Swyx reseller or distributor.