TANDBERG MPS API Interface D13639 User manual

TANDBERG MPS API
User Guide
TANDBERG
D13639 Rev 07
March 2008

TANDBERG MPS API
User Guide
ii
Table of Contents
User Guide................................................................................................................................. 1
1 The TANDBERG API.............................................................................................................. 1
1.1 Introduction to XML.......................................................................................................... 2
1.2 Introduction to XML Path Language (XPath)................................................................... 5
1.3 The TANDBERG XML Engine......................................................................................... 7
1.4 The XML Documents....................................................................................................... 9
1.5 Introduction to TANDBERG XML API Service (TXAS).................................................. 14
1.6 Exercises........................................................................................................................ 15
2 The XML-based Advanced Command Line Interface .......................................................... 17
2.1 XACLI............................................................................................................................. 18
2.2 The Status-type root commands – xstatus / xhistory..................................................... 21
2.3 The Configuration-type root commands - xconfiguration/xdirectory.............................. 23
2.4 The Command-type root commands - xcommand ........................................................ 26
2.5 XML Output - xgetxml.................................................................................................... 29
2.6 Special Commands........................................................................................................ 30
3 API - Configurations ............................................................................................................. 36
3.1 configuration.xml – xconfiguration ................................................................................. 37
3.2 directory.xml – xdirectory............................................................................................... 46
4 API - Commands................................................................................................................... 47
4.1 command.xml – xcommand........................................................................................... 48
5 API - Status........................................................................................................................... 63
5.1 status.xml – xstatus ....................................................................................................... 64
5.2 history.xml – xhistory ..................................................................................................... 79
5.3 Event.xml – xevent......................................................................................................... 80

TANDBERG MPS API
User Guide
1
1 The TANDBERG API
This document is a guide to the API interface of the TANDBERG MPS products. All rights
reserved. This document contains information that is proprietary to TANDBERG. No part of
this publication may be reproduced, stored in a retrieval system, or transmitted, in any form,
or by any means, electronically, mechanically, by photocopying, or otherwise, without the
prior written permission of TANDBERG. Nationally and internationally recognized trademarks
and trade names are the property of their respective holders and are hereby acknowledged.
Disclaimer
The information in this document is furnished for informational purposes only, is subject to
change without prior notice, and should not be construed as a commitment by TANDBERG.
The information in this document is believed to be accurate and reliable; however
TANDBERG assumes no responsibility or liability for any errors or inaccuracies that may
appear in this document, nor for any infringements of patents or other rights of third parties
resulting from its use. No license is granted under any patents or patent rights of
TANDBERG.
This document was written by the Research and Development Department of TANDBERG,
Norway. We are committed to maintaining a high level of quality in all our documentation.
Towards this effort, we welcome your comments and suggestions regarding the content and
structure of this document. Please fax or mail your comments and suggestions to the
attention of:
Research and Development Department
TANDBERG
Philip Pedersen vei 22
1366 Lysaker
Norway
Tel: [phone]
Fax: [phone]
COPYRIGHT © 2007, TANDBERG

TANDBERG MPS API
User Guide
2
1.1 Introduction to XML
XML is a markup language for documents containing structured information.
All information elements in an XML document are marked by a tag and a corresponding end-
tag. The end-tag has the same name as the tag, but is prefixed with a slash, “/”. All tags are
put within angular brackets (“< >”).
Example 1.1
Below is an example of how configurations of a Serial Port could be represented using XML.
<Configuration>
<SerialPort item="1">
<BaudRate item="1">9600</BaudRate>
<Parity item="1">None</Parity>
<DataBits item="1">8</DataBits>
<StopBits item="1">1</StopBits>
<Mode item="1">Control</Mode>
</SerialPort>
</Configuration>
From the tree structure of this example we can see that BaudRate, Parity, Databits,
StopBits and Mode are properties of the SerialPort. We can distinguish between
container-elements and value-elements. Container-elements contain one or more sub-
elements, while value-elements contain a value. This is analogous to files and folders on a
computer. Container-elements are folders that can contain sub-folders and files, while value-
elements are files containing data.
In the XML structure for the Serial Port we see that the container-element SerialPort
contains five sub-elements. All these sub-elements are value-elements, each holding values
for the properties: BaudRate, Parity, DataBits, StopBits and Mode.
Example 1.2
In this example we will look at element attributes. Attributes are used to add meta information
to an element. Attributes are placed within the start tag of an element and different attributes
are separated by space.
An XML structure representing the status of a call in a videoconferencing system is shown
below:
<Status>
<Call item="1" status="Disconnected" type="NA" protocol="NA">
<Cause item="1">255</Cause>
</Call>
</Status>
We can see from the status attribute of the Call element that the call is disconnected. The
only relevant information regarding this call is the disconnect cause value. Therefore the sub-
structure of the call element contains only one value-element.

TANDBERG MPS API
User Guide
3
Example 1.3
If we now look at the call element for an active call we see that call element contains a large
sub-structure:
<Status>
<Call item="1" status="Synced" type="Vtlph" protocol="H323">
<CallRate item="1">768</CallRate>
<RemoteNumber item="1">10.47.15.127</RemoteNumber>
<Channels item="1" type="Incoming">
<Audio item="1" status="Active">
<Protocol item="1">G722</Protocol>
<Rate item="1">64</Rate>
</Audio>
<Video item="1" status="Active">
<Protocol item="1">H263</Protocol>
<Resolution item="1">CIF</Resolution>
<Rate item="1">704</Rate>
</Video>
<Video item="2" status="Inactive" />
<Data item="1" status="Inactive" />
</Channels>
<Channels item="2" type="Outgoing">
<Audio item="1" status="Active">
<Protocol item="1">G722</Protocol>
<Rate item="1">64</Rate>
</Audio>
<Video item="1" status="Active">
<Protocol item="1">H264</Protocol>
<Resolution item="1">SIF</Resolution>
<Rate item="1">704</Rate>
</Video>
<Video item="2" status="Inactive" />
<Data item="1" status="Inactive" />
</Channels>
</Call>
</Status>
In this example, the attributes are used to provide valuable information in addition to
establishing a dependency to the underlying sub-structure of the element.
Example 1.4
In the above examples, all elements are having an attribute named item. This attribute
specifies the instance number of the element. If we expand Example 1.1 to a system having
two serial ports, the XML structure could look like this:
<Configuration>
<SerialPort item="1">
<BaudRate item="1">9600</BaudRate>
<Parity item="1">None</Parity>
<DataBits item="1">8</DataBits>
<StopBits item="1">1</StopBits>
<Mode item="1">Control</Mode>
</SerialPort>
<SerialPort item="2">
<BaudRate item="1">19200</BaudRate>
<Parity item="1">None</Parity>
<DataBits item="1">8</DataBits>

TANDBERG MPS API
User Guide
4
<StopBits item="1">1</StopBits>
<Mode item="1">Auto</Mode>
</SerialPort>
</Configuration>

TANDBERG MPS API
User Guide
5
1.2 Introduction to XML Path
Language (XPath)
XPath is a comprehensive language to address data in XML documents.
It is though very simple to understand the basics. If you are able to specify the path to a file
on your computer, you are able to specify the path to an element in a XML structure.
Example 1.5
Let us go back to the serial port configurations of Example 1.1.
<Configuration>
<SerialPort item="1">
<BaudRate item="1">9600</BaudRate>
<Parity item="1">None</Parity>
<DataBits item="1">8</DataBits>
<StopBits item="1">1</StopBits>
<Mode item="1">Control</Mode>
</SerialPort>
</Configuration>
To specify the path to the SerialPort element we simply start at the root level and separate
the levels in the tree structure by a slash (“/”):
Configuration/SerialPort
The path to the BaudRate element is:
Configuration/SerialPort/BaudRate
Example 1.6
To address a specific item of an element, the item number is added within brackets (“[]”) after
the element name.
The path to the BaudRate element of SerialPort item 2 in Example 1.4 is:
Configuration/SerialPort[2]/BaudRate
If the item number is omitted for an element, all items of this element will be addressed. The
following expression addresses the BaudRate element of both serial ports:
Configuration/SerialPort/BaudRate
Example 1.7
When using XPath it is possible to omit specifying intermediate levels in the address
expression. By using the powerful “double slash” you can address elements without having to
specify the complete path.
The expression below addresses the BaudRate element of both serial ports of Example 1.4:
Configuration//BaudRate

TANDBERG MPS API
User Guide
6
Example 1.8
XPath also supports addressing by putting constraints on element attributes. Let’s go back to
the Call element in Example 1.2. The below expression will address the CallRate element
of all Synced calls in a system:
Status/Call[@status=”Synced”]/CallRate
To add more constraints on element attributes, XPath supports boolean expressions. To
address all Synced H323 calls in a system, the following expression can be used:
Status/Call[@status=”Synced” AND @protocol=”H323”]/CallRate

TANDBERG MPS API
User Guide
7
1.3 The TANDBERG XML Engine
The TANDBERG XML engine is optimized for advanced machine-machine interaction
between a TANDBERG system and an external control application. The main features can be
summarized to:
•Structuring of information
•Addressing using XPath
•Feedback
1.3.1 Structuring of Information
An application programming interface can be seen as a gate where information is exchanged
between two systems - a control application and a target system. The control application
transmits instructions to the target system, while the target system supplies information about
how these instructions are executed, in addition to other system related information.
Thus, the exchange of information can be divided into:
1. information flowing from target, hereby called read information (r)
2. information flowing to target, hereby called write information (w)
If we now look at the TANDBERG systems we can identify three main types of information,
either being read information (r), write information (w) or read-write information (rw):
1. (r) Read information – Status Information.
Information about the system and system processes, i.e. information generated by
the system.
F.ex. status about ongoing calls, network status, conference status etc.
All status information is structured in a hierarchy, making up a database constantly
beeing updated by the system to reflect process changes.
2. (w) Write information – Command Information.
Information supplied by the user to initiate an action.
F.ex. instructing the system to place a call, assigning floor to a specific site,
disconnecting a site etc.
A command is usually followed by a set of parameters to specify how the given action
is to be executed.
3. (rw) Read-Write information – Configuration Information.Information defining
system settings. This information can both be supplied and read by the user. F.ex.
default callrate, baudrate of a serial port, enabling/disabling of various features etc.
All configuration information is structured in a hierarchy making up a database of
system settings. But for the Configuration information, the data in the database can
only be updated by the user/control application.
1.3.2 Addressing using XPath
To address information in the hierarchic structure of Status and Configuration information the
TANDBERG systems support abbreviated XML Path Language (XPath). This allows the
user/control application to address everything from a single element of data, f.ex. the callrate
of a specific call, to larger parts of the hierarchy, f.ex. all information available for a given call.
The structuring of information together with XPath for addressing makes up powerful features
like searching and setting of multiple instances of a configuration.
1.3.3 Feedback
Feedback is an extremely powerful feature where the TANDBERG system actively returns
updated status and configuration information to the user/control application whenever
changes occur. The user/control application can specify what parts of the status and

TANDBERG MPS API
User Guide
8
configuration hierarchies it wants to monitor by using XPath. The user/control application can
therefore limit the amount of information it receives from the target system to only those parts
being of interest for the given application.

TANDBERG MPS API
User Guide
9
1.4 The XML Documents
1.4.1 Documents
The XML Data in the TANDBERG systems are divided into three main types of documents.
The division is based on whether the information is Read Information, Write Information or
Read-Write information:
1. Status documents (r): Documents holding all available Status Information in the
system.
Supported documents:
a. status.xml
b. history.xml
2. Configuration documents (rw): Documents holding all system configurations.
Supported documents:
a. configuration.xml
b. directory.xml
3. Command documents (w): Documents defining the supported system commands
used to initiate system processes. This is write data, i.e. the parameter values for a
given command are defined by the user and posted to the system. The posted values
will not be returned when reading the document from the system. Reading a
command document from the system returns descriptions of the supported
commands with empty parameter values.
Supported documents:
a. command.xml
4. Meta Documents: Meta documents contain information that can be referenced by
other documents, e.g. value domains of configurations or command parameters.
Supported Meta Documents:
a. valuespace.xml
1.4.2 Status Documents (r)
The Status Documents are characterised by an extensive use of XML attributes. In addition to
holding information, the attributes are used to reflect the structure of the sub-elements, which
are dependent on the state of the system.
Example 9
The element Call will contain different sub elements depending on the call state, call type or
direction:
<Call item="1" status="Synced" type="Vtlph" protocol=”H323”
direction="Outgoing">
<CallRate item="1">768</CallRate>
<RemoteNumber item="1">58458</RemoteNumber>
<Mute item="1">Off</Mute>
<Microphone item="1">Off</Microphone>
<Duration item="1">15</Duration>
<Channels item="1" type="Incoming">
<Rate item="1">768</Rate>
<Restrict item="1">Off</Restrict>
<Encryption item="1" status="Off" />
<Audio item="1" status="Active">
<Protocol item="1">G722</Protocol>
<Rate item="1">64</Rate>

TANDBERG MPS API
User Guide
10
<RemoteIPAddress item="1" />
<LocalIPAddress item="1">10.47.8.41:2326</LocalIPAddress>
<Encryption item="1" status="On">
<Type item="1">AES-128</Type>
</Encryption>
<RSVP item="1">Off</RSVP>
<RSVPRate item="1">0</RSVPRate>
<DynamicRate item="1">64</DynamicRate>
<TotalPackets item="1">367</TotalPackets>
<PacketLoss item="1">0</PacketLoss>
<Jitter item="1">0</Jitter>
</Audio>
.
.
.
</Call>
---
<Call item="2" status="Synced" type="Vtlph" protocol="H320"
direction="Outgoing">
<CallRate item="1">384</CallRate>
<Bonding item="1">On</Bonding>
<RemoteNumber item="1">8796</RemoteNumber>
<RemoteNumber item="2" />
<RemoteSubAddress item="1" />
<Mute item="1">Off</Mute>
<Microphone item="1">Off</Microphone>
<LogTag item="1">25</LogTag>
<Channels item="1" type="Incoming">
<Rate item="1">384</Rate>
<Restrict item="1">Off</Restrict>
<Encryption item="1" status="Off" />
<Audio item="1" status="Active">
<Protocol item="1">G722</Protocol>
<Rate item="1">56</Rate>
</Audio>
.
.
.
</Call>
---
<Call item="6" status="Disconnected" type="NA" protocol="NA"
direction="NA">
<Cause item="1">255</Cause>
</Call>
In the above example we see that the Bonding element, RemoteNumber[2] and
SubAddress is not present for H323 calls. On the other hand, for H323 calls, the Audio
channel element holds information regarding packet loss etc., which is not present for H320
calls. If the call is disconnected, the Call element only contains the disconnect cause value.
1.4.3 Configuration documents (rw)
The structure of the Configuration documents is independent of system state, i.e. the
structure will be constant in time. In addition to holding the values for the various
configurations, each configuration value-element includes an attribute, valueSpaceRef,
referencing the value domain for the configuration.

TANDBERG MPS API
User Guide
11
Example 10
From the XML structure below we see that the BaudRate element of SerialPort[1] is
configured to 9600. The BaudRate element references the SerialPortBaudrate element
in the ValueSpace document, showing the value domain for this configuration.
<Configuration>>
<SerialPort item="1">
<BaudRate item="1"
valueSpaceRef="/ValueSpace/SerialPortBaudrate[@item='1']">9600</BaudR
ate>
.
.
</SerialPort>
.
.
</Configuration>
---
<ValueSpace>
<SerialPortBaudrate item="1" type="Literal">
<Value>1200</Value>
<Value>2400</Value>
<Value>4800</Value>
<Value>9600</Value>
<Value>19200</Value>
<Value>38400</Value>
<Value>57600</Value>
<Value>115200</Value>
</SerialPortBaudrate>
</ValueSpace>
To change configurations, the part(s) of the document containing the configurations to be
updated should be posted back to the system with the new values. This will be described
thoroughly in a later section.
1.4.4 Command documents (w)
Command documents contain descriptions of the supported commands for the system. A
Command consists of a Command name and a set of Command parameters. The parameter
elements have attributes to denote whether the parameter is optional or required, in a addition
to referencing the value domain for the given parameter.
Command parameters do not contain any values when read from the system.
Example 11
The command Dial is defined to take five parameters, while only the Number parameter is
required as specified by the attribute required. The value domain for the parameters is
referenced by the attribute valueSpaceRef.
<Command>
<Dial item="1">
<Number item="1" required="True"
valueSpaceRef="/ValueSpace/RemoteNumber"/>
<SubAddress item="1" required="False"
valueSpaceRef="/ValueSpace/SubAddress"/>

TANDBERG MPS API
User Guide
12
<CallRate item="1" required="False"
valueSpaceRef="/ValueSpace/Bandwidth"/>
<Restrict item="1" required="False"
valueSpaceRef="/ValueSpace/OnOff"/>
<NetProfile item="1" required="False"
valueSpaceRef="/ValueSpace/NetprofileRef"/>
</Dial>
</Command>
To issue a command, the command structure is posted back to the system together with
values for the various parameters. Optional parameters can be omitted when posting the
structure back to the system.
Example 12
To place a call to number 999 the user can simply post the following XML structure to the
system:
<Command>
<Dial item="1">
<Number item="1">999</Number>
</Dial>
</Command>
When issuing Commands, the system will return an XML structure in response. The response
structure will have the same name as the command issued, but it will be post fixed with
“Result”. All commands will have an attribute named status, stating whether the command
was accepted or not. If a command is not accepted, the response structure will contain a
cause code. If the command is accepted, the response structure may contain information
relevant for the specific command.
Example 13
The Dial command in the above example may return the following response structure:
<Command>
<DialResult item="1" status="OK">
<CallRef item="1">1</CallRef>
<LogTag item="1">6</LogTag>
</DialResult>
</Command>
The response structure for the Dial command, DialResult, states that the command was
accepted by the system. In addition to stating that the command was accepted, the Dial
command returns the elements CallRef and LogTag. This lets the user identify/trace the
call in the Status documents (status.xml and history.xml).

TANDBERG MPS API
User Guide
13
Example 14
Below is an example of the Dial command, not being accepted by the system:
<Command>
<DialResult item="1" status="Error">
<Cause item="1">17</Cause >
<Description item="1">Too much bandwidth requested</Description >
</DialResult>
</Command>

TANDBERG MPS API
User Guide
14
1.5 Introduction to TANDBERG XML
API Service (TXAS)
TXAS is a service provided by TANDBERG units for transmitting and receiving (transceiving)
information encoded in XML format.
The API uses HTTP(S) as the transport mechanism and connects to the normal web port
(80). TXAS can be accessed in two ways; bare-bone HTTP requests where URL’s uniquely
identifies the request, and SOAP where a single URI is used but the request itself is encoded
with XML.
1.5.1 Bare-bone HTTP(S) access
The bare-bone HTTP mode uses a unique URL to identify the specific request. The contents
of the HTTP body will be a XML document (or part of it).
Bare-bone HTTP(S) access is accomplished by passing arguments in the query string (after
'?' in URL) in a GET request, or using the "application/x-www-form-urlencoded" content-type
mehtod of POSTing form data (Each argument starts with a name '=' and a value, and every
parameter separated with '&' (and opt NL).)
getxml
REQUEST:
/getxml
PARAM:
location = XPath expression
"/getxml" request returns an XML document based on the location parameter passed to the
request. The elements (or complete document) matching the expression will be returned.
On Incorrect XPath expression, a <Fault> element with a <XPathError> element will be
returned.
formputxml
REQUEST:
/formputxml
PARAM:
xmldoc = "an XML document of Configuration, Directory or Command"
This is most useful in a POST (to extend character limit of 255 of GET urls). It posts a
Configuration or Command document to set the configurations or issue a command.
Like getxml, it has the data URL form-data encoded with one single parameter. The Content-
Type of the document must be of type “application/x-www-form-urlencoded” and the body
must be encoded accordingly (e.g. first line will be xmldoc=<then the document>).
putxml
REQUEST:
/putxml
PARAM:
HTTP BODY as argument
Putxml is like "formputxml", put uses the complete BODY as argument (i.e. the content of the
xmldoc parameter). The Content-type should be "text/xml" or "application/xml" (or "text/plain"),
though no check at the moment. (Except for application/x-www-form-urlencoded, this will
cause a failure).

TANDBERG MPS API
User Guide
15
1.6 Exercises
The exercises in this section are based on using a TANDBERG 6000 MXP codec and
Microsoft Internet Explorer. Some of the examples may however also apply to other systems
and other browsers.
NOTE! Replace the ip address, 10.47.8.41, in the below examples with the ip address of your
system.
Exercise 1
The example in this exercise shows how to read the supported XML documents from the
system using a web browser.
Enter the following address in the browsers address field:
http://10.47.8.41/status.xml
http://10.47.8.41/history.xml
http://10.47.8.41/configuration.xml
http://10.47.8.41/directory.xml
http://10.47.8.41/command.xml
http://10.47.8.41/valuespace.xml
Exercise 2
This exercise shows how to use getxml to read the supported XML documents from the
system. Enter the following expressions in the browsers address field (NOTE! The first letter
in the document names is uppercase):
http://10.47.8.41/ getxml?location=Status
http://10.47.8.41/ getxml?location=History
http://10.47.8.41/ getxml?location=Configuration
http://10.47.8.41/ getxml?location=Directory
http://10.47.8.41/ getxml?location=Command
http://10.47.8.41/ getxml?location=ValueSpace
Exercise 3
This exercise shows how to use XPath expressions to read subsets of the XML documents.
http://10.47.8.41/getxml?location=Status/SystemUnit
http://10.47.8.41/getxml?location=Configuration/SerialPort/BaudRate
http://10.47.8.41/getxml?location=ValueSpace/SerialPortBaudrate[@item='1’]
http://10.47.8.41/getxml?location=Configuration//Mode
http://10.47.8.41/getxml?location=Command/Dial
Exercise 4
The address: http://10.47.8.41/xmlput.ssi contains an editor where XML data can be edited
and then posted to the system by pressing the save button. Below are examples of XML
structures to be posted to the system:
<Configuration>
<SerialPort>
<BaudRate>19200</BaudRate>
</SerialPort>
</Configuration>
---
<Configuration>

TANDBERG MPS API
User Guide
16
<SerialPort>
<BaudRate>2400</BaudRate>
</SerialPort>
<Conference>
<H263>Off</H263>
<Downspeed>Off</Downspeed>
</Conference>
</Configuration>
---
<Command>
<Dial>
<Number>10.47.8.42</Number>
</Dial>
</Command>
---
<Command>
<DisconnectCall/>
</Command>

TANDBERG MPS API
User Guide
17
2 The XML-based Advanced
Command Line Interface
The XML-based Advanced Command Line Interface, XACLI, is a very flexible interface both
optimized for machine-machine interaction and man-machine interaction. It is based on the
powerful TANDBERG XML engine and offers many of the same features as the TANDBERG
XML interface.
The main distinction between XACLI and the TANDBERG XML interface is the input format. As
XACLI is a command line interface all inputs from the user/control application have to be put on
one line, in opposite to the XML interface where a complete XML document can be posted to
the system in one operation.
A basic understanding of the information structuring in the TANDBERG XML engine is important
in order to get the most out of the XACLI interface. It is therefore recommended to read the
documentation of the TANDBERG XML API prior to reading this section.

TANDBERG MPS API
User Guide
18
2.1 XACLI
2.1.1 Accessing XACLI
XACLI can be accessed through Telnet via the LAN interface or through RS-232 by connecting
a serial cable to the serial interface connector, referred to as the Dataport.
48 Telnet sessions can be active at the same time in addition to the RS-232 connection.
2.1.2 Root commands
For each of the XML documents supported by the system, there is a corresponding XACLI root
command. The root command has the same name as the corresponding XML document,
except that the root command is prefixed by an “x”:
XML document XACLI root command
status.xml xstatus
history.xml xhistory
configuration.xml xconfiguration
directory.xml xdirectory
command.xml xcommand
The information in the TANDBERG XML engine is divided into three main types: Status
Information, Configuration Information and Command Information, ref. the documentation of the
TANDBERG XML API.
As there is a fundamental difference in these three main types of information, there is also three
different ways of working with the information using XACLI.
2.1.3 Addressing
XACLI supports XPath for addressing Status Information and Configuration Information.
In addition there is support for the proprietary TANDBERG SimplePath notation. With
SimplePath notation an element or a group of elements are addressed by supplying a space
separated list of element names (elemName) and optional element instance numbers (item):
<elemName> [item] <elemName> [item] ...
If the instance number of a given element is omitted, the expression addresses all instances of
this element
Example 2.1
To address the BaudRate sub-element of SerialPort 2:
XPath: SerialPort[2]/BaudRate
SimplePath: SerialPort 2 BaudRate
To address the BaudRate sub-element of all SerialPort elements:
XPath: SerialPort/BaudRate
SimplePath: SerialPort BaudRate