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...
User Guide 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.
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...
Page 5
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...
Page 6
TANDBERG MPS API User Guide <StopBits item="1">1</StopBits> <Mode item="1">Auto</Mode> </SerialPort> </Configuration>...
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...
Page 8
TANDBERG MPS API User Guide 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...
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.
Page 10
TANDBERG MPS API User Guide 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.
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.
Page 12
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...
Page 13
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...
Page 14
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...
Page 15
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...
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).
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.
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.
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.
Page 21
Rate: 704 Video 2 (status=Inactive): / Data (status=Inactive): / *s/end Request for Call 1 element with exposure option “-“: xstatus call 1 - *s Call 1 (status=Synced, type=Vtlph, protocol=H323, direction=Outgoing): Channels 1 (type=Incoming): Encryption (status=Off): / TANDBERG MPS API User Guide...
Page 22
Request for Call 1 element with exposure option “--“: xstatus call 1 -- *s Call 1 (status=Synced, type=Vtlph, protocol=H323, direction=Outgoing): *s/end 2.1.5 Misc The XACLI interface is not case sensitive. XACLI allows using only partial names. TANDBERG MPS API User Guide...
GatewayCall [1..80] H323Gatekeeper ISDNInterfaceCard [1..6] To access status-type data, simply type the status-type root command (xstatus or xhistory) and then an XPath address expression or a TANDBERG SimplePath expression: <status-type root command> <address expression> Example 2.4 xstatus call 1 remotenumber...
Page 24
SubnetMask: "255.255.248.0" Gateway: "10.47.8.1" *s/end NOTE! To write a parser for the XACLI format, the parser must keep track of the levels by counting white spaces. The indent is increased by two whitespaces for each level. TANDBERG MPS API User Guide...
? or help. The possible values for the elements matching the address expression will be returned. HTTPS IP [1..2] SerialInterfaceCard [1..6] IPProtocol Session ISDNInterfaceCard SingleNumberDialIn [1..6] SNMP MediaBoard [1..12] NetProfile [1..7] STUN SystemClock PrefixDialIn SystemUnit QoS [1..2] Telnet TANDBERG MPS API User Guide...
Page 26
TANDBERG MPS API User Guide <configuration-type root command> <address expr> ?/help Example 2.7 User wants to configure IP: xconfiguration ip ? *h xConfiguration IP Assignment: <DHCP/Static> *h xConfiguration IP Address: <IPAddr> *h xConfiguration IP SubnetMask: <IPAddr> *h xConfiguration IP Gateway: <IPAddr>...
Page 27
TANDBERG MPS API User Guide Example 2.9 User wants to set IP assignment: xconfiguration ip assignment: static xconfiguration ip/assignment: static...
?? 2.4.1 Command help To get help on a specific command, type the command-type root command – then a command name followed by ? or help: <command-type root command> <command name> ? TANDBERG MPS API User Guide MessageBoxDisplay PIPHide PIPShow...
Page 29
If there are multiple instances of a parameter, the item number is added after the tag separated with a dot: <command-type root command> <command> <parameter.item:value> <parameter.item:value>... Example 2.15 xcommand groupentryadd name:TANDBERG localentryid.1:15 localentryid.2:57 TANDBERG MPS API User Guide...
Page 30
666 r:on 10 128 Command response When issuing a command, the system will return a set of return values, ref. the documentation of the TANDBERG XML API. The response will be on the same format as the standard XACLI Status format. Example 2.18 xcommand dial 10.47.15.127...
XPath expression as parameter and the elements (or complete document) matching the expression will be returned. Example 2.19 xgetxml status/ip <Status> <IP item="1"> <Address item="1">10.47.8.20</Address> <SubnetMask item="1">255.255.248.0</SubnetMask> <Gateway item="1">10.47.8.1</Gateway> </IP> </Status> TANDBERG MPS API User Guide...
*s Call 1 (status=Synced, type=Vtlph, protocol=H323, direction=Outgoing): Channels 1 (type=Incoming): Audio (status=Active): Protocol: G728 *s/end When changing back to G722: *s Call 1 (status=Synced, type=Vtlph, protocol=H323, direction=Outgoing): Channels 1 (type=Incoming): Audio (status=Active): Protocol: G722 *s/end TANDBERG MPS API User Guide...
Page 33
User only wants to know when calls are connected and disconnected: xfeedback register status/call[@status="Synced"]-- xfeedback register status/call[@status="Disconnected"]-- xcom dial 10.47.15.127 *r Result (status=OK): CallRef: 1 LogTag: 4 *r/end CONNECT *s Call 1 (status=Synced, type=Vtlph, protocol=H323, direction=Outgoing): TANDBERG MPS API User Guide...
Page 34
Channels 1 (type=Incoming): Rate: 768 Restrict: Off Encryption (status=Off): / Audio (status=Active): Protocol: G722 Rate: 64 Video 1 (status=Active): Protocol: H263 Resolution: CIF Rate: 704 Video 2 (status=Inactive): / Data (status=Inactive): / Channels 2 (type=Outgoing): TANDBERG MPS API User Guide...
Page 35
(no “double slashes” allowed). This will improve the performance of the system when issuing many consecutive configurations. NOTE! It is always recommended to supply the complete path for configurations to be set when issuing commands from an external control application. TANDBERG MPS API User Guide...
Page 36
<on/off> If xmlconfigfeedback is set to on, feedback on configurations will be returned in XML-format instead of the standard XACLI configuration format. Example 2.25 XACLI-format: *c xConfiguration SerialPort 1 BaudRate: 2400 XML-format: <Configuration> <SerialPort item="1"> TANDBERG MPS API User Guide...
Page 37
If xmlcommandresult is set to on, response for commands will be returned in XML-format. Example 2.27 XACLI-format: xcom dial 10.47.15.127 *r Result (status=OK): CallRef: 1 LogTag: 8 *r/end XML-format: xcom dial 10.47.15.127 <Result item="1" status="OK"> <CallRef item="1">1</CallRef> <LogTag item="1">8</LogTag> </Result> TANDBERG MPS API User Guide...
TANDBERG MPS API User Guide 3 API - Configurations This section gives an overview of the Configuration Information available in the Configuration XML documents (configuration.xml / directory.xml) and the Configuration root commands (xconfiguration / xdirectory) of the XACLI interface. All examples are presented using the standard XACLI format.
Page 47
LanguageAdmin: <S: 0, 3> LanguageGraphic: <S: 0, 3> DefaultConferenceTemplate: <1..10> Telnet Telnet Mode: <On/Off> * The Gateway LoadLimit command will not be available if 1) MPS doesn't have GW option; 2) MPS have MCU and GW option. TANDBERG MPS API User Guide...
TANDBERG MPS API User Guide 4 API - Commands This section gives an overview of the supported system Commands. All examples are presented using the standard XACLI format.
Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. Call(r): <1..128> Reference to the call to be muted or unmuted. Mode(r): <On/Off> Denotes whether the call is to be muted or unmuted. TANDBERG MPS API User Guide...
Page 51
Description Textual description of the cause code. GatewayCall(r): <1..80> DirectoryEntry(r): <1..99> Cause: <1…> Cause code specifying why the call was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
Page 52
Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. Conference(r): <1..35> PictureMode: VideoFormat: <Auto/Motion/Sharpness> CustomFormats: <On/Off> AGC: <On/Off> AllowIncomingCalls: <On/Off> Duration: <0..999> MaxAudioSites: <0..16> MaxVideoSites: <0..160> TANDBERG MPS API User Guide...
Page 53
Description Textual description of the cause code. Conference(r): <1..35> Name: <S: 0, 30> CallRate: <1xh221/2xh221/64/128/192/256/320/384/H0/512/768/1152/1472/15 36/1920/Tlph> Restrict: <On/Off> Password: <S: 0, 8> PasswordOnOutgoingCalls: <On/Off> Encryption: <On/Off> EncryptionType: <DES/AES-128/Auto> SecondaryRate: <On/Off> WelcomeMessage: <On/Off> DuoVideo: <On/Off> TANDBERG MPS API User Guide...
Page 54
AudioG728: <On/Off> CascadingPreference: <Auto/Master/Slave> BillingCode: <S: 0, 16> CPAutoSwitch: <0..60> NetworkId: <1..32> ConferenceSelfview: <On/Off> Protect: <On/Off> TemplateReference: <1..10> HDEnabled: <On/Off>onference(r): <1..12> Cause: <1…> Cause code specifying why the command was not accepted by the system TANDBERG MPS API User Guide restrict:on...
Page 55
Cause: <1…> Cause code specifying why the call was not accepted by the system Description Textual description of the cause code. Conference(r): <1..35> Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
Page 56
LogTag: <1…> Unique reference to call. Identifies the call in the call log. Cause: <1…> Cause code specifying why the call was not accepted by the system Description Textual description of the cause code. CallRef: 26 LogTag: 312 TANDBERG MPS API User Guide...
Page 57
CallerId: <S: 0, 60> Cause: <1…> Cause code specifying why the call was not accepted by the system Description Textual description of the cause code. Conference(r): <1..15> NetProfile(r): <2..7> Number(r): <S: 0, 60> CallerId: <S: 0, 60> TANDBERG MPS API User Guide...
Page 58
Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. GatewayCall(r): <1..80> Reference to the call to be disconnected. Cause: <1…> Cause code specifying why the command was not TANDBERG MPS API User Guide...
Page 59
URL(r): <S: 0, 256> The URL to post feedback to. Expression.1..15: <S: 0, 256> XPath expression ID: <1..3> Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. expression.1:status/call expression.2:status/conferenc ID: 2 TANDBERG MPS API User Guide...
Page 60
Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. Name: <S: 0, 48> The entry’s name. LocalEntryId.1..32: <1..99>References to local entry ids to be included in this Group entry. TANDBERG MPS API User Guide...
Page 61
Description Textual description of the cause code. Window(r): <1..16> CallID(r): <1..176> Call. Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
Page 62
Description Textual description of the cause code. LocalEntryId: 17 LocalEntryId(r): <1..99> Reference to the entry to delete. Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
Page 63
Conference(r): <1..15> Conference to add number NetProfile(r): <2..7> Net profile of number Number(r): <S: 0, 60> Number to add Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
Page 64
Text: <S: 0, 61> The text to set Visible: <On/Off> If text is visible Cause: <1…> Cause code specifying why the command was not accepted by the system Description Textual description of the cause code. TANDBERG MPS API User Guide...
TANDBERG MPS API User Guide 5 API - Status This section gives an overview of the Status Information available in the Status XML documents (status.xml / history.xml) and the Status root commands (xstatus / xhistory) of the XACLI interface. All examples are presented using the standard XACLI format.
Page 67
Encryption (status=Off): / RSVP: Off RSVPRate: 0 DynamicRate: 164 TotalPackets: 259599 PacketLoss: 0 Jitter: 7 Video 2 (status=Inactive): / Data (status=Inactive): / *s/end *s Call 2 (status=Disconnected, type=NA, protocol=NA, direction=NA, logTag=NA, conferenceRef=NA): Cause: 255 *s/end TANDBERG MPS API User Guide...
Page 68
MaxVideoSites: 0 EntryExitTones: On LegacyLevel: 0 TelephoneFilter: On FloorToFull: On WebCallListTimeout: On BandwidthThreshold: 128 NetworkId: 1 ConferenceSelfview: On PhoneIndication: On SpeakerIndication: On VideoText: On VideoTextTimeout: 2 ChairControl: On LectureMode: Off Protect: Off VideoCodingMode: Transcoding SecondaryRate: On TANDBERG MPS API User Guide...
Page 70
BillingCode: "" CPAutoSwitch: 0 PictureMode: 4Split VideoFormat: Auto CustomFormats: On AGC: On AllowIncomingCalls: On Duration: 0 MaxAudioSites: 8 MaxVideoSites: 40 EntryExitTones: On LegacyLevel: 0 TelephoneFilter: On FloorToFull: On WebCallListTimeout: Off BandwidthThreshold: 128 NetworkId: 1 ConferenceSelfview: On TANDBERG MPS API User Guide...
Page 72
Top level attributes: None Summary: • Returns current IP and Ethernet information for the Media Boards. Address 1 (type=NA): "" Address 2 (type=NA): "" Address: "10.0.0.2" Address: "127.0.0.1" Address: "127.0.0.1" Address: "127.0.0.1" Address: "0.0.0.0" Name: "" TANDBERG MPS API User Guide...
Page 73
*s/end SystemUnit Top level attributes: None Summary: • Returns information about the System Unit Example *s SystemUnit: ProductType: "TANDBERG MPS-MCU" ProductId: "TANDBERG MPS200" Uptime: 600587 UptimeStr: "6 days 22 hours 49 minutes 47 seconds" Software: Hardware: Address: "10.47.9.106" SubnetMask: "255.255.248.0"...