C SDK Developers Guide

7/22/2019 C SDK Developers Guide

1/88

C# SDK Developers Guide

C# Software Development Kit

Model No. KX-NCS6100

Thank you for purchasing this Panasonic product.

Please read this manual carefully before using this product and save this manual for future use.


2/88

Purpose and ScopeThe purpose of this document is to guide software developers who are interested in using the API interfaces

which are provided by C# SDK version 1.1. The scope of the document is to describe how a developer will use

the C# SDK library to develop applications.

Trademarks Microsoft, MSDN, Windows, Windows Server, Windows Vista and Visual Studio are either registered

trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks identified herein are the property of their respective owners. Microsoft product screen shots reprinted with permission from Microsoft Corporation.

2 C# SDK Developers Guide


3/88

Table of Contents1 Preface ......................................................................................................61.1 Reference ...........................................................................................................................61.2 Definitions, Acronyms, and Terminology .......................................................................6

2 Introduction to C# SDK ............................................................................7

3 Installing C# SDK .....................................................................................83.1 System Requirements ......................................................................................................83.1.1 Required Operating System .............................................................................................83.1.2 Minimum Hardware Requirements ...................................................................................83.1.3 Software Requirements ....................................................................................................83.2 PBX Settings ......................................................................................................................93.2.1 Supported PBX Types ......................................................................................................9

3.2.2 TCP/IP Setting ..................................................................................................................93.2.3 Activation Key ...................................................................................................................93.3 Installing C# SDK Library ...............................................................................................10

4 C# SDK Programming Guide ................................................................144.1 Before Calling C# SDK API .............................................................................................144.2 Using C# SDK Namespace .............................................................................................144.3 Starts and Ends C# SDK Library ...................................................................................154.3.1 Initialize ..........................................................................................................................154.3.2 Shutdown .......................................................................................................................154.4 Monitoring Line Device ...................................................................................................164.4.1 LineOpen ........................................................................................................................164.4.2 LineClose .......................................................................................................................16

4.5 Information Gathering ....................................................................................................174.5.1 PBX Information .............................................................................................................174.5.2 Line Information ..............................................................................................................174.5.2.1 GetLineInfoList ............................................................................................................174.5.2.2 GetLineInfo ..................................................................................................................184.5.2.3 GetLineStatus ..............................................................................................................184.5.3 Call Infor mation ..............................................................................................................194.6 Basic Call Control ...........................................................................................................204.6.1 Answer Call ....................................................................................................................204.6.2 Drop Call ........................................................................................................................204.6.3 Make Call .......................................................................................................................214.6.4 Two Way Recording .......................................................................................................21

4.7 Call Accounting Control .................................................................................................224.7.1 Set SMDR On .................................................................................................................224.7.2 Set SMDR Off .................................................................................................................224.7.3 Get SMDR ......................................................................................................................234.8 Physical Device Control .................................................................................................244.8.1 Button Press ...................................................................................................................244.8.2 Set Ringer Status ...........................................................................................................244.8.3 Set Display .....................................................................................................................254.8.4 Clear Display ..................................................................................................................254.8.5 Terminate Display ..........................................................................................................264.9 C# SDK Events Handling ................................................................................................274.9.1 Call Control Events .........................................................................................................284.9.1.1 KX_APPNEWCALL .....................................................................................................284.9.1.2 KX_CALLSTATE .........................................................................................................29

C# SDK Developers Guide 3

Table of Contents


4/88

4.9.1.3 KX_CALLINFO ............................................................................................................294.9.2 Device State Events .......................................................................................................304.9.2.1 KX_DEVSTATE ...........................................................................................................304.9.3 SMDR Events .................................................................................................................314.9.3.1 KX_SMDR_CREATE ...................................................................................................314.9.3.2 KX_SMDR_DELETE ...................................................................................................314.9.4 PBX Setting and Connection Events ..............................................................................324.9.4.1 KX_REINIT ..................................................................................................................324.9.4.2 KX_RETRIEVE ............................................................................................................324.9.4.3 KX_RECONFIG ...........................................................................................................334.9.5 Initialization Error Events ................................................................................................344.9.5.1 KX_INIT_ERROR ........................................................................................................344.9.5.2 KX_LICENSE_ERROR ...............................................................................................34

5 C# SDK Sample Program ......................................................................355.1 Call Control Sample ........................................................................................................35

5.1.1 Test Procedures .............................................................................................................365.1.2 FormCallControl Class ...................................................................................................375.1.2.1 FormCallControl Constructor .......................................................................................395.1.2.2 Shutdown When Form Closing ....................................................................................405.1.2.3 Respond to Open Button Clicked ................................................................................415.1.2.4 Respond to Answer Call Button Clicked ......................................................................415.1.2.5 Respond to Drop Call Button Clicked ..........................................................................425.1.2.6 Respond to Make Call Button Clicked .........................................................................425.1.2.7 Respond to Two-Way Recording Button Clicked ........................................................435.1.2.8 C# SDK Events ............................................................................................................445.1.2.9 Respond to KX_APPNEWCALL event ........................................................................455.1.2.10 Respond to KX_CALLSTATE event ............................................................................45

5.1.2.11 Respond to KX_CALLINFO event ...............................................................................465.1.2.12 Respond to KX_DEVSTATE event ..............................................................................465.1.2.13 Respond to KX_INIT_ERROR event ...........................................................................475.1.2.14 Respond to KX_LICENSE_ERROR event ..................................................................485.1.2.15 Respond to KX_RECONFIG event ..............................................................................495.1.2.16 Respond to KX_REINIT event .....................................................................................495.1.2.17 Respond to KX_RETRIEVE event ...............................................................................505.1.3 Line Class .......................................................................................................................515.1.3.1 Line Constructor ..........................................................................................................525.1.3.2 Open ............................................................................................................................525.1.3.3 Close ...........................................................................................................................535.1.3.4 Make Call .....................................................................................................................535.1.3.5 Drop Call ......................................................................................................................54

5.1.3.6 Answer Call .................................................................................................................545.1.3.7 Set Two Way Recording ..............................................................................................555.2 Phone Control Sample ....................................................................................................565.2.1 Test Procedures .............................................................................................................575.2.2 FormPhoneControl Class ...............................................................................................585.2.2.1 FormPhoneControl Constructor ...................................................................................605.2.2.2 Shutdown When Form Closing ....................................................................................615.2.2.3 Respond to Open Button Clicked ................................................................................625.2.2.4 Respond to Ring Mode Checked Changed Event .......................................................625.2.2.5 Respond to Set display Button Clicked .......................................................................635.2.2.6 Respond to Clear Display Button Clicked ....................................................................635.2.2.7 Respond to Terminate Display Button Clicked ............................................................64

5.2.2.8 Respond to Keypad Button Clicked .............................................................................645.2.3 ExtensionLine Class .......................................................................................................65


Table of Contents


5/88

5.2.3.1 ExtensionLine Constructor ..........................................................................................665.2.3.2 Open ............................................................................................................................665.2.3.3 Close ...........................................................................................................................675.2.3.4 Button Press ................................................................................................................675.2.3.5 Set Ringer ....................................................................................................................685.2.3.6 Set Display ..................................................................................................................685.2.3.7 Clear Display ...............................................................................................................695.2.3.8 Terminate Display ........................................................................................................695.3 SMDR Sample ..................................................................................................................705.3.1 Test Procedures .............................................................................................................715.3.2 FormSMDR Class ..........................................................................................................725.3.2.1 FormSMDR Constructor ..............................................................................................745.3.2.2 Shutdown When Form Closing ....................................................................................755.3.2.3 Respond to SMDR ON Button Clicked ........................................................................755.3.2.4 Respond to SMDR OFF Button Clicked ......................................................................765.3.2.5 Respond to Button Get SMDR Information Click .........................................................76

5.3.2.6 C# SDK Events ............................................................................................................775.3.2.7 Respond to KX_SMDR_CREATE event .....................................................................785.3.2.8 Respond to KX_SMDR_DELETE event ......................................................................785.3.3 SystemLine Class ...........................................................................................................795.3.3.1 SystemLine Constructor ..............................................................................................795.3.3.2 SMDR ON ....................................................................................................................805.3.3.3 SMDR OFF ..................................................................................................................805.3.3.4 Get SMDR ...................................................................................................................81

6 Frequently Asked Questions ................................................................826.1 General TSP Setting ........................................................................................................826.1.1 How to configure multiple PBX? .....................................................................................82

6.1.2 How to know the CTI port of a PBX? ..............................................................................826.1.3 How to verify TSP PBX connection? ........................................................................826.1.4 How to generate KX_REINIT and KX_RETRIEVE event? .............................................836.2 C# SDK Information ........................................................................................................846.2.1 What is the C# SDK library? ...........................................................................................846.2.2 Can C# SDK library work with 1st Party TSP? ...............................................................846.2.3 How do I obtain an activation key for a Third Party CTI (KX-NCS3930)? ......................846.2.4 How do I install an activation key for a Third Party CTI (KX-NCS3930)? .......................846.2.5 How do I find the IP address for the connected PBX? ...................................................846.2.6 How do I identify a PBX? ................................................................................................846.2.7 How do I find a call ID of a call? .....................................................................................846.2.8 How do I find the name of a line? ...................................................................................856.2.9 How do I find the dialable address for destination to be dialed? ....................................85

6.2.10 How do I find the voice mail group number in order to useSetTwoWayRecording? ..................................................................................................85

6.2.11 Why does my application not receive any events from SDK? ........................................856.2.12 Can I initialize SDK more than one time in my application? ...........................................856.2.13 Do I need to shutdown SDK when my application exits? ...............................................856.2.14 How do I know which PBX is returning errors during SDK initialization? .......................866.2.15 What are those APIs which need to execute on an opened line? ..................................866.2.16 Why I did not receive any notification in an SMDR related event after

SetSMDROn? .................................................................................................................866.2.17 Can I install more than one instance of C# SDK in the same PC? ................................866.2.18 How can I uninstall C# SDK? .........................................................................................86

7 C# SDK Error Troubleshooting .............................................................87


Table of Contents


6/88

1 Preface

1.1 Reference1. C# SDK Library API Reference Manual2. Panasonic KX-TDA TAPI Specification Version 3.33. TAPI reference from MSDN 2009

1.2 Definitions, Acronyms, and TerminologySDK Software Development Kit

TSP TAPI Service Provider DLL Dynamic Link Library

SMDR Station Message Detail Recording

PS Portable Station

PT Proprietary Telephone

DPT Digital Proprietary Telephone


1.2 Definitions, Acronyms, and Terminology


7/88

2 Introduction to C# SDK

C# SDK library is a DLL composed by C# class library and is a wrapper class located on TAPI. C# SDK providesa simple and easy-to-use programming interface.

To use C# SDK library, Panasonic TAPI Service Provider (Panasonic 3rd Party TSP) is required.

The following figure shows the architecture of C# SDK application.

C# API

Windows PC

3rd Party CSTA

Panasonic PBX

User Application

C# SDK Library

Windows Telephony Service

Panasonic 3rd Party TSP

TAPI

Note

C# SDK library assumes that no other TAPI application is running on the same PC.This is to ensure that C# SDK library has full control over the PBX.

Use a Panasonic 3rd Party TSP that is compatible with the environment in which the C# SDK libraryis being used.

Obtain Panasonic 3rd Party TSP from sales companies or dealers distributing C# SDK.



8/88

3 Installing C# SDK

3.1 System Requirements

3.1.1 Required Operating System

Panasonic C# SDK version 1.1 library will be able to work on the following operation system:

Microsoft Windows XP (32-bit only) Microsoft Windows Vista (32-bit and 64-bit) Microsoft Windows Server 2008 (32-bit and 64-bit) Microsoft Windows 7 (32-bit and 64-bit)

3.1.2 Minimum Hardware Requirements

Windows has to work on the PC LAN interface is needed.

3.1.3 Software Requirements

Microsoft .NET Framework version 3.5 Microsoft Visual Studio 2008 Panasonic 3rd Party TSP version 3.3 or later


3.1.3 Software Requirements


9/88

3.2 PBX Settings

3.2.1 Supported PBX TypesSupported PBX types are KX-TDE100/200 (PMMPR Software File Version 3.0000 or later), KX-TDE600

(PGMPR Software File Version 3.0000 or later), and KX-NCP500/KX-NCP1000.

Panasonic 3rd Party TSP uses TCP/IP to connect and control the KX-TDE/KX-NCP series PBX.

Note

KX-TDA100/200/600 are not supported.

3.2.2 TCP/IP Setting

Before installation, please make sure you know the IP address of the PBX and its CTI port. By default the CTIport is 33333.

3.2.3 Activation Key

To use C# SDK features, the following activation key is required. Activation Key for Third Party CTI (KX-NCS3930)

To obtain and install the activation key, refer to section 6.2.3 How do I obtain an activation key for a ThirdParty CTI (KX-NCS3930)? and 6.2.4 How do I install an activation key for a Third Party CTI

(KX-NCS3930)?


3.2.3 Activation Key


10/88

3.3 Installing C# SDK Library1. Double-click the C# SDK setup file.

Note

If another installation is already running, the following dialog is displayed and the installation process

is aborted.

2. Click Next to continue installation. Click Cancel to abort.


3.3 Installing C# SDK Library


11/88

3. Select I accept the terms of the license agreement and then click Next to continue installation afterreading the agreement. Click Cancel to abort installation. Click Back to go back to the previous step.

4. Click Next to continue installation with default installation path. Click Cancel to abort installation.

Click Back to go back to the previous step.




12/88

The default installation path is the setup file location. Click Change and then select desired installation

path from the following dialog.

5. Click Install to start installation. Click Cancel to abort installation. Click Back to go back to the previousstep.




13/88

6. Click Finish to complete the installation.




14/88

4 C# SDK Programming Guide

4.1 Before Calling C# SDK APIIn order to use the C# SDK library, the application needs the following:

Install Panasonic 3rd Party TSP and configure the settings for connecting to the PBX. PBX contains Activation Key for Third Party CTI (KX-NCS3930). The application project must make a reference to KXTapiAPI.dll found in C# SDK.

4.2 Using C# SDK NamespaceC# SDK namespace must be added.


4.2 Using C# SDK Namespace


15/88

4.3 Starts and Ends C# SDK Library

4.3.1 InitializeInitialize is used to start the C# SDK library. Error event is sent if error occurred or activation key validation

failed during initialization. User application which is interested in receiving initialization error event needs to

subscribe to C# SDK event before calling Initialize method.

4.3.2 Shutdown

To shutdown the C# SDK library:


4.3.2 Shutdown


16/88

4.4 Monitoring Line Device

4.4.1 LineOpenLineOpen is used to monitor a line device.

4.4.2 LineClose

LineClose is used to stop monitoring a line device.


4.4.2 LineClose


17/88

4.5 Information Gathering

4.5.1 PBX InformationGetPBXInfo is used to get PBX information for an opened line device.

For details ofV_PBXINFO, please refer to C# SDK Library API Reference Manual.

4.5.2 Line Information

4.5.2.1 GetLineInfoList

GetLineInfoList is used to get a list of line information for all available lines in the system.This method is used to obtain line information after initialization (e.g: line ID, extension number). For details of

V_LINEINFO, please refer to C# SDK Library API Reference Manual.




18/88

4.5.2.2 GetLineInfo

GetLineInfo is used to get line information for a specified line in the system.

This method is used to update line information. For details ofV_LINEINFO, please refer to C# SDK Library

API Reference Manual.

4.5.2.3 GetLineStatus

GetLineStatus is used to get current line status of a line device.

This method returns an enumeration, E_LINESTATUS. For monitored line, C# SDK library returns KX_INS or

KX_OUS depending on current status of the line. For non-monitored line, C# SDK library returns

KX_UNKNOWN.




19/88

4.5.3 Call Information

To get current call information of a call, GetCallInfo method is used.

GetCallInfo returns a V_CALLINFO structure containing requested call information. For details of

V_CALLINFO, please refer to C# SDK Library API Reference Manual.


4.5.3 Call Information


20/88

4.6 Basic Call Control

4.6.1 Answer CallAnswerCallis used to answer a specified incoming call. The call state of the incoming call must be offering.

4.6.2 Drop Call

DropCallis used to drop a specified call. For called party, the call state must be connected otherwise

KX_INVALCALLSTATEerror is returned.


4.6.2 Drop Call


21/88

4.6.3 Make Call

MakeCallis used to place a call on a specified line to a destination address as specified.

4.6.4 Two Way Recording

SetTwoWayRecording is used to record a specified connected conversation into the requesting devices

mailbox. This method is not available for a SIP type of extension. Voice mail setting is required to use this

feature.


4.6.4 Two Way Recording


22/88

4.7 Call Accounting ControlNote

All SYSTEM lines for PBX with activation key (KX-NCS3930) are monitored by default when Initializemethod is called.

SYSTEM line needs to be monitored in order to use call accounting control methods.

4.7.1 Set SMDR On

SetSMDROn is used to enable call accounting information. After starting SMDR on, KX_SMDR_CREATE

event is generated for SYSTEM line whenever a CO call ends.

4.7.2 Set SMDR Off

SetSMDROffis used to disable call accounting information. After starting SMDR off, application will not receive

an SMDR event.


4.7.2 Set SMDR Off


23/88

4.7.3 Get SMDR

GetSMDRis used to get a specified call accounting information. This method returns call account information

of type V_CALLACCOUNTINFO. For details ofV_CALLACCOUNTINFO, please refer to C# SDK Library API

Reference Manual.


4.7.3 Get SMDR


24/88

4.8 Physical Device Control

4.8.1 Button PressButtonPress is used to simulate activation of a specified button for a specified proprietary telephone.

4.8.2 Set Ringer Status

SetRingerStatus is used to ring a specified extension telephone using a specified ring mode.

For details ofE_RINGMODE, please refer to C# SDK Library API Reference Manual.


4.8.2 Set Ringer Status


25/88

4.8.3 Set Display

SetDisplayis used to set specified text to a telephone display. This method supports PT (DPT and IP-PT) and

PS extension lines only.

4.8.4 Clear Display

ClearDisplayis used to clear all text on the telephone display. This method supports PT (DPT and IP-PT) and

PS extension lines only.


4.8.4 Clear Display


26/88

4.8.5 Terminate Display

TerminateDisplay is used to terminate the control for telephone display. This method supports PT (DPT and

IP-PT) and PS extension lines only.


4.8.5 Terminate Display


27/88

4.9 C# SDK Events HandlingC# SDK library uses events to notify user applications regarding change of line or call state, call information

and PBX setting or connection. User applications that are interested in C# SDK events needs to subscribeKXMessageEvent.


4.9 C# SDK Events Handling


28/88

The following are the methods for handling each event according to categories.

4.9.1 Call Control Events

4.9.1.1 KX_APPNEWCALL

KX_APPNEWCALL is sent when a new call ID is created.




29/88

4.9.1.2 KX_CALLSTATE

KX_CALLSTATEis sent when the state of the specified call has changed.

For details ofE_LINECALLSTATE, please refer to C# SDK Library API Reference Manual.

4.9.1.3 KX_CALLINFO

KX_CALLINFO is sent when call information about the specified call has changed.

For details ofV_EVENTCALLINFO, please refer to C# SDK Library API Reference Manual.




30/88

4.9.2 Device State Events

4.9.2.1 KX_DEVSTATEKX_DEVSTATEis sent when the state of a specified line device has changed.

For details ofE_LINEDEVSTATE, please refer to C# SDK Library API Reference Manual.


4.9.2 Device State Events


31/88

4.9.3 SMDR Events

4.9.3.1 KX_SMDR_CREATEKX_SMDR_CREATE is sent to report that call accounting information is added into call account information

buffers.

4.9.3.2 KX_SMDR_DELETE

KX_SMDR_DELETEis sent to report that call accounting information is deleted from call account information

buffers.


4.9.3 SMDR Events


32/88

4.9.4 PBX Setting and Connection Events

4.9.4.1 KX_REINITKX_REINITis sent when any connection error between PBX and C# SDK Library has occurred.

4.9.4.2 KX_RETRIEVE

KX_RETRIEVEis sent when connection between PBX and C# SDK Library has been recovered after a

connection error occurred.




33/88

4.9.4.3 KX_RECONFIG

KX_RECONFIG is sent when the PBX setting is changed.




34/88

4.9.5 Initialization Error Events

4.9.5.1 KX_INIT_ERRORKX_INIT_ERRORis sent when an initialization error occurs.

4.9.5.2 KX_LICENSE_ERROR

KX_LICENSE_ERRORis sent when PBX does not contain an activation key (KX-NCS3930).


4.9.5 Initialization Error Events


35/88

5 C# SDK Sample Program

C# SDK includes three sample programs. The source code is located in the Sample Code folder. Theexecutables are located in the Executables folder in the Sample Code folder.

KXTapiAPI.dll must be in the same folder to execute the executables.

5.1 Call Control SampleThis sample demonstrates how to use the C# SDK library to develop simple call control application. Call control

sample is able to monitor a line, make an outgoing call, drop a call, answer an incoming call and set two-way

recording during call connection.

Call control sample will demonstrate how to use the following APIs supported by C# SDK library:

Initialize GetLineInfoList GetLineInfo LineOpen LineClose MakeCall DropCall AnswerCall SetTwoWayRecording Shutdown

This sample will also demonstrate how to handle the following C# SDK events:

KX_APPNEWCALL KX_CALLSTATE KX_CALLINFO KX_INIT_ERROR KX_LICENSE_ERROR KX_DEVSTATE KX_RECONFIG KX_REINIT KX_RETRIEVE


5.1 Call Control Sample


36/88

5.1.1 Test Procedures

The following figure shows the Call Control Sample program running. The following are the test procedures:

1. Select an extension line device from the available line devices list.2. Click Open button to monitor the selected line. Extension name and status will be updated for themonitored line.

3. Enter destination number in the Called Number text box. For destination number of desired line device,refer to Ext Number of its line information.

4. Click Make Call button to place a call.

5. Call information will be updated according to call events.6. Click Drop Call button to drop the call.




37/88

5.1.2 FormCallControl Class

This FormCallControlclass in CallControlForm.cs responds to button clicks, C# SDK events and updates user

interface. FormCallControlconstructor is responsible to initialize C# SDK and register to SDK events.

The following is the outline ofFormCallControlclass.




38/88




39/88

5.1.2.1 FormCallControl Constructor

FormCallControlconstructor initialize C# SDK library once the application is started. C# SDK library uses

events to facilitate communication with a user program. An event is sent to a user application during initialization

if there is any occurrence of an activation key validation error. User applications that are interested in receiving

an initialization error event are required to subscribe to a C# SDK event before calling initialize.

The following is the code written to subscribe C# SDK event, initialize C# SDK library, get list of available lines

and line information.

When this application starts, FormCallControlwill initialize call and line information using

ClearCallInformation and ClearLineInformation methods. MonitorLine is initialized as a Line object. Line is a




40/88

class defined to handle line related information and line functions. Details for this class will be discussed later

in this document. KXMessageEvent is subscribed, followed by C# SDK library initialization. GetLineInfoList is

called after initialization to get all available lines for the system.

In case of initialization failed or no PBX is available, KX_NOLINEmessage is returned.

The following error message is shown and call control sample application is terminated.

5.1.2.2 Shutdown When Form Closing

When form is closing, call control sample calls Shutdown method to end C# SDK library usage.




41/88

5.1.2.3 Respond to Open Button Clicked

Method btnMonitor_Click is registered as the event handling method for a click event of Open button.

When Open button is clicked, btnMonitor_Clickwill open the currently selected line, clear call information

and update line information. If an application is monitoring a line, this monitored line will be closed and the

currently selected line is monitored or opened.

The following is the code written to respond to monitor button click:

5.1.2.4 Respond to Answer Call Button Clicked

When Answer Call button is clicked and if a call exists,AnswerCallmethod in Line class will be invoked.

Value forCallID indicates the existence of a call. CallID is set to 0 if no call exists.

The following is the code written forbtnAnswerCall_Click, the event handling method for click event of Answer

Call button:




42/88

5.1.2.5 Respond to Drop Call Button Clicked

DropCallmethod in Line class will be invoked if a call exists when Drop Call button is clicked. CallID is set

to 0 if no call exists and no action will be performed if drop call button is clicked.

The following is the code written forbtnDropCall_Click, the event handling method for click event of Drop

Call button:

5.1.2.6 Respond to Make Call Button Clicked

MakeCallmethod in Line class is invoked when Make Call button is clicked. CallID is updated once

MakeCallsuccessful.

The following is the code written forbtnMakeCall_Clickmethod:




43/88

5.1.2.7 Respond to Two-Way Recording Button Clicked

Method btnTwoWayRecord_Clickis registered as the event handling method for click event of the Two-Way

Recording button. When the Two-Way Recording button is clicked, TwoWayRecordingmethod in Line

class will be invoked if call exists and voice mail number is entered.

The following is the code written forbtnTwoWayRecord_Clickmethod:




44/88

5.1.2.8 C# SDK Events

OnKxRespondmethod is registered as event handling method for C# SDK events when an application starts.

The following is the code written forOnKxRespondmethod:




45/88

5.1.2.9 Respond to KX_APPNEWCALL event

OnNewCallEventmethod is invoked when KX_APPNEWCALL event is received.

KX_APPNEWCALL event is sent when a new call is created. This event provides call ID for a new call.

The following is the code written forOnNewCallEventmethod:

5.1.2.10 Respond to KX_CALLSTATE event

KX_APPNEWCALL event is always followed by a KX_CALLSTATEevent which indicates the initial state of

the call. OnCallStateEventmethod is invoked when KX_CALLSTATEevent is received. KX_CALLSTATE

event is sent when status of a call has changed.

The following is the code written forOnCallStateEventmethod:




46/88

5.1.2.11 Respond to KX_CALLINFO event

OnCallInformationEvent method is invoked when KX_CALLINFO event is received.

KX_CALLINFO event is sent when call information has changed. This event is sent along with call information

structure, V_EVENTCALLINFO. For detailed information about V_EVENTCALLINFO, please refer to C#

SDK Library API Reference Manual.

The following is the code written forOnCallInformationEventmethod:

5.1.2.12 Respond to KX_DEVSTATE event

OnDevState method is invoked when KX_DEVSTATEevent is received. KX_DEVSTATEevent is sent when

state of a monitored line has changed. In case application received KX_REINITstate, Windows Telephony

Service should be restarted. This scenario occurs when TSP fails to retrieve broken connection.

The following is the code written forOnDevState method:




47/88

The following figure shows the information dialog forKX_DEVSTATEevent:

5.1.2.13 Respond to KX_INIT_ERROR event

KX_INIT_ERRORis sent when C# SDK library fails to LineOpen a SYSTEM line during initialization. Theprovider name of the SYSTEM line is provided in this event.

The following is the code written forOnInitErrormethod:

The following figure shows the error dialog forKX_INIT_ERRORevent:




48/88

5.1.2.14 Respond to KX_LICENSE_ERROR event

KX_LICENSE_ERRORis sent if specified PBX does not contain activation key (KX-NCS3930). The PBX

information for the PBX which failed is sent along with this event. For detailed information about

V_PBXINFO, please refer to C# SDK Library API Reference Manual.

The following is the code written forOnLicenseErrormethod:

The following figure shows the error dialog forKX_LICENSE_ERRORevent:




49/88

5.1.2.15 Respond to KX_RECONFIG event

KX_RECONFIG is sent if specified PBX setting changed. User needs to shutdown and reinitialize the C#

SDK library to get updated PBX setting.

The following is the code written forOnReconfigmethod:

5.1.2.16 Respond to KX_REINIT event

KX_REINITis sent if specified PBX connection error occurred. TSP tries to retrieve the connection for several

times. All APIs are unavailable during connection retrieve process. This message is sent to all monitored lines.

The following is the code written forOnReinitmethod:

The following figure shows the information dialog forKX_REINITevent:




50/88

5.1.2.17 Respond to KX_RETRIEVE event

KX_RETRIEVEis sent when connection between PBX and the C# SDK library has been recovered by

connection recovery process after a connection error occurred. This message is sent to all monitored lines.

The following is the code written forOnRetrieve method:

The following figure shows the information dialog forKX_RETRIEVEevent:




51/88

5.1.3 Line Class

This Line class in CallControlForm.cs is responsible for storing line information and performing line related

operations.

The following is the outline ofLine class.


5.1.3 Line Class


52/88

5.1.3.1 Line Constructor

Line constructor initialized local members.

The following is the code written forLine constructor:

5.1.3.2 Open

Open method is invoked when the Open button is clicked. This method responsible to call LineOpen to startmonitors a line device. Local memberbIsLineOpen is set to true ifLineOpen succeeds and line information is

updated.

The following is the code written forOpen method:


5.1.3 Line Class


53/88

5.1.3.3 Close

Close method is invoked when the Open button is clicked. Method btnMonitor_Clickwill check whether any

line is opened before opening a line. If call control sample is currently opening a line, Close method is invoked

to close the line.

The following is the code written forClose method:

5.1.3.4 Make CallMakeCallmethod is invoked when the Make Call button is clicked. Call ID for the newly placed call is returned.

The following is the code written forMakeCallmethod:


5.1.3 Line Class


54/88

5.1.3.5 Drop Call

DropCallmethod is invoked when the Drop Call button is clicked. This method is called only if call exists for

monitored line.

The following is the code written forDropCallmethod:

5.1.3.6 Answer Call

AnswerCallmethod is invoked when the Answer Call button is clicked. This method is called only if call exists

for monitored line.

The following is the code written forAnswerCallmethod:


5.1.3 Line Class


55/88

5.1.3.7 Set Two Way Recording

TwoWayRecordingmethod is invoked when the Two-Way Recording button is clicked. This method is called

only if call exists for monitored line and voice mail number is entered.

The following is the code written forTwoWayRecordingmethod:


5.1.3 Line Class


56/88

5.2 Phone Control SampleThis sample demonstrates how to use the C# SDK library to develop simple phone control applications. A

phone control sample is able to monitor an extension line, control phone display, set ringer status and simulatea button press. Phone control sample is focused on the extension line only because only the extension line is

eligible to set phone control.

Phone control sample will demonstrate how to use the following APIs supported by the C# SDK library:

Initialize GetLineInfoList LineOpen LineClose SetDisplay ClearDisplay TerminateDisplay

SetRingerStatus ButtonPress Shutdown

This sample will also demonstrate how to handle the following initialization error events:

KX_INIT_ERROR KX_LICENSE_ERROR KX_DEVSTATE KX_RECONFIG KX_REINIT KX_RETRIEVE

Note

Description for events handling, please refer to Call Control Sample section.


5.2 Phone Control Sample


57/88


The following figure shows the Phone Control Sample program running.

The following are the test procedures:

1. When the Phone Control Sample application started, the first extension line on the list is monitored. In casethe user wants to switch to another extension line, select desired extension line and click the Open button

to monitor the selected line.

2. Click on radio button in the Ringer Status group box, ringer status is set for the monitored line.

3. Enter row, column and message into text box in the Display group box and then click Set button to setphone display.

4. Click on Clear to clear the display and Terminate to terminate the control to phone display.5. Click on any key in the Key Pad group box to simulate a button press on a monitored extension line.




58/88

5.2.2 FormPhoneControl Class

This FormPhoneControlclass in FormPhoneControl.cs used to respond to user interface action and C#

SDK events. FormCallControlconstructor is responsible to initialize the C# SDK library and register to C#

SDK events.

The following is the outline ofFormPhoneControlclass.




59/88




60/88

5.2.2.1 FormPhoneControl Constructor

FormPhoneControlconstructor initialize the C# SDK library once the application is started. C# SDK library

uses events to facilitate communication with a user program. An event is sent to a user application during

initialization if there is any occurrence of an activation key validation error. User applications that are interested

in receiving an initialization error event are required to subscribe to a C# SDK event before calling initialize.

The following is the code written forFormPhoneControlconstructor to subscribe to a C# SDK event, initialize

C# SDK library, and get list of available extension lines and line information. First available extension line is

monitored when application is started.




61/88

When application start, MonitorLine member is initialized as an ExtensionLine object. ExtensionLine is a class

defined to handle line information and phone control functions. Details for this class will be discussed later inthis document.


When form is closing, phone control sample calls Shutdown method to end C# SDK library usage.




62/88

5.2.2.3 Respond to Open Button Clicked

When the Open button is clicked, btnMonitor_Clickwill check whether any other line is monitored. If an

application is monitoring a line, the monitored line is closed and currently selected line is monitored or opened.

The following is the code written to respond to a monitor button click:

5.2.2.4 Respond to Ring Mode Checked Changed Event

When the ring mode radio button is checked, FormPhoneControlwill invoke ExtensionLine class SetRinger

method to ring the monitored line.

The following is the code written forRingMode_CheckedChangedmethod:




63/88

5.2.2.5 Respond to Set display Button Clicked

When the Set button is clicked and if the row and column edit box have valid input, SetDisplaymethod in

ExtensionLineclass will be called. User interface forFormPhoneControlis updated ifSetDisplayis successfull.

The following is the code written forbtnSetDisplay_Clickmethod:

5.2.2.6 Respond to Clear Display Button ClickedWhen the Clear button is clicked, the displayed message on phone LCD is cleared.

The following is the code written forbtnClear_Clickmethod:




64/88

5.2.2.7 Respond to Terminate Display Button Clicked

When the Terminate button is clicked, control over phone display is stopped.

The following is the code written forbtnTerminate_Clickmethod:

5.2.2.8 Respond to Keypad Button Clicked

Keypadis a customized user control according to physical phone keypad. When button for keypad is clicked,

ButtonClickevent is sent to FormPhoneControl. CtrlKeypad_ButtonClickused to respond to keypad button

click event.

The following is the code written forCtrlKeypad_ButtonClickmethod:




65/88

5.2.3 ExtensionLine Class

This ExtensionLine class in FormPhoneControl.cs is responsible for storing line information and performing

phone control related operations.

The following is the outline ofExtensionLine class.




66/88

5.2.3.1 ExtensionLine Constructor

ExtensionLine constructor initializes local members.

The following is the code written forExtensionLine constructor:

5.2.3.2 Open

Open method is invoked when the Open button is clicked. This method will call LineOpen to start monitoring

a line device. Local memberbIsLineOpen is set to true ifLineOpen succeeded.

The following is the code written forOpen method:




67/88

5.2.3.3 Close

Close method is invoked when the Open button is clicked. Method btnMonitor_Clickwill check whether any

line is opened before opening a line. If phone control sample is currently opening a line, Close method is

invoked to close the line.

The following is the code written forClose method:

5.2.3.4 Button Press

ButtonPress method is invoked when a KeyPadbutton is clicked.

The following is the code written forButtonPress method:




68/88

5.2.3.5 Set Ringer

RingMode_CheckedChangedmethod invokes SetRingerwhen ring mode radio button is checked.

The following is the code written forSetRingermethod:

5.2.3.6 Set Display

SetDisplaymethod is invoked as respond for the Set button click event.

The following is the code written forSetDisplaymethod:




69/88

5.2.3.7 Clear Display

ClearDisplaymethod is invoked as respond for Clear button click event.

The following is the code written forClearDisplaymethod:

5.2.3.8 Terminate Display

TerminateDisplaymethod is invoked as a response for the Terminate button click event.

The following is the code written forTerminateDisplaymethod:




70/88

5.3 SMDR SampleThis sample demonstrates how to use the C# SDK library to develop simple call accounting applications. The

SMDR sample is used to enable or disable call accounting information and get call accounting information.Call accounting information can only be stored in SYSTEM line, hence the SYSTEM line is the focus for an

SMDR sample.

An SMDR sample will demonstrate how to use the following APIs supported by the C# SDK library:

Initialize GetLineInfoList SetSMDROn SetSMDROff GetSMDR Shutdown

NoteLineOpen and LineClose for SYSTEM line are not required because SYSTEM line is monitored by default

during C# SDK library initialization.

This sample will also demonstrate how to handle the following C# SDK events:

KX_SMDR_CREATE KX_SMDR_DELETE KX_INIT_ERROR KX_LICENSE_ERROR KX_DEVSTATE KX_RECONFIG KX_REINIT KX_RETRIEVE

Note

Description forKX_SMDR_CREATEand KX_SMDR_DELETEwill be discussed in this section.

Description for others event handling, please refer to the Call Control Sample section.


5.3 SMDR Sample


71/88


The following figure shows the SMDR Sample program running.

The following are the test procedures:1. When SMDR application is started, all the SYSTEM lines in the list are monitored.2. Select a SYSTEM line and click the ON button in the Control group box, call accounting information is

enabled for that selected SYSTEM line.

3. Make a CO call for that PBX and KX_SMDR_CREATE event is received once the call ends.4. Enter the call accounting information ID into the Information ID text box and click Get Info button. Account

information is updated.

5. Click the OFF button in the Control group box to disable call accounting information.

Note

In the above figure, two PBX are connected. One is Line ID of SYSTEM line 7, the other is Line ID of

SYSTEM line 389.




72/88

5.3.2 FormSMDR Class

This FormSMDRclass in FormSMDR.cs is used to respond to user interface action and C# SDK events.

FormSMDRconstructor is responsible for initializing the C# SDK library and registering to C# SDK events.

The following is the outline ofFormSMDRclass.




73/88




74/88

5.3.2.1 FormSMDR Constructor

FormSMDRconstructor initializes the C# SDK library once the application is started. An event is sent to a user

application during initialization if there is any occurrence of activation key validation error. User applications

that are interested in initialization error events are required to subscribe to C# SDK event before calling initialize.

The following is the code written forFormSMDRconstructor to subscribe C# SDK event, initialize the C#

SDK library, and get a list of lines and add an available SYSTEM line to the list box.

All SYSTEM lines are monitored by default during C# SDK library initialization.AddSystemLine method is used

to update user interface with available SYSTEM lines only.




75/88


When the form is closing, the SMDR sample invokes a Shutdown method to end C# SDK library usage.

5.3.2.3 Respond to SMDR ON Button Clicked

When the ON button is clicked, btnSMDRON_Clickwill invoke an SMDRONmethod in SystemLine Class to

enable call accounting information.

The following is the code written forbtnSMDRON_Clickmethod:




76/88

5.3.2.4 Respond to SMDR OFF Button Clicked

When the OFF button is clicked, btnSMDROFF_Clickwill invoke an SMDROFFmethod in SystemLine Class

to disable call accounting information.

The following is the code written forbtnSMDROFF_Clickmethod:

5.3.2.5 Respond to Button Get SMDR Information Click

When the Get Info button is clicked, btnGetSMDR_Clickwill check whether call accounting ID is valid. If call

accounting ID is valid, GetSMDRin SystemLine class is invoked and account information is updated.

The following is the code written forbtnGetSMDR_Clickmethod:




77/88

5.3.2.6 C# SDK Events

OnKXLinesRespondmethod is registered as event handling method for C# SDK event when application start.

The following is the code written forOnKXLinesRespondmethod:

Description forKX_INIT_ERRORand KX_LICENSE_ERRORevent handling, please refer to Call Control

Sample section.




78/88

5.3.2.7 Respond to KX_SMDR_CREATE event

OnSMDRCreate method is invoked when KX_SMDR_CREATEevent is received.

KX_SMDR_CREATEevent is sent to report that call accounting information is added into call account

information buffer. This event provides the call account ID that had been created.

The following is the code written forOnSMDRCreate method:

5.3.2.8 Respond to KX_SMDR_DELETE event

OnSMDRDelete method is invoked when KX_SMDR_DELETEevent is received.

KX_SMDR_DELETEevent is sent to report that call accounting information is deleted into call account

information buffer. This event provides the call account ID that had been deleted.

The following is the code written forOnSMDRDelete method:




79/88

5.3.3 SystemLine Class

This SystemLine class in FormSMDR.cs is responsible to store SYSTEM line information and performs call

accounting related operations.

The following is the outline ofSystemLine class.

5.3.3.1 SystemLine Constructor

SystemLine constructor initializes local members.

The following is the code written forSystemLine constructor:




80/88

5.3.3.2 SMDR ON

SMDRONmethod is invoked to enable call accounting information notification. Local memberbIsSMDRONis

set to true if API call succeeds.

The following is the code written forSMDRONmethod:

5.3.3.3 SMDR OFF

SMDROFFmethod is invoked to disable call accounting information notification. Local member

bIsSMDRONis set to false if API call succeeds.

The following is the code written forSMDROFFmethod:




81/88

5.3.3.4 Get SMDR

GetSMDRmethod is invoked for obtaining call account information for a specified call account ID. For details

ofV_CALLACCOUNTINFO, please refer to C# SDK Library API Reference Manual.

The following is the code written forGetSMDRmethod:




82/88

6 Frequently Asked Questions

This section lists frequently asked questions (and answers) about TSP setting and C# SDK library.

6.1 General TSP Setting

6.1.1 How to configure multiple PBX?

Please refer to Panasonic 3rd Party TSP Installation Manual for multiple PBX configurations.

6.1.2 How to know the CTI port of a PBX?

You can check the port setting using PC Maintenance Console under [1-1] Slot Card Property IPCMPR

Port Number tab. For details, please refer to the PC Programming Manual.

6.1.3 How to verify TSP PBX connection?

Panasonic KX-TDA TSP Monitor is a tool used to verify connection with PBX for each TSP instance. To start

this tool open Start Menu Program Panasonic KX-TDA TSP Connection Monitor.

PBX combo box is used to select an interested instance to verify connection.Connection may be:

Now Connection TSP instance is initializing connection with PBX.

Connected TSP instance is connected with PBX. It is possible to control/monitor with TAPI application(s).

Disconnected TSP instance is not communicating with PBX.

Not Registered with TAPI TSP instance is not registered in TAPI (Telephony System).


6.1.3 How to verify TSP PBX connection?


83/88

6.1.4 How to generate KX_REINIT and KX_RETRIEVE event?

KX_REINITand KX_RETRIEVEevent is generated only when Send KX_REINIT and KX_RETRIEVE check

box in configuration GUI is checked and TSP works in Standard Mode.

You may use the provided shortcut under TSP Installed Path MultiPBX Configuration.

If TSP loses connection with PBX, KX_REINITevent is sent and TSP will try to recover the connection. TSP

may fail recovery in some case (e.g. When PBX setting changed between KX_REINITand KX_RETRIEVE.

etc). Call event is not notified while TSP sends KX_REINITevent.


6.1.4 How to generate KX_REINIT and KX_RETRIEVE event?


84/88

6.2 C# SDK Information

6.2.1 What is the C# SDK library?The C# SDK library is a C# class library (wrapper on TAPI) which provides simpler interfaces for third party

developers to develop software for Panasonic PBX.

6.2.2 Can C# SDK library work with 1st Party TSP?

No. C# SDK library only work with Panasonic 3rd Party TSP.

6.2.3 How do I obtain an activation key for a Third Party CTI

(KX-NCS3930)?

Please contact Panasonic Sales Company.

6.2.4 How do I install an activation key for a Third Party CTI

(KX-NCS3930)?

Please contact Panasonic Sales Company.

6.2.5 How do I find the IP address for the connected PBX?The IP address for the connected PBX is obtainable using GetPBXInfo method for any opened line. IP address

is provided by V_PBXINFO.strIPAddress.

6.2.6 How do I identify a PBX?

A PBX can be identified by an IP address and PBX Name. The mentioned information is provided by

V_PBXINFO.strIPAddress and V_PBXINFO.strName.

Note

V_PBXINFO.strName is empty by default. User needs to assign PBX name by using PC Maintenance

Console (2. System 2.9 System Options Option 6(CTI) PBX Name) in order to get value for this

structure.

6.2.7 How do I find a call ID of a call?

The call ID for an incoming call can be obtained by KX_APPNEWCALL event. Call ID for an outgoing call is

returned from MakeCallAPI.


6.2.7 How do I find a call ID of a call?


85/88

6.2.8 How do I find the name of a line?

The name of a line is provided in a V_LINEINFO structure. User can obtain line information including the name

of a line using a GetLineInfo method by passing in lineID of the specific opened line as parameter.

V_LINEINFO.strExtName is only available for an opened line only. V_LINEINFO.strExtName is available for

extension, SVM, Sensor, Group and CO lines only.

For details ofV_LINEINFO structure, please refer to C# SDK Library API Reference Manual.

6.2.9 How do I find the dialable address for destination to be

dialed?

V_LINEINFO.strExtNumberprovides the dialable address for the line.

For details ofV_LINEINFO structure, please refer to C# SDK Library API Reference Manual.

6.2.10 How do I find the voice mail group number in order to use

SetTwoWayRecording?

For voice mail group number setting, please refer to your PBXs PC Programming Manual.

6.2.11 Why does my application not receive any events from SDK?

A possible cause is KXMessageEvent is not subscribed.

6.2.12 Can I initialize SDK more than one time in my application?No. You can only initialize one C# SDK library in an application.

6.2.13 Do I need to shutdown SDK when my application exits?

It is always recommended to shutdown the C# SDK library and unsubscribe KXMessageEventbefore exiting

the application. This is to free and release the memory which is no longer in use.


6.2.13 Do I need to shutdown SDK when my application exits?


86/88

6.2.14 How do I know which PBX is returning errors during SDK

initialization?

You have to subscribe KXMessageEventbefore initializing SDK. Any PBX connection error is notified throughthis event.

KX_LICENSE_ERRORevent which contains PBX information (e.g. PBX IP address and PBX Name) issent for PBX that does not have activation key (KX-NCS3930).

KX_INIT_ERRORevent with provider name of PBX is sent if C# SDK library failed during initialization. Youcan trace the PBX information using the following steps.

1. Go to TSP Installed Path MultiPBX Configuration.2. Select the provider name of PBX provided in KX_INIT_ERRORfrom TSP Instance list and click

the Configure button.

3. Select Link Parameters to trace the IP address of the PBX which failed during initialization.

6.2.15 What are those APIs which need to execute on an openedline?

Basically all APIs which required LineID orSystemLineID as a parameter need an opened line except

LineOpen and GetLineInfo.

6.2.16 Why I did not receive any notification in an SMDR related

event afterSetSMDROn?

Basically afterSetSMDROn, SMDR related event is generated for SYSTEM line whenever a CO call ended.

If you did not receive an SMDR related event, this might be because the SYSTEM line has been closed.

6.2.17 Can I install more than one instance of C# SDK in the same

PC?

Yes. The installer only performs extraction of C# SDK files on a selected folder.

6.2.18 How can I uninstall C# SDK?

No uninstallation is needed for C# SDK. You may delete the files if it is not in use.


6.2.18 How can I uninstall C# SDK?


87/88

7 C# SDK Error Troubleshooting

This section lists possible causes for C# SDK errors and solutions.Error Possible Cause Solution

KX_NOLINE No Panasonic line is available. 1. Proper connection betweenTSP and PBX

2. Activation key for Third PartyCTI is installed on PBX.

KX_NOPROVIDER No Panasonic 3rd Party TSP is

registered to TAPI.

Register Panasonic 3rd Party

TSP with TAPI.

KX_SDKNOTINIT C# SDK library is not initialized. Initialize C# SDK library.

KX_FAILEDREINIT C# SDK library had been

initialized.1. Reinitialization of C# SDK

library is forbidden.

2. If reinitialize is needed,shutdown C# SDK library

before reinitializing.

KX_REQUESTTIMEOUT PBX is in heavy traffic and

failed to respond within time

limit for the specified API

execution.

Retry API execution.

KX_REINIT 1. LAN connectiondisconnected.

2. Problem on Telephonyservice

3. Heavy traffic for PBX

Restart windows telephony

service.

KX_INVALLINEID 1. Specified line is notopened.

2. Line ID is not valid.

1. Check if specific API needsan opened line.

2. Make sure Line ID is valid.

KX_INVALCALLSTATE The call is not in a valid state for

requested operation.

Ensure the call is in required

state before calling the API.

KX_INVALPARAM Some parameter is out of

bounds or not valid for the

specific API.

Ensure the parameter is valid

and within the range.

KX_NOTOWNER C# SDK library is not owner ofthe specified call.

Ensure no other TAPIapplication is running on the

same PC.

KX_INUSE Another TAPI application had

monitored the line.

Ensure no other TAPI

application is running on the

same PC.



88/88

C SDK Developers Guide

Documents

Transcript of C SDK Developers Guide