Summary of the content on the page No. 1
Reference guide
Codian Remote
Management API
Document version 3.0
September 2008
Summary of the content on the page No. 2
TANDBERG Philip Pedersens vei 20 1366 Lysaker Norway Telephone: +47 67 125 125 Telefax: +47 67 125 234 Video: +47 67 117 777 tandberg@tandberg.com E-mail: www.tandberg.com Copyright © TANDBERG 2008
Summary of the content on the page No. 3
Contents 1 Introduction ...................................................................................................................................... 1 1.1 HTTP and HTTPS............................................................................................................................................................ 1 1.2 XML-RPC...................................................................................................................................................
Summary of the content on the page No. 4
6 ISDN Gateway methods ................................................................................................................. 38 6.1 Common structures...................................................................................................................................................38 6.2 calls.active.enumerate..............................................................................................................................................39 6.3 calls.com
Summary of the content on the page No. 5
1 Introduction This document contains the specification of the TANDBERG Codian Remote Management API, by which it is possible to control several Codian products. This is accomplished via messages sent using the XML-RPC protocol. XML-RPC is a simple protocol for remote procedure calling using HTTP as the transport and XML as the encoding. It is designed to be as simple as possible, whilst allowing complex data structures to be transmitted, processed and returned. XML-RPC has no platfor
Summary of the content on the page No. 6
2 Protocol overview 2.1 Authentication In order to manage the device, the controlling application must authenticate itself as a user with relevant privileges. Accordingly, each message contains a user name and password; see section 2.4.1 for details of the format. It is worth noting that authentication information is sent using plain text and should only be sent over a trusted network. 2.2 Message flow An application can create and manage conferences by sending command messages to the d
Summary of the content on the page No. 7
durationSeconds 3600 If the command was successful, the MCU sends a success response. For example, in response to a successful conference.create message, the MCU returns: HTTP/1.1 200 OK Connection: close Content-Type: text/xml Content-Length: 240 status <
Summary of the content on the page No. 8
faultString duplicate conference name The complete list of command messages, their required and optional parameters, and the expected responses are detailed in the sections below. The possible fault codes are listed in section 11. Appendix B - contains examples of some messages and their correspondin
Summary of the content on the page No. 9
2.4.2 Participant identification parameters The following parameters appear in the majority of conference control messages, and identify a specific participant on which operations are to be performed. The use of “MCU” below refers to any device which acts as a videoconferencing server. Parameter Type Description participantName String This is an “internal” name, and therefore is not necessarily related to any name configured on an endpoint. Within the scope of a particular conference
Summary of the content on the page No. 10
3. If there is an enumerateID, the client should call the enumerate method again, with any parameters that are required or desired, and an enumerateID parameter containing the ID returned by the device from the previous call. This should be repeated while the device continues to provide new enumerateID values in responses. 4. After all data is returned, the device will reply with all remaining results, but no enumerateID. This method should only be called using enumerateID values as pro
Summary of the content on the page No. 11
Operator Description - Unary minus + Unary plus ! Logical negation ~ Bitwise negation An example filter would be !(expression && expression ) 1 2 Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 7
Summary of the content on the page No. 12
3 Messages supported by multiple product types The methods in this section are common to many devices, including video conferencing servers, IP VCR products, ISDN GW products, and IP GW products. Not all methods are supported by all product types, and not all fields will be present in responses from all products. 3.1 device.query There are no parameters passed with this method call. The method response returns the following: Parameter Type Comments currentTime dateTime.iso8601 The sys
Summary of the content on the page No. 13
Field Type Comments domainName (optional) String The domain name of this port. nameServer (optional) String a.b.c.d format. nameServerSecondary String a.b.c.d format. (optional) linkStatus Boolean true if the link is up, false if the link is down. speed Integer one of 10, 100 or 1000, in Mbps. fullDuplex Boolean true if full duplex enabled, false if half. macAddress String a 12 character string, no separators. packetsSent Integer Stats from the web interface. It is worth noting that
Summary of the content on the page No. 14
The "log" array consists of structures which contain the following fields. Field Type Comments time dateTime.iso8601 The time of the last reboot. reason String The reason for the reboot (one of unknown, User requested shutdown or User requested upgrade). 3.5 gatekeeper.query Retrieves the gatekeeper settings and current status for an MCU or IP VCR. Takes no parameters. Response Type Comments gatekeeperUsage String One of disabled, enabled or required. The following parameters are
Summary of the content on the page No. 15
Response Type Comments currently configured SIP proxy. conferenceRegistration String This value is only present if the device being queried is an MCU. It will be enabled if the MCU is configured to register conferences’ numeric IDs with the configured SIP registrar, and disabled if not. The enabled value corresponds to “SIP registration settings” being set to “Allow conference registration” on the Settings > SIP page. 3.7 addressBookEntry.enumerate Enumerates configured endpoints
Summary of the content on the page No. 16
Field Type Comments name String Endpoint name. address String IP address. e164 String E.164 number. The structure conferencingParameters contains the following fields: Field Type Comments useDefaultMotionSharpness Boolean If true, this endpoint will use box-wide default motion sharpness settings. minFrameRateMotionSharpness Integer Only present if useDefaultMotionSharpness is false. Specifies the minimum frame rate for this endpoint. useDefaultVideoTransmitResolutions Boolean
Summary of the content on the page No. 17
This method returns: Response Type Comments enumerateID String The value which should be used in the next call to get (optional) the next set of data. If this is omitted, no further data is available from the MCU. gateways array of structs See below for details. The array “gateways” contains structs with the following fields: Field Type Comments name String The name of the configured gateway. address String (< The gateway’s E.164 directory number, 32 chars) hostname or IP addre
Summary of the content on the page No. 18
4 Conference related methods Methods in this section are only implemented on products, such as the Codian MCU 4200 series, which act as a video conferencing server. Throughout this section, the term MCU refers to any such device. 4.1 conference.create Parameter Type Comments conferenceName String (<32 Name of the conference to be created. chars) The conference name must be unique. numericId (optional) String (<32 Numeric identifier of the conference. chars) conferenceId (deprecated)
Summary of the content on the page No. 19
Parameter Type Comments reservedVideoPorts (optional) Integar repetition(optional) String One of: none, daily, weekly, everyTwoWeeks or monthly. weekDay(optional) String Must be present if repetition is monthly. One of monday, tuesday, wednesday, thursday, friday, saturday or sunday. Note that if repetition is not weekly or everyTwoWeeks, the "weekDays" parameter should be used. whichWeek(optional) String Must be present if repetition is monthly. One of: first (the first X of the
Summary of the content on the page No. 20
Parameter Type Comments chairControl (optional) String The chair control setting for the conference. This can be none, floorControlOnly or chairAndFloorControl - these values correspond to the web interface "Floor and chair control" setting values of "Do not allow floor or chair control", "Allow floor control only" and "Allow floor and chair control" respectively. If not specified, the chair control setting for the new conference will be "Allow floor control only". This field is o
