================================================================================
                           XApi: Xymphony Api Project
                           http://www.telesis-pbx.com
                                       by
                                  Telesis A.S.
                      Iskitler Cad. No.68 Ankara, TURKEY
================================================================================


LICENSE

This project is released under Simplified BSD License . Please read below.


BSD LICENSE

Copyright 2010 Telesis A.S. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:

   1. Redistributions of source code must retain the above copyright notice, this list of
      conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above copyright notice, this list
      of conditions and the following disclaimer in the documentation and/or other materials
      provided with the distribution.

THIS SOFTWARE IS PROVIDED BY TELESIS A.S. ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the
authors and should not be interpreted as representing official policies, either expressed
or implied, of Telesis A.S.


SPECIFICATION

XApi (XAPI 2.00) is Xymphony Companion protocol application programming interface 
supported by Xymphony based TELESIS systems. Systems running Xymphony firmware act
as XApi servers and communicate with XApi clients via IP protocol.

xapidll.dll library has XApi functions for application, which needs to 
use XApi services that Xymphony delivers.

This dialog based MFC project provides a sample code to demonstrate usage of various
XApi functions.


PREREQUISITES

This project has been developed using Microsoft Visual Studio 2010. You should 
install the Microsoft Visual Studio 2010 on your computer if you want to compile 
and run the application. You can find the solution file XApi.sln in the XApi project
directory. You can download the latest version of the application from: 

http://wiki.telesis-pbx.com

As XApi protocol uses multicast IP packets (both sends and receives), all the network
elements needed to communicate with the controlled TELESIS Xymphony system should 
support multicast protocol.

Xymphony firmware should be at least 081020 to support XAPI 2.00 companion client protocol.
Xymphony firmware should be 110304 or later to support cmdr client and adjunct server api
functions.

All users of the TELESIS Xymphony system, which are to be controlled, should be 
enabled. To do so, "Common ptoperties/Companion IP address" field of the users 
should be set to the IP address of the PC running XApi application.

Number displayed in "System/Info/Companion protocol" (number of XApi server parts) 
should be enough to support maximum concurrent XApi clients.


EXPERIENCE IN XYMPHONY OPERATING FIRMWARE

Telesis systems are Stored-Program-Controlled (SPC) ones. Their leading-edge 
operational software or firmware, Xymphony, has been developed by Telesis A.S. 
XApi developers should have basic programming experience sufficient to enable 
XApi server within the Telesis system and utilize features offered by the server. 
Embedded online help system in Telesis systems and technical documentation at 
http://wiki.telesis-pbx.com may help software developers to understand basics of
Xymphony firmware. 


IMPLEMENTATION

You can find the definitions of XApi calls in xapilib\xapilib.h . Applications should initialize 
the stack by XAPI_Stack_initialize function before calling any other XApi function.
If already initialized, XAPI_Stack_initialize function will release all client
links. Before terminating the application a final call to XAPI_Stack_release should be
performed.

Companion client:

To open a client link to Xymphony, application should perfom XAPI_Client_start api
call to receive a hadle to use with the rest of the XAPI_Client api calls. The parent
window will be notified about link state changes and relevant events by PostMessage 
function. If the appication no longer needs the link, should call XAPI_Client_stop
to release the resources.

Every client can register for upto 512 busy display panel entries by XAPI_Client_bdp_register
call. Lamp state changes of all registered entries will trigger a PostMessage to
the parent.

Cmdr client:

To open a cmdr client link to Xymphony, application should perfom XAPI_Cmdr_start api
call to receive a hadle to use with the rest of the XAPI_Cmdr api calls. The parent
window will be notified about link state changes and received cmdr records by PostMessage 
function. If the appication no longer needs the link, should call XAPI_Cmdr_stop
to release the resources.

Adjunct server:

To open an adjunct server link to Xymphony, application should perfom XAPI_Adjunct_start api
call to receive a hadle to use with the rest of the XAPI_Adjunct api calls. The parent
window will be notified about link state changes and received setup modification requests
by PostMessage function. Responses to setup modification requets of Xymphony can be performed
by XAPI_Adjunct_response api call. If the appication no longer needs the link, should call
XAPI_Adjunct_stop to release the resources.


RUNNING

After running Windows Visual Studio 2010, select Open Existing Project then select 
XApi.sln file. This will open XApi solution onto your workspace. After building 
the solution you may start the test application with Debug > Start.

Sample application sends companion protocol messages to port number Xapi_default_protocol_port.
If you  use a different port, set "Ethernet/Basic/Companion signalling port" of Xymphony accordingly.

To launch a companion client, type the access code of the user and then press
"New companion client (access code)" button. (please remember that both the PC running
and the Xymphony based  system must be in the same Local Network). This will open a window,
which provides visual tools like buttons, for using and testing the XApi calls.
Xapilib supports upto 512 companion client instances simultaneously. The number of instances
that Xymphony supports depends on the platform and installed licenses.

Advanced developers can write their own companion applications by using the XApi 
library and can manage to have specific features for specific applications with 
desired graphical user interfaces. Also XApi library can be used for monitoring 
intentions. In such cases, remember that up to 512 clients data can be monitored.

To launch a cmdr client to download Xymphony cmdr data, type the IP address or URL of
the Xymphony based system and then press "New cmdr client (Xymphony IP address)" button.
This will open a window to display received cmdr records. Xapilib supports upto 32 cmdr
client instances simultaneously (to download cmdr data of 32 Xymphony based systems).
Be sure that the IP address of the PC running this application is registered to Xymphony
"Ethernet/Cmdr/Xtools Cmdr client IP address" and Xymphony cmdr download protocol is
selected as Xtools ("Ethernet/Cmdr/Cmdr protocol"). Sample application sends cmdr download
requests to port number Xapi_default_cmdr_port. If you  use a different port, set
"Ethernet/Cmdr/XtoolsMonitor(UDP)Cmdr(TCP)port" of Xymphony accordingly.

To launch an adjunct server, type the IP address or URL of the Xymphony based system and
then press "New adjunct server (Xymphony IP address)" button. This will open a window to
display received setup modification requests. "Response digits" and "Charge pulse limit"
fields will be used to compose the automated response. Xapilib supports upto 8 adjunct
servers instances simultaneously (to serve 8 Xymphony based systems).
Be sure that the IP address of the PC running this application is registered to Xymphony
"Ethernet/Adjunct/Adjunct server IP address". The sample application listens to requests
from port number Xapi_default_adjunct_port. If you  use a different port, set
"Ethernet/Adjunct/Adjunct server port" of Xymphony accordingly.


HISTORY

2013-03-10 2.12
XAPI_API HXAPI XAPI_Client_start_Thread (unsigned idThread, unsigned access_code)
function added to start client process when a HWND is not available.
Minor bugs corrected.

2012-06-15 2.11 
XAPI_Client_digits accepts DTMF digits a-d 

2012-06-01 2.10 
Stack implemented as a DLL.
Sample MFC project do not need Windows SDK to be installed.

2011-03-01 2.00 
XApi library supports cmdr client and adjunct server api functions.

2010-09-01 1.00 
Initial release. Sample test program and XApi library supporting XAPI 2.00.


AUTHOR

TELESIS A.S. 
