View source for VS-SDK for AlphaCom

{{AI}}
==Introduction==
ICX-500 and ICX-Core software are fully compatible with the VS-SDK for AlphaCom. In the rest of this article ICX (for ICX -500 and ICX-Core) can be read for AlphaCom; only when there is a noticeable difference between ICX and AlphaCom, ICX will be referred to separately. The SDK name itself will remain VS-SDK for AlphaCom for the time being.<br> 
The SDK provides dll's, helpfiles and some sample software to make integration of 3rd party software with ICX as easy as possible. Three sample applications are delivered including source code. These 3 samples cover many (if not all) aspects of what normally is expected from an integration with ICX. Users of the SDK are allowed to freely use parts of the sample source code in their own software.<br> <br>
The information in this article is relevant for the SDK release 2.1.3.1 and higher. For releases 1.3.3.2 and earlier, please refer to the manual which was included in the SDK package.

==Licensing==
The possibility to retrieve intercom station state information from the exchange is a licensed feature, and requires the presence of an ‘API/OPC interface’ license in the ICX or AlphaCom for at least as many stations of which the status has to be retrieved.<br>
===ICX===
With ICX it is possible to purchase a single Product Key which covers all stations connected to all ICX's in a network. ICX licenses can be stacked, i.e. 1x 1002602306 + 2x 1002602309 gives 1088 API licenses which can be used on 2 or more ICXs.
*1002602306 - ILI-API64 - API License Supporting 64 Stations
*1002602309 - ILI-API512 - API License Supporting 512 Stations

===AlphaCom E/XE===
Every AlphaCom in an AlphaNet requires a license.
*1009649901 - STENTOFON API License Supporting 40 Stations
*1009649902 - STENTOFON API License Supporting 80 Stations
*1009649903 - STENTOFON API License Supporting 160 Stations
*1009649904 - STENTOFON API License Supporting 240 Stations
*1009649905 - STENTOFON API License Supporting 320 Stations
*1009649906 - STENTOFON API License Supporting 400 Stations
*1009649907 - STENTOFON API License Supporting 552 Stations

==Installation==
VS-SDK for AlphaCom is distributed as a zip-file containing 2 windows installer packages
*'''VS-SDK for AlphaCom_Setup_Vx.x.x.x.msi'''
*'''AlphaNetServiceProviderService_Setup_Vx.x.x.x.msi'''
The package '''VS-SDK for AlphaCom_Setup_Vx.x.x.x.msi''' contains the SDK files. 
The files are by default installed to C:\Program Files(x86)\Vingtor Stentofon\VS-SDK for AlphaCom\, with links on the User Program folder (All Programs) "Vingtor Stentofon".
The setup will install the following:

* The latest release of the [[Stentofon_DotNet_Libraries|Stentofon.AlphaCom.*]] libraries
* The latest compiled help files from the libraries
* The latest bundle of example applications including source code

For more information about '''AlphaNetServiceProviderService_Setup_Vx.x.x.x.msi''', see [[#More information about the AlphaNetServiceProvider|below]] and  the article [[AlphaNetServiceProvider]].

<br>

==DLL description==
===Stentofon.AlphaCom.AlphaNet.dll===
The Stentofon.AlphaCom.AlphaNet.dll implements the AlphaCom Data Protocol and handles the communication with the AlphaCom XE exchanges. It raises events and exposes methods to be able to receive data from, and send commands to the exchange.
The .dll supports auto-discovery of the complete AlphaCom XE network configuration. This makes the system very easy to configure and set up. In addition, the .dll will track and report all state changes in the AlphaCom XE network which the 3rd program subscribes to.
The .dll supports the STENTOFON AlphaNet. This means that all AlphaCom XE exchanges and stations in a network can be addressed by having an IP connection to just one of the AlphaCom XE exchanges.
The .dll requires Microsoft .NET 4.6.2
The DLL contains three name spaces:
*Messages
*Client
*Config
The AlphaNetClient object in Stentofon.AlphaCom.AlphaNet.dll maintains a database (named Stations), which stores the stationstate. The database is updated automatically by the AlphaNetClient.
The Stations database is available when the AlphaNetClient is created  
 _client = new AlphaNetClient(…
 _client.Stations
<br>

===Stentofon.AlphaCom.Data.dll===
The Stentofon.AlphaCom.Data.dll is not required anymore (see the paragraph above), but is available on request for backward compatibility for developers who want to upgrade from SDK 1.x.x.x. Note that Zenitel recommends that during the upgrade all references to events and methods supported by this dll are removed and that the dll is not used at all.<br>
The Stentofon.AlphaCom.Data.dll provides a standardized way of storing and retrieving AlphaCom XE network, exchange and station information and states.
Storage can be in an MSSQL database or in memory ’AlphaComStateStorages.MSSQL’ or ‘AlphaComStateStorages.IN_MEMORY’.
The .dll requires Microsoft .NET 4.6.2
The DLL contains one name space:
*State
The AlphaNetClient object in Stentofon.AlphaCom.AlphaNet.dll maintains a database (named Stations) which contains the same information as AlphaComState object in Stentofon.AlphaCom.Data.dll, as shown below:
 private AlphaComState _stateStorage;
   _stateStorage = new AlphaComState(AlphaComStateStorages.IN_MEMORY);

<br>

==Communication with the AlphaCom XE exchange==
Software based on the SDK have 2 possibilities to communicate with AlphaCom:
*Direct connection to either TCP port 61112 or 61113
*Connection via a 'Service Provider'
Also when there is an AlphaNet of multiple AlphaCom servers, it is only necessary to connect to a single AlphaCom, it does in this case not matter with which AlphaCom the connection will be established.

===Direct connection===
ICX-AlphaCom and AlphaCom have 2 communication ports available for API/OPC based software, ports 61112 and 61113. These 2 ports are independent. <br>
The number of simultaneous connections that can be made to these ports depends on the AlphaCom or ICX-AlphaCom software version.
* As from ICX-AlphaCom 1.1.3.0 the TCP-server has been re-implemented; until then an API/OPC port on an ICX-AlphaCom only supported 1 connection, if more connections were required it was possible to use similar ports on other exchanges as described in the bullets below; Now the total number of connections in an AlphaNet has the limitation as below, where it is possible to use a single port on a single server to provide those connections (all servers must have the same softwarwe version):
** 120 API connections
** 30 OPC server connections
* As from AMC-IP software version 12.3.3.2 and ICX-AlphaCom 1.0.3.0 it is possible to use up to 10 ports (61112/61113), divided over at least 5 exchanges. Ports 61112 and 61113 only accept a single connection.
* All earlier software only allows 2 simultaneous connections, 1 to port 61112 and 1 to port 61113. In an AlphaNet, once a port is used on one AlphaCom server that same port number is blocked on the other servers

===AlphaNetServiceProvider===
If the number of connections needs to be expanded, please see the paragraph above, it is possible to use the '''AlphaNetServiceProvider'''. This 'Service provider' is included as from SDK version 2.1.3.1. The service provider will itself connect to either port 61112 or 61113; it will then make a single new port available which accepts multiple conections for other software to connect to. In effect the service provider acts as a port expander.

===TCP communication ports===
To be able to communicate with either of port 61112 or 61113, the port must be enabled in the exchange using AlphaWeb, the web server which is integrated in the AlphaCom XE.
Log in to AlphaWeb and select ‘System Configuration/Filters’ and enable the required port number for the physical Ethernet port the API will connect to.

===Connecting to the AlphaCom XE===
At software start up it is only necessary to provide the following information:
*IP address of AlphaCom or service provider
*Port to connect to
**61112 or 61113 for AlphaCom
**The port to connect to as configured for the service provider
*Information whether the connection is direct or via the service provider
**DIRECT_TCP
**PC_REMOTE
Calling the method '''_client.Connect();''' will then:
*Establish the connection
*Discover all nodes which are part of the AlphaNet
*Discover all intercom stations which are configured in each of the nodes
*Handle all messages which are required to keep the connection

===More information about the AlphaNetServiceProvider===
The AlphaNetServiceProvider is available both as an application and as a service.<br>
More information about the AlphaNetServiceProvider is available on [[AlphaNetServiceProvider]].

==AlphaCom Data Protocol message classes==
The API communicates with AlphaCom XE via the AlphaCom Data Protocol. The ‘.Messages’-namespace provides classes for AlphaCom Data Protocol Messages.
 using Stentofon.AlphaCom.AlphaNet.Messages;

==Event reports==
Activity inside the exchange can raise events. The following is an example.
Register for some events:
 // Register for some events
 _client.OnStationConnect += HandleStationConnect;
 _client.OnStationDisconnect += HandleStationDisconnect;

The event handlers:
 #region The AlphaNet Handlers
 private static void HandleStationConnect(StationConnect sc)
 {
   // Use the objects internal ToString() method:
   Console.WriteLine(sc);
 }
 private static void HandleStationDisconnect(StationDisconnect sd)
 {
   Console.WriteLine(sd);
 }
 #endregion

If only part of the information contained in an object is of interest, then there are a multitude of methods available to retrieve just that information, as for example:
 private static void HandleStationConnect(StationConnect sc)
 {
   Console.WriteLine(“ A: {0}”, sc.StationA.GetDirNo());
 }

==Sending commands to AlphaCom XE==
Commands to the AlphaCom XE server are normally related to a station. When a guard clicks on an area on his PC screen to make a call or cancel an established call, it is just as if he presses keys on his intercom station.
All information related to an intercom station is part of an object of type '''StationState'''. The '''StationState class''' also has the methods implemented to format commands to be sent to the AlphaCom XE on behalf of an intercom station. Methods where the name starts with '''MakeCommand''', will format and store the command.
The AlphaNetClient class method '''SendAlphaCommand''' sends the stored command to the exchange.
 private StationState _selectedStation
   _selectedStation.MakeCommandCKey();
   _client.SendAlphaCommand(_selectedStation);
<br>

==API custom events==
All standard AlphaNet broadcast messages will always be sent out from all available OPC/API ports. All important activity in the exchange is reported as a broadcast message and is therefore able to raise an event in the API. But there may be a specific interface requirement which depends on an action inside the exchange for which there is no API event available, as there is no related broadcast message. To be able to support such requirements there are four custom events which can be raised:
*OnCustomParameter event
*OnCustomString event
*OnCustomStringParameter event (available as from SDK version 2.1.3.3)
*OnCustomWordStringParameter event (available as from SDK version 2.1.3.3)
The AlphaCom XE exchange features an internal event handler with trigger points on any possible action inside the exchange. By programming a custom message inside the exchange event handler related to the relevant action of the specific interface, it is possible to raise the above listed API events. <br>
Addressing scheme:
*As from AMC-IP software version 12.3.3.1 and ICX-AlphaCom 1.0.3.0 use @*D1 - this will broadcast the message out of all open OPC/API ports in all servers in an AlphaNet
*For previous AMC-IP software versions, the data must be sent out via specific ports using this address scheme: 
**@nnC7 – for port 61112
**@nnC4 – for port 61113
nn is the node number and can be in the range 01-FE (1-254). TCP ports 61112 and 61113 are handled by the AlphaCom XE exchange as devices with device number 199 (0xc7) for port 61112 and 196 (0xc4) for port 61113. 

===OnCustomParameter event===
To raise the API OnCustomParameter event, the exchange must send a message with MessageID 0x7f01 followed by 7 parameters. The first two parameters are of type [[NET_OBJ_REF]], the other 5 parameters are of type [[UINT2]]. 
Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:
*@*d1 M7F01 %1.ref %2.ref Wpar1 Wpar2 Wpar3 Wpar4 Wpar5
Where:
*@*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
*par1, par2, par3, par4 and par5 can be any value from 0 to 65535

If one of the two [[NET_OBJ_REF]] parameters is not relevant, the NULL value should be used, which is:
*U0 – NULL value for parameter type [[NET_OBJ_REF]]

Note that all parameters must be passed. [[NET_OBJ_REF]] parameters which are not relevant to the interfacing application must be set to NULL; [[UINT2]] parameters which are not relevant can be set to any arbitrary value.

===OnCustomStringParameter event===
To raise the API OnCustomStringParameter event, the exchange must send a message with MessageID 0x7f02 followed by up to 7 parameters. The first two parameters are of type [[NET_OBJ_REF]], the other 5 parameters are of type string. 
Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:
*@*d1 M7F02 %1.ref %2.ref "str1\tstr2\tstr3\tstr4\tstr5\t"
Where:
*@*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
*"str1\tstr2\tstr3\tstr4\tstr5\t" combines upto 5 string parameters in one string out of the AlphaCom
**\t separates each string parameter; note that \t must also be used after the last string parameter
**It is possible to pass fewer than 5 string parameters

If one of the two [[NET_OBJ_REF]] parameters is not relevant, the NULL value should be used, which is:
*U0 – NULL value for parameter type [[NET_OBJ_REF]]

===OnCustomWordStringParameter event===
To raise the API OnCustomWordStringParameter event, the exchange must send a message with MessageID 0x7f03 followed by up to 12 parameters. The first two parameters are of type [[NET_OBJ_REF]], followed by 5 parameters of type [[UINT2]] and up to 5 parameters of type string. 
Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:
*@*d1 M7F03 %1.ref %2.ref Wpar1 Wpar2 Wpar3 Wpar4 Wpar5 "str1\tstr2\tstr3\tstr4\tstr5\t"
Where:
*@*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
*par1, par2, par3, par4 and par5 can be any value from 0 to 65535; all 5 parameters must be passed
*"str1\tstr2\tstr3\tstr4\tstr5\t" combines upto 5 string parameters in one string out of the AlphaCom
**\t separates each string parameter; note that \t must also be used after the last string parameter
**It is possible to pass fewer than 5 string parameters

If one of the two [[NET_OBJ_REF]] parameters is not relevant, the NULL value should be used, which is:
*U0 – NULL value for parameter type [[NET_OBJ_REF]]

===OnCustomString event===
With the OnCustom...Parameter events described above, most interface requirements can be met. For those requirements which are not covered by events, it is possible to use the OnCustomString event. Any number of parameters of any type will be passed as a single string.
To raise the API OnCustomString event, the exchange must send a message with MessageID 0x7f00. All following parameters will be sent as one large string, decoding of which will be application specific.

==Method to send ACDP messages==
The underlying protocol of the API is the AlphaCom Data Protocol. To send commands to the AlphaCom XE, specific methods (some of which are described in the sections above) have been implemented. These methods result in the API sending the appropriate ACDP command to the exchange.
Sometimes it can be an advantage to send an ACDP command directly to the exchange. For this purpose, a method has been implemented which takes the ACDP command as a parameter in Simple Link Layer format.
 Public bool SendAlphaCommand(String cmd)
The statement below will set up a call between stations with directory numbers 101 and 102:
 SendAlphaCommand("$CALL L101 L102");

==Intercom station state==
By setting the flag '''AutoGetStationState''' the API will discover all intercom stations in all discovered exchanges. For each discovered station, the API will raise the '''OnStationStateReceived''' event. This can therefore be used to get an accurate overview of the connected intercom stations and their status at the time of the connection of the API to the exchange.
Most applications need to be able to retrieve 'StationState' at any moment and 'Stentofon.AlphaCom.Data.dll' stores this information so it is readily available.

==Sample software==
Three applications, including their source code, are included in the SDK. Most events and methods which are used in the majority of applications are also used in the 'Stations-Basic' and 'CallRequest' sample applications.
The 3rd application 'Stations' is a further development of the 'Stations-Basic' application but adds control for 'Multi-conferencing', an advanced mixing capability which requires AMC-IP software 12.3.3.2 or higher and VSIS-4.7 or higher.
*Stentofon.AlphaCom.Example.CallRequest
**Connects directly to AlphaCom - select portnr 61112 or 61113
**Autodiscovery of nodes and stations
**Ability to select a station as master in 'Station Search/Select'
**Shows incoming call requests
**Accept a call request by selecting a queue entry in the dropdown box 'Selected Station Queue'
*Stentofon.AlphaCom.Example.Stations-Basic
**Connects directly to AlphaCom or via the service provider - in the latter case, make certain that AlphaNetServiceProviderAppl.exe is running
**Autodiscovery of nodes and stations
**Ability to select a station as master in 'Station Selector and Status' - start typing a directory number in the text field to populate the dropdown box, select an entry in the dropdown box
**Show status of the selected station
**Dial digits, as if pressing digits on a keypad
**Operate 'M' and 'C'
**Operate 10 DAK (Direct Access Key) buttons
*Stentofon.AlphaCom.Example.Stations
**Connects directly to AlphaCom or via the service provider - in the latter case, make certain that AlphaNetServiceProviderAppl.exe is running
**Autodiscovery of nodes and stations
**Ability to select a station as master in the TAB 'Station Control'
**Show status of the selected station
**Dial digits, as if pressing digits on a keypad
**Operate 'M' and 'C'
**Operate 10 DAK (Direct Access Key) buttons
**Play voice messages to the selected station
**Show Station RCI status
**The TAB 'Station Matrix' allows the selection of 4 stations to view their status
**The TAB 'Conference Control' requires in-depth knowledge of setting up Turbine stations as conference mixers 

==Differences between SDK versions 1.x.x.x and 2.x.x.x==
===Connecting to AlphaCom===
'''Connect()''' replaces the separate methods '''StartListening()''' and '''StartMonitorThread()'''

===Station state updates===
It was required to update 'stationstate' via software on events such as 'OnStationBusyReceived', 'OnStationFreeReceived', 'OnStationConnect', 'OnStationDisconnect'. Stationstate updates are now automatic as part of the AlphaNetClient object.

===AlphaNet Service Provider===
{{note|Note: The use of the AlphaNet Service Provider is not necessary when using ICX-AlphaCom version 1.1.3.0 or higher, as the OPC/API ports now accept multiple connections: [[ICX_1.1.3.X_-_Release_Notes#ICXEL-20_Multiplexing_API_Port_61112_and_61113]]
}}

AlphaCom only has ports 61112 and 61113 available for connection of API based software; these ports only accept a single connection each. The Service Provider will connect to either port 61112 or 61113 (configurable) and will make one new port available which accepts multiple connections. The connection type can be set to:
*DIRECT_TCP
*PC_REMOTE

===Logging===
A new dll 'Gurock.SmartInspect.dll' has been included. This dll writes logging information in a file with extension '.sil'; This file may help Zenitel in case the developer experiences issues with the communication between his/her application and the AlphaCom. The log file is placed in C:\Users\%USERNAME%\AppData\Roaming\STENTOFON\SDK\Logs


[[Category:3rd party integration]] [[Category:SDK]]