model no. kx-ncs6100

C# SDK Developer’s GuideC# 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.

Purpose and ScopeThe purpose of this document is to guide software developers who are interested in using the API interfaceswhich are provided by C# SDK version 1.1. The scope of the document is to describe how a developer will usethe 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 Developer’s Guide

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

2 Introduction to C# SDK ............................................................................73 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 ......................................................................................................93.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 .......................................................................................................................164.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 Information ..............................................................................................................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 .......................................................................................................214.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 Developer’s Guide 3

Table of Contents

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 ........................................................................................................355.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 ............................................................................455.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 ......................................................................................................................545.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 ............................................................645.2.2.8 Respond to Keypad Button Clicked .............................................................................645.2.3 ExtensionLine Class .......................................................................................................65


Table of Contents

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 .........................................................765.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? .....................................................................................826.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? ....................................856.2.10 How do I find the voice mail group number in order to use

SetTwoWayRecording? ..................................................................................................856.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

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

2 Introduction to C# SDKC# 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 library

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


3 Installing C# SDK

3.1 System Requirements

3.1.1 Required Operating SystemPanasonic 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

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.

NoteKX-TDA100/200/600 are not supported.

3.2.2 TCP/IP SettingBefore 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

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

NoteIf another installation is already running, the following dialog is displayed and the installation processis aborted.

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


3.3 Installing C# SDK Library

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.



The default installation path is the setup file location. Click “Change” and then select desired installationpath from the following dialog.

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



6. Click “Finish” to complete the installation.



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

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 validationfailed during initialization. User application which is interested in receiving initialization error event needs tosubscribe to C# SDK event before calling Initialize method.

4.3.2 ShutdownTo shutdown the C# SDK library:


4.3.2 Shutdown

4.4 Monitoring Line Device

4.4.1 LineOpenLineOpen is used to monitor a line device.

4.4.2 LineCloseLineClose is used to stop monitoring a line device.


4.4.2 LineClose

4.5 Information Gathering

4.5.1 PBX InformationGetPBXInfo is used to get PBX information for an opened line device.For details of V_PBXINFO, please refer to C# SDK Library API Reference Manual.

4.5.2 Line Information

4.5.2.1 GetLineInfoListGetLineInfoList 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 ofV_LINEINFO, please refer to C# SDK Library API Reference Manual.



4.5.2.2 GetLineInfoGetLineInfo is used to get line information for a specified line in the system.This method is used to update line information. For details of V_LINEINFO, please refer to C# SDK LibraryAPI Reference Manual.

4.5.2.3 GetLineStatusGetLineStatus 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 orKX_OUS depending on current status of the line. For non-monitored line, C# SDK library returnsKX_UNKNOWN.



4.5.3 Call InformationTo get current call information of a call, GetCallInfo method is used.GetCallInfo returns a V_CALLINFO structure containing requested call information. For details ofV_CALLINFO, please refer to C# SDK Library API Reference Manual.


4.5.3 Call Information

4.6 Basic Call Control

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

4.6.2 Drop CallDropCall is used to drop a specified call. For called party, the call state must be connected otherwiseKX_INVALCALLSTATE error is returned.


4.6.2 Drop Call

4.6.3 Make CallMakeCall is used to place a call on a specified line to a destination address as specified.

4.6.4 Two Way RecordingSetTwoWayRecording is used to record a specified connected conversation into the requesting device’smailbox. This method is not available for a SIP type of extension. Voice mail setting is required to use thisfeature.


4.6.4 Two Way Recording

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 OnSetSMDROn is used to enable call accounting information. After starting SMDR on, KX_SMDR_CREATEevent is generated for SYSTEM line whenever a CO call ends.

4.7.2 Set SMDR OffSetSMDROff is used to disable call accounting information. After starting SMDR off, application will not receivean SMDR event.


4.7.2 Set SMDR Off

4.7.3 Get SMDRGetSMDR is used to get a specified call accounting information. This method returns call account informationof type V_CALLACCOUNTINFO. For details of V_CALLACCOUNTINFO, please refer to C# SDK Library APIReference Manual.


4.7.3 Get SMDR

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 StatusSetRingerStatus is used to ring a specified extension telephone using a specified ring mode.For details of E_RINGMODE, please refer to C# SDK Library API Reference Manual.


4.8.2 Set Ringer Status

4.8.3 Set DisplaySetDisplay is used to set specified text to a telephone display. This method supports PT (DPT and IP-PT) andPS extension lines only.

4.8.4 Clear DisplayClearDisplay is used to clear all text on the telephone display. This method supports PT (DPT and IP-PT) andPS extension lines only.


4.8.4 Clear Display

4.8.5 Terminate DisplayTerminateDisplay is used to terminate the control for telephone display. This method supports PT (DPT andIP-PT) and PS extension lines only.


4.8.5 Terminate Display

4.9 C# SDK Events HandlingC# SDK library uses events to notify user applications regarding change of line or call state, call informationand PBX setting or connection. User applications that are interested in C# SDK events needs to subscribeKXMessageEvent.


4.9 C# SDK Events Handling

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

4.9.1 Call Control Events

4.9.1.1 KX_APPNEWCALLKX_APPNEWCALL is sent when a new call ID is created.



4.9.1.2 KX_CALLSTATEKX_CALLSTATE is sent when the state of the specified call has changed.For details of E_LINECALLSTATE, please refer to C# SDK Library API Reference Manual.

4.9.1.3 KX_CALLINFOKX_CALLINFO is sent when call information about the specified call has changed.For details of V_EVENTCALLINFO, please refer to C# SDK Library API Reference Manual.



4.9.2 Device State Events

4.9.2.1 KX_DEVSTATEKX_DEVSTATE is sent when the state of a specified line device has changed.For details of E_LINEDEVSTATE, please refer to C# SDK Library API Reference Manual.


4.9.2 Device State Events

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 informationbuffers.

4.9.3.2 KX_SMDR_DELETEKX_SMDR_DELETE is sent to report that call accounting information is deleted from call account informationbuffers.


4.9.3 SMDR Events

4.9.4 PBX Setting and Connection Events

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

4.9.4.2 KX_RETRIEVEKX_RETRIEVE is sent when connection between PBX and C# SDK Library has been recovered after aconnection error occurred.



4.9.4.3 KX_RECONFIGKX_RECONFIG is sent when the PBX setting is changed.



4.9.5 Initialization Error Events

4.9.5.1 KX_INIT_ERRORKX_INIT_ERROR is sent when an initialization error occurs.

4.9.5.2 KX_LICENSE_ERRORKX_LICENSE_ERROR is sent when PBX does not contain an activation key (KX-NCS3930).


4.9.5 Initialization Error Events

5 C# SDK Sample ProgramC# 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 controlsample is able to monitor a line, make an outgoing call, drop a call, answer an incoming call and set two-wayrecording 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

5.1.1 Test ProceduresThe 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 the

monitored 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.


5.1.1 Test Procedures

5.1.2 FormCallControl ClassThis FormCallControl class in CallControlForm.cs responds to button clicks, C# SDK events and updates userinterface. FormCallControl constructor is responsible to initialize C# SDK and register to SDK events.

The following is the outline of FormCallControl class.


5.1.2 FormCallControl Class

5.1.2.1 FormCallControl ConstructorFormCallControl constructor initialize C# SDK library once the application is started. C# SDK library usesevents to facilitate communication with a user program. An event is sent to a user application during initializationif there is any occurrence of an activation key validation error. User applications that are interested in receivingan 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 linesand line information.

When this application starts, FormCallControl will initialize call and line information usingClearCallInformation and ClearLineInformation methods. MonitorLine is initialized as a Line object. Line is a



class defined to handle line related information and line functions. Details for this class will be discussed laterin this document. KXMessageEvent is subscribed, followed by C# SDK library initialization. GetLineInfoList iscalled after initialization to get all available lines for the system.

In case of initialization failed or no PBX is available, KX_NOLINE message is returned.The following error message is shown and call control sample application is terminated.

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



5.1.2.3 Respond to Open Button ClickedMethod btnMonitor_Click is registered as the event handling method for a click event of Open button.When “Open” button is clicked, btnMonitor_Click will open the currently selected line, clear call informationand update line information. If an application is monitoring a line, this monitored line will be closed and thecurrently 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 ClickedWhen “Answer Call” button is clicked and if a call exists, AnswerCall method in Line class will be invoked.Value for CallID indicates the existence of a call. CallID is set to 0 if no call exists.

The following is the code written for btnAnswerCall_Click, the event handling method for click event of “AnswerCall” button:



5.1.2.5 Respond to Drop Call Button ClickedDropCall method in Line class will be invoked if a call exists when “Drop Call” button is clicked. CallID is setto 0 if no call exists and no action will be performed if drop call button is clicked.

The following is the code written for btnDropCall_Click, the event handling method for click event of “DropCall” button:

5.1.2.6 Respond to Make Call Button ClickedMakeCall method in Line class is invoked when “Make Call” button is clicked. CallID is updated onceMakeCall successful.

The following is the code written for btnMakeCall_Click method:



5.1.2.7 Respond to Two-Way Recording Button ClickedMethod btnTwoWayRecord_Click is registered as the event handling method for click event of the “Two-WayRecording” button. When the “Two-Way Recording” button is clicked, TwoWayRecording method in Lineclass will be invoked if call exists and voice mail number is entered.

The following is the code written for btnTwoWayRecord_Click method:



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

The following is the code written for OnKxRespond method:



5.1.2.9 Respond to KX_APPNEWCALL eventOnNewCallEvent method 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 for OnNewCallEvent method:

5.1.2.10 Respond to KX_CALLSTATE eventKX_APPNEWCALL event is always followed by a KX_CALLSTATE event which indicates the initial state ofthe call. OnCallStateEvent method is invoked when KX_CALLSTATE event is received. KX_CALLSTATEevent is sent when status of a call has changed.

The following is the code written for OnCallStateEvent method:



5.1.2.11 Respond to KX_CALLINFO eventOnCallInformationEvent 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 informationstructure, V_EVENTCALLINFO. For detailed information about V_EVENTCALLINFO, please refer to C#SDK Library API Reference Manual.

The following is the code written for OnCallInformationEvent method:

5.1.2.12 Respond to KX_DEVSTATE eventOnDevState method is invoked when KX_DEVSTATE event is received. KX_DEVSTATE event is sent whenstate of a monitored line has changed. In case application received KX_REINIT state, Windows TelephonyService should be restarted. This scenario occurs when TSP fails to retrieve broken connection.

The following is the code written for OnDevState method:



The following figure shows the information dialog for KX_DEVSTATE event:

5.1.2.13 Respond to KX_INIT_ERROR eventKX_INIT_ERROR is 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 for OnInitError method:

The following figure shows the error dialog for KX_INIT_ERROR event:



5.1.2.14 Respond to KX_LICENSE_ERROR eventKX_LICENSE_ERROR is sent if specified PBX does not contain activation key (KX-NCS3930). The PBXinformation for the PBX which failed is sent along with this event. For detailed information aboutV_PBXINFO, please refer to C# SDK Library API Reference Manual.

The following is the code written for OnLicenseError method:

The following figure shows the error dialog for KX_LICENSE_ERROR event:



5.1.2.15 Respond to KX_RECONFIG eventKX_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 for OnReconfig method:

5.1.2.16 Respond to KX_REINIT eventKX_REINIT is sent if specified PBX connection error occurred. TSP tries to retrieve the connection for severaltimes. All APIs are unavailable during connection retrieve process. This message is sent to all monitored lines.

The following is the code written for OnReinit method:

The following figure shows the information dialog for KX_REINIT event:



5.1.2.17 Respond to KX_RETRIEVE eventKX_RETRIEVE is sent when connection between PBX and the C# SDK library has been recovered byconnection recovery process after a connection error occurred. This message is sent to all monitored lines.

The following is the code written for OnRetrieve method:

The following figure shows the information dialog for KX_RETRIEVE event:



5.1.3 Line ClassThis Line class in CallControlForm.cs is responsible for storing line information and performing line relatedoperations.

The following is the outline of Line class.


5.1.3 Line Class

5.1.3.1 Line ConstructorLine constructor initialized local members.

The following is the code written for Line constructor:

5.1.3.2 OpenOpen method is invoked when the “Open” button is clicked. This method responsible to call LineOpen to startmonitors a line device. Local member bIsLineOpen is set to true if LineOpen succeeds and line information isupdated.

The following is the code written for Open method:


5.1.3 Line Class

5.1.3.3 CloseClose method is invoked when the “Open” button is clicked. Method btnMonitor_Click will check whether anyline is opened before opening a line. If call control sample is currently opening a line, Close method is invokedto close the line.

The following is the code written for Close method:

5.1.3.4 Make CallMakeCall method is invoked when the “Make Call” button is clicked. Call ID for the newly placed call is returned.

The following is the code written for MakeCall method:


5.1.3 Line Class

5.1.3.5 Drop CallDropCall method is invoked when the “Drop Call” button is clicked. This method is called only if call exists formonitored line.

The following is the code written for DropCall method:

5.1.3.6 Answer CallAnswerCall method is invoked when the “Answer Call” button is clicked. This method is called only if call existsfor monitored line.

The following is the code written for AnswerCall method:


5.1.3 Line Class

5.1.3.7 Set Two Way RecordingTwoWayRecording method is invoked when the “Two-Way Recording” button is clicked. This method is calledonly if call exists for monitored line and voice mail number is entered.

The following is the code written for TwoWayRecording method:


5.1.3 Line Class

5.2 Phone Control SampleThis sample demonstrates how to use the C# SDK library to develop simple phone control applications. Aphone 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 iseligible 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

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


5.2 Phone Control Sample

5.2.1 Test ProceduresThe 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 case

the user wants to switch to another extension line, select desired extension line and click the “Open” buttonto 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 set

phone 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.



5.2.2 FormPhoneControl ClassThis FormPhoneControl class in FormPhoneControl.cs used to respond to user interface action and C#SDK events. FormCallControl constructor is responsible to initialize the C# SDK library and register to C#SDK events.

The following is the outline of FormPhoneControl class.


5.2.2 FormPhoneControl Class

5.2.2.1 FormPhoneControl ConstructorFormPhoneControl constructor initialize the C# SDK library once the application is started. C# SDK libraryuses events to facilitate communication with a user program. An event is sent to a user application duringinitialization if there is any occurrence of an activation key validation error. User applications that are interestedin receiving an initialization error event are required to subscribe to a C# SDK event before calling initialize.

The following is the code written for FormPhoneControl constructor to subscribe to a C# SDK event, initializeC# SDK library, and get list of available extension lines and line information. First available extension line ismonitored when application is started.



When application start, MonitorLine member is initialized as an ExtensionLine object. ExtensionLine is a classdefined to handle line information and phone control functions. Details for this class will be discussed later inthis document.

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



5.2.2.3 Respond to Open Button ClickedWhen the “Open” button is clicked, btnMonitor_Click will check whether any other line is monitored. If anapplication 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 EventWhen the ring mode radio button is checked, FormPhoneControl will invoke ExtensionLine class SetRingermethod to ring the monitored line.

The following is the code written for RingMode_CheckedChanged method:



5.2.2.5 Respond to Set display Button ClickedWhen the “Set” button is clicked and if the row and column edit box have valid input, SetDisplay method inExtensionLine class will be called. User interface for FormPhoneControl is updated if SetDisplay is successfull.

The following is the code written for btnSetDisplay_Click method:

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 for btnClear_Click method:



5.2.2.7 Respond to Terminate Display Button ClickedWhen the “Terminate” button is clicked, control over phone display is stopped.

The following is the code written for btnTerminate_Click method:

5.2.2.8 Respond to Keypad Button ClickedKeypad is a customized user control according to physical phone keypad. When button for keypad is clicked,ButtonClick event is sent to FormPhoneControl. CtrlKeypad_ButtonClick used to respond to keypad buttonclick event.

The following is the code written for CtrlKeypad_ButtonClick method:



5.2.3 ExtensionLine ClassThis ExtensionLine class in FormPhoneControl.cs is responsible for storing line information and performingphone control related operations.

The following is the outline of ExtensionLine class.


5.2.3 ExtensionLine Class

5.2.3.1 ExtensionLine ConstructorExtensionLine constructor initializes local members.

The following is the code written for ExtensionLine constructor:

5.2.3.2 OpenOpen method is invoked when the “Open” button is clicked. This method will call LineOpen to start monitoringa line device. Local member bIsLineOpen is set to true if LineOpen succeeded.

The following is the code written for Open method:



5.2.3.3 CloseClose method is invoked when the “Open” button is clicked. Method btnMonitor_Click will check whether anyline is opened before opening a line. If phone control sample is currently opening a line, Close method isinvoked to close the line.

The following is the code written for Close method:

5.2.3.4 Button PressButtonPress method is invoked when a KeyPad button is clicked.

The following is the code written for ButtonPress method:



5.2.3.5 Set RingerRingMode_CheckedChanged method invokes SetRinger when ring mode radio button is checked.

The following is the code written for SetRinger method:

5.2.3.6 Set DisplaySetDisplay method is invoked as respond for the “Set” button click event.

The following is the code written for SetDisplay method:



5.2.3.7 Clear DisplayClearDisplay method is invoked as respond for “Clear” button click event.

The following is the code written for ClearDisplay method:

5.2.3.8 Terminate DisplayTerminateDisplay method is invoked as a response for the “Terminate” button click event.

The following is the code written for TerminateDisplay method:



5.3 SMDR SampleThis sample demonstrates how to use the C# SDK library to develop simple call accounting applications. TheSMDR 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 anSMDR 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 defaultduring 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

NoteDescription for KX_SMDR_CREATE and KX_SMDR_DELETE will be discussed in this section.Description for others event handling, please refer to the Call Control Sample section.


5.3 SMDR Sample

5.3.1 Test ProceduresThe 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.

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



5.3.2 FormSMDR ClassThis FormSMDR class in FormSMDR.cs is used to respond to user interface action and C# SDK events.FormSMDR constructor is responsible for initializing the C# SDK library and registering to C# SDK events.

The following is the outline of FormSMDR class.


5.3.2 FormSMDR Class

5.3.2.1 FormSMDR ConstructorFormSMDR constructor initializes the C# SDK library once the application is started. An event is sent to a userapplication during initialization if there is any occurrence of activation key validation error. User applicationsthat are interested in initialization error events are required to subscribe to C# SDK event before calling initialize.

The following is the code written for FormSMDR constructor 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 usedto update user interface with available SYSTEM lines only.



5.3.2.2 Shutdown When Form ClosingWhen 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 ClickedWhen the “ON” button is clicked, btnSMDRON_Click will invoke an SMDRON method in SystemLine Class toenable call accounting information.

The following is the code written for btnSMDRON_Click method:



5.3.2.4 Respond to SMDR OFF Button ClickedWhen the “OFF” button is clicked, btnSMDROFF_Click will invoke an SMDROFF method in SystemLine Classto disable call accounting information.

The following is the code written for btnSMDROFF_Click method:

5.3.2.5 Respond to Button Get SMDR Information ClickWhen the “Get Info” button is clicked, btnGetSMDR_Click will check whether call accounting ID is valid. If callaccounting ID is valid, GetSMDR in SystemLine class is invoked and account information is updated.

The following is the code written for btnGetSMDR_Click method:



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

The following is the code written for OnKXLinesRespond method:

Description for KX_INIT_ERROR and KX_LICENSE_ERROR event handling, please refer to Call ControlSample section.



5.3.2.7 Respond to KX_SMDR_CREATE eventOnSMDRCreate method is invoked when KX_SMDR_CREATE event is received.KX_SMDR_CREATE event is sent to report that call accounting information is added into call accountinformation buffer. This event provides the call account ID that had been created.

The following is the code written for OnSMDRCreate method:

5.3.2.8 Respond to KX_SMDR_DELETE eventOnSMDRDelete method is invoked when KX_SMDR_DELETE event is received.KX_SMDR_DELETE event is sent to report that call accounting information is deleted into call accountinformation buffer. This event provides the call account ID that had been deleted.

The following is the code written for OnSMDRDelete method:



5.3.3 SystemLine ClassThis SystemLine class in FormSMDR.cs is responsible to store SYSTEM line information and performs callaccounting related operations.

The following is the outline of SystemLine class.

5.3.3.1 SystemLine ConstructorSystemLine constructor initializes local members.

The following is the code written for SystemLine constructor:


5.3.3 SystemLine Class

5.3.3.2 SMDR ONSMDRON method is invoked to enable call accounting information notification. Local member bIsSMDRON isset to true if API call succeeds.

The following is the code written for SMDRON method:

5.3.3.3 SMDR OFFSMDROFF method is invoked to disable call accounting information notification. Local memberbIsSMDRON is set to false if API call succeeds.

The following is the code written for SMDROFF method:



5.3.3.4 Get SMDRGetSMDR method is invoked for obtaining call account information for a specified call account ID. For detailsof V_CALLACCOUNTINFO, please refer to C# SDK Library API Reference Manual.

The following is the code written for GetSMDR method:



6 Frequently Asked QuestionsThis 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 startthis 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?

6.1.4 How to generate KX_REINIT and KX_RETRIEVE event?KX_REINIT and KX_RETRIEVE event is generated only when “Send KX_REINIT and KX_RETRIEVE” checkbox 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_REINIT event is sent and TSP will try to recover the connection. TSPmay fail recovery in some case (e.g. When PBX setting changed between KX_REINIT and KX_RETRIEVE.etc). Call event is not notified while TSP sends KX_REINIT event.


6.1.4 How to generate KX_REINIT and KX_RETRIEVE event?

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 partydevelopers 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 addressis 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 byV_PBXINFO.strIPAddress and V_PBXINFO.strName.

NoteV_PBXINFO.strName is empty by default. User needs to assign PBX name by using PC MaintenanceConsole (2. System – 2.9 System Options – Option 6(CTI) – PBX Name) in order to get value for thisstructure.

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 isreturned from MakeCall API.


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

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 nameof 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 forextension, SVM, Sensor, Group and CO lines only.For details of V_LINEINFO structure, please refer to C# SDK Library API Reference Manual.

6.2.9 How do I find the dialable address for destination to bedialed?

V_LINEINFO.strExtNumber provides the dialable address for the line.For details of V_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 useSetTwoWayRecording?

For voice mail group number setting, please refer to your PBX’s 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 KXMessageEvent before exitingthe 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?

6.2.14 How do I know which PBX is returning errors during SDKinitialization?

You have to subscribe KXMessageEvent before initializing SDK. Any PBX connection error is notified throughthis event.• KX_LICENSE_ERROR event which contains PBX information (e.g. PBX IP address and PBX Name) is

sent for PBX that does not have activation key (KX-NCS3930).• KX_INIT_ERROR event with provider name of PBX is sent if C# SDK library failed during initialization. You

can 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_ERROR from “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 or SystemLineID as a parameter need an opened line exceptLineOpen and GetLineInfo.

6.2.16 Why I did not receive any notification in an SMDR relatedevent after SetSMDROn?

Basically after SetSMDROn, 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 samePC?

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?

7 C# SDK Error TroubleshootingThis 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 isregistered to TAPI.

Register Panasonic 3rd PartyTSP with TAPI.

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

KX_FAILEDREINIT C# SDK library had beeninitialized.

1. Reinitialization of C# SDKlibrary is forbidden.

2. If reinitialize is needed,shutdown C# SDK librarybefore reinitializing.

KX_REQUESTTIMEOUT PBX is in heavy traffic andfailed to respond within timelimit for the specified APIexecution.

Retry API execution.

KX_REINIT 1. LAN connectiondisconnected.

2. Problem on Telephonyservice

3. Heavy traffic for PBX

Restart windows telephonyservice.

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 forrequested operation.

Ensure the call is in requiredstate before calling the API.

KX_INVALPARAM Some parameter is out ofbounds or not valid for thespecific API.

Ensure the parameter is validand within the range.

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

Ensure no other TAPIapplication is running on thesame PC.

KX_INUSE Another TAPI application hadmonitored the line.

Ensure no other TAPIapplication is running on thesame PC.


Copyright:This material is copyrighted by Panasonic System Networks Co., Ltd., and may be reproduced for internal useonly. All other reproduction, in whole or in part, is prohibited without the written consent of Panasonic SystemNetworks Co., Ltd.

© Panasonic System Networks Co., Ltd. 2010

PNQX2715YA KK1109MH1010

model no. kx-ncs6100

Documents