C SDK Developers Guide

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.
Purpose and Scope

The 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.
Table of Contents
Table of Contents
1 Preface ......................................................................................................6
1.1 1.2 Reference ...........................................................................................................................6 Definitions, Acronyms, and Terminology .......................................................................6
2 Introduction to C# SDK ............................................................................7 3 Installing C# SDK .....................................................................................8

3.1 3.1.1 3.1.2 3.1.3 3.2 3.2.1 3.2.2 3.2.3 3.3 4.1 4.2 4.3 4.3.1 4.3.2 4.4 4.4.1 4.4.2 4.5 4.5.1 4.5.2 4.5.2.1 4.5.2.2 4.5.2.3 4.5.3 4.6 4.6.1 4.6.2 4.6.3 4.6.4 4.7 4.7.1 4.7.2 4.7.3 4.8 4.8.1 4.8.2 4.8.3 4.8.4 4.8.5 4.9 4.9.1 4.9.1.1 4.9.1.2 System Requirements ......................................................................................................8 Required Operating System .............................................................................................8 Minimum Hardware Requirements ...................................................................................8 Software Requirements ....................................................................................................8 PBX Settings ......................................................................................................................9 Supported PBX Types ......................................................................................................9 TCP/IP Setting ..................................................................................................................9 Activation Key ...................................................................................................................9 Installing C# SDK Library ...............................................................................................10 Before Calling C# SDK API .............................................................................................14 Using C# SDK Namespace .............................................................................................14 Starts and Ends C# SDK Library ...................................................................................15 Initialize ..........................................................................................................................15 Shutdown .......................................................................................................................15 Monitoring Line Device ...................................................................................................16 LineOpen ........................................................................................................................16 LineClose .......................................................................................................................16 Information Gathering ....................................................................................................17 PBX Information .............................................................................................................17 Line Information ..............................................................................................................17 GetLineInfoList ............................................................................................................17 GetLineInfo ..................................................................................................................18 GetLineStatus ..............................................................................................................18 Call Information ..............................................................................................................19 Basic Call Control ...........................................................................................................20 Answer Call ....................................................................................................................20 Drop Call ........................................................................................................................20 Make Call .......................................................................................................................21 Two Way Recording .......................................................................................................21 Call Accounting Control .................................................................................................22 Set SMDR On .................................................................................................................22 Set SMDR Off .................................................................................................................22 Get SMDR ......................................................................................................................23 Physical Device Control .................................................................................................24 Button Press ...................................................................................................................24 Set Ringer Status ...........................................................................................................24 Set Display .....................................................................................................................25 Clear Display ..................................................................................................................25 Terminate Display ..........................................................................................................26 C# SDK Events Handling ................................................................................................27 Call Control Events .........................................................................................................28 KX_APPNEWCALL .....................................................................................................28 KX_CALLSTATE .........................................................................................................29
4 C# SDK Programming Guide ................................................................14
Table of Contents
4.9.1.3 4.9.2 4.9.2.1 4.9.3 4.9.3.1 4.9.3.2 4.9.4 4.9.4.1 4.9.4.2 4.9.4.3 4.9.5 4.9.5.1 4.9.5.2
KX_CALLINFO ............................................................................................................29 Device State Events .......................................................................................................30 KX_DEVSTATE ...........................................................................................................30 SMDR Events .................................................................................................................31 KX_SMDR_CREATE ...................................................................................................31 KX_SMDR_DELETE ...................................................................................................31 PBX Setting and Connection Events ..............................................................................32 KX_REINIT ..................................................................................................................32 KX_RETRIEVE ............................................................................................................32 KX_RECONFIG ...........................................................................................................33 Initialization Error Events ................................................................................................34 KX_INIT_ERROR ........................................................................................................34 KX_LICENSE_ERROR ...............................................................................................34
5 C# SDK Sample Program ......................................................................35

5.1 Call Control Sample ........................................................................................................35 5.1.1 Test Procedures .............................................................................................................36 5.1.2 FormCallControl Class ...................................................................................................37 5.1.2.1 FormCallControl Constructor .......................................................................................39 5.1.2.2 Shutdown When Form Closing ....................................................................................40 5.1.2.3 Respond to Open Button Clicked ................................................................................41 5.1.2.4 Respond to Answer Call Button Clicked ......................................................................41 5.1.2.5 Respond to Drop Call Button Clicked ..........................................................................42 5.1.2.6 Respond to Make Call Button Clicked .........................................................................42 5.1.2.7 Respond to Two-Way Recording Button Clicked ........................................................43 5.1.2.8 C# SDK Events ............................................................................................................44 5.1.2.9 Respond to KX_APPNEWCALL event ........................................................................45 5.1.2.10 Respond to KX_CALLSTATE event ............................................................................45 5.1.2.11 Respond to KX_CALLINFO event ...............................................................................46 5.1.2.12 Respond to KX_DEVSTATE event ..............................................................................46 5.1.2.13 Respond to KX_INIT_ERROR event ...........................................................................47 5.1.2.14 Respond to KX_LICENSE_ERROR event ..................................................................48 5.1.2.15 Respond to KX_RECONFIG event ..............................................................................49 5.1.2.16 Respond to KX_REINIT event .....................................................................................49 5.1.2.17 Respond to KX_RETRIEVE event ...............................................................................50 5.1.3 Line Class .......................................................................................................................51 5.1.3.1 Line Constructor ..........................................................................................................52 5.1.3.2 Open ............................................................................................................................52 5.1.3.3 Close ...........................................................................................................................53 5.1.3.4 Make Call .....................................................................................................................53 5.1.3.5 Drop Call ......................................................................................................................54 5.1.3.6 Answer Call .................................................................................................................54 5.1.3.7 Set Two Way Recording ..............................................................................................55 5.2 Phone Control Sample ....................................................................................................56 5.2.1 Test Procedures .............................................................................................................57 5.2.2 FormPhoneControl Class ...............................................................................................58 5.2.2.1 FormPhoneControl Constructor ...................................................................................60 5.2.2.2 Shutdown When Form Closing ....................................................................................61 5.2.2.3 Respond to Open Button Clicked ................................................................................62 5.2.2.4 Respond to Ring Mode Checked Changed Event .......................................................62 5.2.2.5 Respond to Set display Button Clicked .......................................................................63 5.2.2.6 Respond to Clear Display Button Clicked ....................................................................63 5.2.2.7 Respond to Terminate Display Button Clicked ............................................................64 5.2.2.8 Respond to Keypad Button Clicked .............................................................................64 5.2.3 ExtensionLine Class .......................................................................................................65
4 C# SDK Developers Guide
Table of Contents
5.2.3.1 ExtensionLine Constructor ..........................................................................................66 5.2.3.2 Open ............................................................................................................................66 5.2.3.3 Close ...........................................................................................................................67 5.2.3.4 Button Press ................................................................................................................67 5.2.3.5 Set Ringer ....................................................................................................................68 5.2.3.6 Set Display ..................................................................................................................68 5.2.3.7 Clear Display ...............................................................................................................69 5.2.3.8 Terminate Display ........................................................................................................69 5.3 SMDR Sample ..................................................................................................................70 5.3.1 Test Procedures .............................................................................................................71 5.3.2 FormSMDR Class ..........................................................................................................72 5.3.2.1 FormSMDR Constructor ..............................................................................................74 5.3.2.2 Shutdown When Form Closing ....................................................................................75 5.3.2.3 Respond to SMDR ON Button Clicked ........................................................................75 5.3.2.4 Respond to SMDR OFF Button Clicked ......................................................................76 5.3.2.5 Respond to Button Get SMDR Information Click .........................................................76 5.3.2.6 C# SDK Events ............................................................................................................77 5.3.2.7 Respond to KX_SMDR_CREATE event .....................................................................78 5.3.2.8 Respond to KX_SMDR_DELETE event ......................................................................78 5.3.3 SystemLine Class ...........................................................................................................79 5.3.3.1 SystemLine Constructor ..............................................................................................79 5.3.3.2 SMDR ON ....................................................................................................................80 5.3.3.3 SMDR OFF ..................................................................................................................80 5.3.3.4 Get SMDR ...................................................................................................................81
6 Frequently Asked Questions ................................................................82

6.1 6.1.1 6.1.2 6.1.3 6.1.4 6.2 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.2.6 6.2.7 6.2.8 6.2.9 6.2.10 6.2.11 6.2.12 6.2.13 6.2.14 6.2.15 6.2.16 6.2.17 6.2.18 General TSP Setting ........................................................................................................82 How to configure multiple PBX? .....................................................................................82 How to know the CTI port of a PBX? ..............................................................................82 How to verify TSP <-> PBX connection? ........................................................................82 How to generate KX_REINIT and KX_RETRIEVE event? .............................................83 C# SDK Information ........................................................................................................84 What is the C# SDK library? ...........................................................................................84 Can C# SDK library work with 1st Party TSP? ...............................................................84 How do I obtain an activation key for a Third Party CTI (KX-NCS3930)? ......................84 How do I install an activation key for a Third Party CTI (KX-NCS3930)? .......................84 How do I find the IP address for the connected PBX? ...................................................84 How do I identify a PBX? ................................................................................................84 How do I find a call ID of a call? .....................................................................................84 How do I find the name of a line? ...................................................................................85 How do I find the dialable address for destination to be dialed? ....................................85 How do I find the voice mail group number in order to use SetTwoWayRecording? ..................................................................................................85 Why does my application not receive any events from SDK? ........................................85 Can I initialize SDK more than one time in my application? ...........................................85 Do I need to shutdown SDK when my application exits? ...............................................85 How do I know which PBX is returning errors during SDK initialization? .......................86 What are those APIs which need to execute on an opened line? ..................................86 Why I did not receive any notification in an SMDR related event after SetSMDROn? .................................................................................................................86 Can I install more than one instance of C# SDK in the same PC? ................................86 How can I uninstall C# SDK? .........................................................................................86
7 C# SDK Error Troubleshooting .............................................................87
1.2 Definitions, Acronyms, and Terminology
1 Preface
1.1 Reference
1. C# SDK Library API Reference Manual 2. Panasonic KX-TDA TAPI Specification Version 3.3 3. TAPI reference from MSDN 2009
1.2 Definitions, Acronyms, and Terminology

SDK TSP DLL SMDR PS PT DPT Software Development Kit TAPI Service Provider Dynamic Link Library Station Message Detail Recording Portable Station Proprietary Telephone Digital Proprietary Telephone
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 provides a 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.
Windows PC User Application C# API C# SDK Library TAPI Windows Telephony Service Panasonic 3rd Party TSP
3rd Party CSTA
Panasonic PBX
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.1.3 Software Requirements
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.2.3 Activation Key
3.2 PBX Settings

3.2.1 Supported PBX Types
Supported 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 CTI port 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 Third Party CTI (KX-NCS3930)? and 6.2.4 How do I install an activation key for a Third Party CTI (KX-NCS3930)?
3.3 Installing C# SDK Library

1. 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.
10
3. Select I accept the terms of the license agreement and then click Next to continue installation after
reading 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.
11
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 previous
step.
12
6. Click Finish to complete the installation.
13
4.2 Using C# SDK Namespace
4 C# SDK Programming Guide

4.1 Before Calling C# SDK API
In 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 Namespace

C# SDK namespace must be added.
14
4.3.2 Shutdown
4.3 Starts and Ends C# SDK Library

4.3.1 Initialize
Initialize 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:
15
4.4.2 LineClose
4.4 Monitoring Line Device

4.4.1 LineOpen
LineOpen is used to monitor a line device.
4.4.2 LineClose
LineClose is used to stop monitoring a line device.
16
4.5.2 Line Information
4.5 Information Gathering

4.5.1 PBX Information
GetPBXInfo 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.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.
17
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 of V_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.
18
4.5.3 Call Information
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.
19
4.6.2 Drop Call
4.6 Basic Call Control

4.6.1 Answer Call
AnswerCall is used to answer a specified incoming call. The call state of the incoming call must be offering.
4.6.2 Drop Call

DropCall is used to drop a specified call. For called party, the call state must be connected otherwise KX_INVALCALLSTATE error is returned.
20
4.6.4 Two Way Recording
4.6.3 Make Call

MakeCall is 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.
21
4.7.2 Set SMDR Off
4.7 Call Accounting Control

Note All SYSTEM lines for PBX with activation key (KX-NCS3930) are monitored by default when Initialize method 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

SetSMDROff is used to disable call accounting information. After starting SMDR off, application will not receive an SMDR event.
22
4.7.3 Get SMDR
4.7.3 Get SMDR

GetSMDR is used to get a specified call accounting information. This method returns call account information of type V_CALLACCOUNTINFO. For details of V_CALLACCOUNTINFO, please refer to C# SDK Library API Reference Manual.
23
4.8.2 Set Ringer Status
4.8 Physical Device Control

4.8.1 Button Press
ButtonPress 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 of E_RINGMODE, please refer to C# SDK Library API Reference Manual.
24
4.8.4 Clear Display
4.8.3 Set Display

SetDisplay is 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

ClearDisplay is used to clear all text on the telephone display. This method supports PT (DPT and IP-PT) and PS extension lines only.
25
4.8.5 Terminate Display
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.
26
4.9 C# SDK Events Handling
4.9 C# SDK Events Handling

C# 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 subscribe KXMessageEvent.
27
4.9.1 Call Control Events
The following are the methods for handling each event according to categories.

4.9.1.1 KX_APPNEWCALL
KX_APPNEWCALL is sent when a new call ID is created.
28
4.9.1.2 KX_CALLSTATE
KX_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_CALLINFO
KX_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.
29
4.9.2 Device State Events
4.9.2 Device State Events

4.9.2.1 KX_DEVSTATE
KX_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.
30
4.9.3 SMDR Events
4.9.3 SMDR Events

4.9.3.1 KX_SMDR_CREATE
KX_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_DELETE is sent to report that call accounting information is deleted from call account information buffers.
31
4.9.4 PBX Setting and Connection Events

4.9.4.1 KX_REINIT
KX_REINIT is sent when any connection error between PBX and C# SDK Library has occurred.
4.9.4.2 KX_RETRIEVE
KX_RETRIEVE is sent when connection between PBX and C# SDK Library has been recovered after a connection error occurred.
32
4.9.4.3 KX_RECONFIG
KX_RECONFIG is sent when the PBX setting is changed.
33
4.9.5 Initialization Error Events
4.9.5 Initialization Error Events

4.9.5.1 KX_INIT_ERROR
KX_INIT_ERROR is sent when an initialization error occurs.
4.9.5.2 KX_LICENSE_ERROR
KX_LICENSE_ERROR is sent when PBX does not contain an activation key (KX-NCS3930).
34
5.1 Call Control Sample
5 C# SDK Sample Program

C# SDK includes three sample programs. The source code is located in the Sample Code folder. The executables 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 Sample

This 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
35
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 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.
36
5.1.2 FormCallControl Class

This FormCallControl class in CallControlForm.cs responds to button clicks, C# SDK events and updates user interface. FormCallControl constructor is responsible to initialize C# SDK and register to SDK events. The following is the outline of FormCallControl class.
37
38
5.1.2.1 FormCallControl Constructor

FormCallControl constructor 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, FormCallControl will initialize call and line information using ClearCallInformation and ClearLineInformation methods. MonitorLine is initialized as a Line object. Line is a
39
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_NOLINE message 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.
40
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_Click will 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, 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 Answer Call button:
41
5.1.2.5 Respond to Drop Call Button Clicked

DropCall method 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 for btnDropCall_Click, the event handling method for click event of Drop Call button:
5.1.2.6 Respond to Make Call Button Clicked

MakeCall method in Line class is invoked when Make Call button is clicked. CallID is updated once MakeCall successful. The following is the code written for btnMakeCall_Click method:
42
5.1.2.7 Respond to Two-Way Recording Button Clicked

Method btnTwoWayRecord_Click is registered as the event handling method for click event of the Two-Way Recording button. When the Two-Way Recording button is clicked, TwoWayRecording method in Line class will be invoked if call exists and voice mail number is entered. The following is the code written for btnTwoWayRecord_Click method:
43
5.1.2.8 C# SDK Events

OnKxRespond method is registered as event handling method for C# SDK events when an application starts. The following is the code written for OnKxRespond method:
44
5.1.2.9 Respond to KX_APPNEWCALL event

OnNewCallEvent 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 event

KX_APPNEWCALL event is always followed by a KX_CALLSTATE event which indicates the initial state of the call. OnCallStateEvent method is invoked when KX_CALLSTATE event is received. KX_CALLSTATE event is sent when status of a call has changed. The following is the code written for OnCallStateEvent method:
45
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 for OnCallInformationEvent method:
5.1.2.12 Respond to KX_DEVSTATE event

OnDevState method is invoked when KX_DEVSTATE event is received. KX_DEVSTATE event is sent when state of a monitored line has changed. In case application received KX_REINIT state, Windows Telephony Service should be restarted. This scenario occurs when TSP fails to retrieve broken connection. The following is the code written for OnDevState method:
46
The following figure shows the information dialog for KX_DEVSTATE event:
5.1.2.13 Respond to KX_INIT_ERROR event

KX_INIT_ERROR is sent when C# SDK library fails to LineOpen a SYSTEM line during initialization. The provider 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:
47
5.1.2.14 Respond to KX_LICENSE_ERROR event

KX_LICENSE_ERROR is 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 for OnLicenseError method:
The following figure shows the error dialog for KX_LICENSE_ERROR event:
48
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 for OnReconfig method:
5.1.2.16 Respond to KX_REINIT event

KX_REINIT is 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 for OnReinit method:
The following figure shows the information dialog for KX_REINIT event:
49
5.1.2.17 Respond to KX_RETRIEVE event

KX_RETRIEVE is 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 for OnRetrieve method:
The following figure shows the information dialog for KX_RETRIEVE event:
50
5.1.3 Line Class
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 of Line class.
51
5.1.3 Line Class
5.1.3.1 Line Constructor

Line constructor initialized local members. The following is the code written for Line constructor:
5.1.3.2 Open
Open method is invoked when the Open button is clicked. This method responsible to call LineOpen to start monitors a line device. Local member bIsLineOpen is set to true if LineOpen succeeds and line information is updated. The following is the code written for Open method:
52
5.1.3 Line Class
5.1.3.3 Close
Close method is invoked when the Open button is clicked. Method btnMonitor_Click will 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 for Close method:
5.1.3.4 Make Call

MakeCall 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:
53
5.1.3 Line Class
5.1.3.5 Drop Call

DropCall method 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 for DropCall method:
5.1.3.6 Answer Call

AnswerCall method 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 for AnswerCall method:
54
5.1.3 Line Class
5.1.3.7 Set Two Way Recording

TwoWayRecording method 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 for TwoWayRecording method:
55
5.2 Phone Control Sample
5.2 Phone Control Sample

This 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 simulate a 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.
56

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 case the 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 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.
57
5.2.2 FormPhoneControl Class

This 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.
58
59
5.2.2.1 FormPhoneControl Constructor

FormPhoneControl constructor 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 for FormPhoneControl constructor 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.
60
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 in this document.

When form is closing, phone control sample calls Shutdown method to end C# SDK library usage.
61
5.2.2.3 Respond to Open Button Clicked

When the Open button is clicked, btnMonitor_Click will 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, FormPhoneControl will invoke ExtensionLine class SetRinger method to ring the monitored line. The following is the code written for RingMode_CheckedChanged method:
62
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, SetDisplay method in ExtensionLine 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 Clicked

When the Clear button is clicked, the displayed message on phone LCD is cleared. The following is the code written for btnClear_Click method:
63
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 for btnTerminate_Click method:
5.2.2.8 Respond to Keypad Button Clicked

Keypad 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 button click event. The following is the code written for CtrlKeypad_ButtonClick method:
64
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 of ExtensionLine class.
65
5.2.3.1 ExtensionLine Constructor

ExtensionLine constructor initializes local members. The following is the code written for ExtensionLine 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 member bIsLineOpen is set to true if LineOpen succeeded. The following is the code written for Open method:
66
5.2.3.3 Close
Close method is invoked when the Open button is clicked. Method btnMonitor_Click will 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 for Close method:
5.2.3.4 Button Press

ButtonPress method is invoked when a KeyPad button is clicked. The following is the code written for ButtonPress method:
67
5.2.3.5 Set Ringer

RingMode_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 Display

SetDisplay method is invoked as respond for the Set button click event. The following is the code written for SetDisplay method:
68
5.2.3.7 Clear Display

ClearDisplay method is invoked as respond for Clear button click event. The following is the code written for ClearDisplay method:
5.2.3.8 Terminate Display

TerminateDisplay method is invoked as a response for the Terminate button click event. The following is the code written for TerminateDisplay method:
69
5.3 SMDR Sample
5.3 SMDR Sample

This 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 Note LineOpen 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 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.
70

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.
71
5.3.2 FormSMDR Class

This 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.
72
73
5.3.2.1 FormSMDR Constructor

FormSMDR constructor 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 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 used to update user interface with available SYSTEM lines only.
74

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_Click will invoke an SMDRON method in SystemLine Class to enable call accounting information. The following is the code written for btnSMDRON_Click method:
75
5.3.2.4 Respond to SMDR OFF Button Clicked

When the OFF button is clicked, btnSMDROFF_Click will invoke an SMDROFF method in SystemLine Class to disable call accounting information. The following is the code written for btnSMDROFF_Click method:
5.3.2.5 Respond to Button Get SMDR Information Click

When the Get Info button is clicked, btnGetSMDR_Click will check whether call accounting ID is valid. If call accounting ID is valid, GetSMDR in SystemLine class is invoked and account information is updated. The following is the code written for btnGetSMDR_Click method:
76
5.3.2.6 C# SDK Events

OnKXLinesRespond 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 Control Sample section.
77
5.3.2.7 Respond to KX_SMDR_CREATE event

OnSMDRCreate 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 account information 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 event

OnSMDRDelete 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 account information buffer. This event provides the call account ID that had been deleted. The following is the code written for OnSMDRDelete method:
78
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 of SystemLine class.
5.3.3.1 SystemLine Constructor

SystemLine constructor initializes local members. The following is the code written for SystemLine constructor:
79
5.3.3.2 SMDR ON
SMDRON method is invoked to enable call accounting information notification. Local member bIsSMDRON is set to true if API call succeeds. The following is the code written for SMDRON method:
5.3.3.3 SMDR OFF

SMDROFF method is invoked to disable call accounting information notification. Local member bIsSMDRON is set to false if API call succeeds. The following is the code written for SMDROFF method:
80
5.3.3.4 Get SMDR

GetSMDR method is invoked for obtaining call account information for a specified call account ID. For details of V_CALLACCOUNTINFO, please refer to C# SDK Library API Reference Manual. The following is the code written for GetSMDR method:
81
6.1.3 How to verify TSP <-> PBX connection?
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).
82
6.1.4 How to generate KX_REINIT and KX_RETRIEVE event?
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 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_REINIT event 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_REINIT and KX_RETRIEVE. etc). Call event is not notified while TSP sends KX_REINIT event.
83
6.2.7 How do I find a call ID of a call?
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 MakeCall API.
84
6.2.13 Do I need to shutdown SDK when my application exits?
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 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 be dialed?

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 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 KXMessageEvent before exiting the application. This is to free and release the memory which is no longer in use.
85
6.2.18 How can I uninstall C# SDK?
6.2.14 How do I know which PBX is returning errors during SDK initialization?
You have to subscribe KXMessageEvent before initializing SDK. Any PBX connection error is notified through this 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 opened line?
Basically all APIs which required LineID or SystemLineID 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 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 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.
86
7 C# SDK Error Troubleshooting

This section lists possible causes for C# SDK errors and solutions. Error KX_NOLINE Possible Cause No Panasonic line is available. Solution
1. Proper connection between

TSP and PBX
2. Activation key for Third Party

CTI is installed on PBX. KX_NOPROVIDER KX_SDKNOTINIT KX_FAILEDREINIT No Panasonic 3rd Party TSP is registered to TAPI. C# SDK library is not initialized. C# SDK library had been initialized. Register Panasonic 3rd Party TSP with TAPI. Initialize C# SDK library.
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 connection
disconnected.
Restart windows telephony service.
2. Problem on Telephony
service
3. Heavy traffic for PBX

KX_INVALLINEID
1. Specified line is not

opened. 2. Line ID is not valid.
1. Check if specific API needs

an opened line.
2. Make sure Line ID is valid.

Ensure the call is in required state before calling the API. Ensure the parameter is valid and within the range. Ensure no other TAPI application is running on the same PC. Ensure no other TAPI application is running on the same PC.
KX_INVALCALLSTATE KX_INVALPARAM
The call is not in a valid state for requested operation. Some parameter is out of bounds or not valid for the specific API. C# SDK library is not owner of the specified call. Another TAPI application had monitored the line.
KX_NOTOWNER
KX_INUSE
87
Copyright: This material is copyrighted by Panasonic System Networks Co., Ltd., and may be reproduced for internal use only. All other reproduction, in whole or in part, is prohibited without the written consent of Panasonic System Networks Co., Ltd. Panasonic System Networks Co., Ltd. 2010
PNQX2715YA KK1109MH1010

C SDK Developers Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

C SDK Developers Guide

Uploaded by

Copyright:

Available Formats

C# SDK Developers Guide

C# Software Development Kit

Purpose and Scope