Reference guide Codian Remote Management API Document version 3.
TANDBERG Philip Pedersens vei 20 1366 Lysaker Norway Telephone: +47 67 125 125 Telefax: +47 67 125 234 Video: +47 67 117 777 E-mail: tandberg@tandberg.com www.tandberg.
Contents 1 Introduction ...................................................................................................................................... 1 HTTP and HTTPS............................................................................................................................................................ 1 XML-RPC..........................................................................................................................................................................
6 ISDN Gateway methods ................................................................................................................. 38 6.1 Common structures ...................................................................................................................................................38 6.2 calls.active.enumerate ..............................................................................................................................................39 6.3 calls.completed.
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.
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 device.
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
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 corresponding responses. 2.
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.
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 provided by the device.
Operator + ! ~ Description Unary minus Unary plus Logical negation Bitwise negation An example filter would be !(expression1 && expression2) Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.
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 currentTime restartTime Type dateTime.iso8601 dateTime.
Field domainName (optional) nameServer (optional) nameServerSecondary (optional) linkStatus speed fullDuplex macAddress packetsSent packetsReceived multicastPacketsSent multicastPacketsReceived bytesSent bytesReceived queueDrops collisions transmitErrors receiveErrors bytesSent64 bytesReceived64 Type String String String Comments The domain name of this port. a.b.c.d format. a.b.c.d format.
The "log" array consists of structures which contain the following fields. Field time reason Type Comments dateTime.iso8601 The time of the last reboot. 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.
Response Type conferenceRegistration String Comments currently configured SIP proxy. 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 on an MCU or IP VCR.
Field name address e164 Type String String String Comments Endpoint name. IP address. E.164 number.
This method returns: Response enumerateID (optional) Type String gateways array of structs Comments The value which should be used in the next call to get the next set of data. If this is omitted, no further data is available from the MCU. See below for details. The array “gateways” contains structs with the following fields: Field name address conferencingParameters Type String String (< 32 chars) struct Comments The name of the configured gateway. The gateway’s E.
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 conferenceName numericId (optional) conferenceId (deprecated) registerWithGatekeeper (optional) Type String (<32 chars) String (<32 chars) String (< 32 chars) Boolean Comments Name of the conference to be created.
Parameter reservedVideoPorts (optional) Type Integar repetition(optional) String weekDay(optional) whichWeek(optional) weekDays(optional) terminationType (optional) terminationDate (optional) numberOfRepeats (optional) customLayoutEnabled (optional) newParticipantsCustomLayout (optional) customLayout (optional) Copyright © TANDBERG 2008 Comments One of: none, daily, weekly, everyTwoWeeks or monthly. String Must be present if repetition is monthly.
Parameter chairControl (optional) Type String Comments 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".
Parameter weekDays terminationType terminationDate numberOfRepeats h239Important locked customLayoutEnabled newParticipantsCustomLayout customLayout chairControl enforceMaximumAudioPorts enforceMaximumVideoPorts Type Comments String String dateTime.iso8601 Integer Boolean Optional. Sets the h239 channel to be important. Boolean Optional. Locks or unlocks the conference. Boolean Optional fields, as for the "conference.create" method above. Boolean Integer String Boolean Assumed to be true if absent.
Valid expressions within the enumerate filter are as follows: Expression active completed scheduled Type Boolean Boolean Boolean Comments True if the conference is active. True if the conference has finished. True if the conference is a scheduled conference (regardless of if it has been completed or not). Response enumerateID (optional) Type String conferences array of structs Comments The value which should be used in the next call to get the next set of data.
Field Comments layout is enabled. newParticipantsCustomLayout Boolean True if new participants will use the conference custom layout. private Boolean True if this conference is a private conference. chairControl String The chair control setting for this conference. See the chairControl description in conference.create for an explanation of the values this parameter can take. The following timing fields will be present for scheduled conferences only startTime dateTime.
4.6 conference.streaming.query This returns some details on the current state of streaming viewers for a conference. Parameter conferenceName Type String Comments Name of the conference from which streaming information is required.
height (optional) Integer This method will return a fault code of "no such conference" if there is no active conference with the given name, regardless of the presence a configured but inactive conference of that name. 4.7 conference.streaming.modify Modifies the current layout for streaming viewers for a conference.
4.9 conference.paneplacement.modify Modifies the pane placement configuration of a particular conference. Parameter conferenceName enabled (optional) panes (optional) Type String Boolean array of structs Comments Name of the conference to be queried. true to enable pane placement, false to disable. See below for format of the structures. The panes array contains structures which define a specific pane and its contents. If a pane index is not present in the array, then that pane will remain unchanged.
Parameter (optional) participantType (optional) address gatewayAddress (optional) useSIPRegistrar (optional) Type String string (< 32 chars) string (< 32 chars) Boolean Comments the only protocols that the API can currently use. If present, must be by_address or ad_hoc. Note that if this conference is an ad_hoc conference, this value should also be ad_hoc. Ad hoc participants can only be added to active conferences. The participant’s E.164 directory number, hostname or IP address.
Parameter Type videoTxMaxResolution videoRxMaxResolution autoConnect String String Boolean autoDisconnect Boolean borderWidth suppressDtmf Integer Boolean linkType String Comments form suitable for a widescreen (16:9) display. One of: cif, 4cif or max. Same as above. If this is true and a participant whose e164, dns, or IP address matches this participant’s address dials into the MCU, it will be moved directly to this conference.
4.12 participant.modify Depending on the operationScope parameter below, this call modifies the configuration of a participant (configuredState), or the active state of a participant in a conference (activeState). For example, if the parameter layoutControlEnabled is included in a call to participant.
Parameter important (optional) Type Boolean audioTxMuted Boolean borderWidth (optional) focusType (optional) focusParticipant (optional) Integer String Struct Comments This setting should not be present if operationScope is "configuredState". Specifies whether this participant is important. This setting should not be present if operationScope is "configuredState". 0 (no border), or 1, 2, or 3 for +1/+2/+3. One of: voiceActivated, h239 or participant. A participant identification structure (i.e.
Parameter participantProtocol participantType newConferenceName Type String String String Comments The name of the conference to move the participant to. This will only move an active participant. Even if this participant is preconfigured, the configuration is unchanged. A fault code of "no such participant" is returned if the participant is not moved or does not exist. 4.16 participant.enumerate This method is used to return data about participants in conferences on the MCU.
Field participantType conferenceName autoAttendantUniqueId connectionUniqueId Type String String String Integer currentState (optional) Struct configuredState (optional) Struct Comments Corresponds to the uniqueId returned by a conference or autoattendant. The current state of the participant as used by the MCU. Details of this struct are given below. This is only present if requested in the operationScope The stored configuration of the participant, if any. Details of this struct are given below.
Field address gatewayAddress Type String String ipAddress String displayName string displayNameOverrideStatus Boolean maxBitRateToMCU maxBitRateFromMCU motionSharpnessTradeoff Integer Integer String callState String connectTime dateTime.iso8601 disconnectTime dateTime.
Field audioRxGainMillidB Type Integer audioTxMuted Boolean videoRxCodec videoRxLost videoRxReceived videoTxCodec videoTxReportedLost videoTxSent videoRxMuted videoTxWidescreen autoDisconnect important activeSpeaker String Integer Integer String Integer Integer Boolean Boolean Boolean Boolean Boolean layoutControlEnabled activeConferenceId Boolean String currentLayout Integer layoutSource String callDirection String previewURL String focusType String focusParticipant Struct Copyright © TA
Field callIdentifier borderWidth autoAttendantConfiguredName Type base64 Integer String mediaEncryption String audioRxEnergyMillidB Integer audioRxMutedRemotely Boolean Comments The h323 id of this caller. 0 (no border), or 1, 2, or 3 for +1/+2/+3. If this participant is connected to an auto attendant, this field holds the name of that auto attendant: the value will change as the user navigates through an MCU’s configured menu structure.
Parameter verticalPosition (optional) Type String durationSeconds (optional) Integer Comments Specifies where to show the message: “top”, “middle” or “bottom”. Message is always horizontally centered, and omitting this parameter is equivalent to choosing “middle”. The length of time, in seconds, to display the message. This defaults to 30 seconds. 4.19 participant.diagnostics Returns diagnostic information about a given participant.
This method returns: Response Type enumerateID(optional) String autoAttendants array of structs Comments The value which should be used in the next call to get the next set of data. If this is omitted, then no further data is available from the MCU. See below for contents. and an array called “autoAttendants” of structs which contains: Response Type autoAttendantUniqueID String autoAttendantConfiguredName String startTime Comments dateTime.
5 IP VCR methods Methods in this section are present only where the product supports video recording and playback, such as the Codian IP VCR 2200 Series. Throughout this section, any such product is referred to as an IP VCR. 5.1 recording.callout This replicates the call out and record functionality from the web interface.
5.3 recording.delete This method deletes a recording from the IP VCR. Parameter recordingId Type Integer Comments The recording ID for the recording to delete. This should be the identifier as returned by recording.enumerate. A "no such recording" fault is returned if the recording does not exist. 5.4 recording.enumerate This function enumerates the recordings stored on the IP VCR.
5.5 recording.stop This method stops a recording in progress on the IP VCR software version 2.2(1.15) and later. The connection between the IP VCR and the endpoint (or endpoints) involved in the call will be dropped. Parameter recordingId Type Integer Comments The recording ID for the recording to stop. This should be the recordingId as returned by recording.enumerate.
Field pointToPointIncomingPrefix Type String pointToPointOutgoingPrefix String Copyright © TANDBERG 2008 Comments The folder’s configured point to point recording prefixes. These values are only present with IP VCR software version 2.3 and later. Reference Guide Version 3.0 rev 3.
6 ISDN Gateway methods The following methods are present on ISDN gateway products, such as the ISDN GW 3220. 6.
6.2 calls.active.enumerate Returns a list of all currently active calls on the ISDN gateway. Parameter enumerateID (optional) Type String Comments An enumerateID, as specified in section 2. This returns the following structure: Response enumerateID (optional) calls Type String array of struct Comments An enumerateID, as specified in section 2. See below for layout of the structures.
The calls structure contains the following members: Field uniqueId participantOne participantTwo startTime endTime voiceCall Type Integer Struct Struct dateTime.iso8601 dateTime.iso8601 Boolean aggregationCall Boolean encryption String ISDN encryption String maxDuration Integer calledNumber String Comments A unique identifier for this call. Participant identification structures, as defined in common structures above. The start time of the call The end time of the call.
Response Type directoryNumber String Comments the search order is low to high. The directory number of this port. The bChannels structure has the following members: Field id active voice Type Integer Boolean Boolean incoming Boolean calling called String String Comments The channel index. True if this channel is active. True if this a voice call, false if a data call. Only present if active. True if this call is incoming, false if outgoing. Only present if active. Only present if active.
7 IP Gateway methods The following methods are present on the IP GW 3500 Series and MSE IP GW 8350 blade. 7.1 corpdirURI.query There are no parameters passed with this method call. The method response returns the following: Parameter corpdirURI Type String Comments The full path of the TMS address book. 7.2 corpdirURI.configure Configures the path to the TMS address book. Parameter corpdirURI Copyright © TANDBERG 2008 Type String Comments The full path of the TMS address book.
8 Deprecated messages These messages were supported in version 1.0 of the MCU 4200 Series Management API, but have since been superseded. 8.1 system.query This method is deprecated in favour of “device.query” and “conference.enumerate”. There are no parameters passed with this method call. The method response returns the following: Parameter currentTime restartTime Type dateTime.iso8601 dateTime.iso8601 Comments The system’s current time. The date and time at which the system was last restarted.
Response displayName Type String address String callState String connectTime disconnectTime disconnectReason dateTime.iso8601 dateTime.iso8601 String Comments The name used by the endpoint to identify itself. This may be different to the participantName. Only returned when the participant is connected. The address used to connect to the remote endpoint in question. Only returned when the address is known.
Response deferConnection displayName Type Boolean string Comments The name used by the endpoint to identify itself. This may be different to the participantName. Only available after the participant has connected. Indicates whether the displayName value is the result of being overridden. As for “participant.add”; in kbps. displayNameOverrideStatus Boolean maxBitRateToMCU maxBitRateFromMCU callState Integer Integer String connectTime dateTime.iso8601 disconnectTime dateTime.
Response Type currentLayout Integer callDirection String Copyright © TANDBERG 2008 Comments participant - see appendix A. This parameter will be present only for participants configured via the API. Actual layout in use for the video stream being sent by the MCU to this participant. This parameter will not be present if the participant is in an auto attendant rather than a conference, nor if the MCU is not currently transmitting video to the participant in question.
9 Related information sources 9.1 system.xml While not strictly part of the XML-RPC API, some information can be retrieved from the system.xml file. This can be downloaded via HTTP as the file system.xml in the root of the unit, i.e. http://TestMCU/system.xml This is only present on MCU, IP VCR and IP GW products. An example is: Codian MCU 4210 MRV1001SM0004B8 1.4(1.2) 6.6(1.
10 Required user privileges The following table summarises which users are permitted to perform which remote management operations. Method device.query device.network.query device.health.query gatekeeper.query conference.enumerate participant.enumerate conference.create conference.destroy conference.modify conference.end conference.streaming.query corpdirURI.query corpdirURI.configure participant.add autoAttendant.enumerate autoAttendant.destroy participant.remove participant.modify participant.
11 Fault codes The MCU has a series of fault codes which are given when a fault occurs during the processing of an XML-RPC request. While individual method descriptions above give some indication of which faults may occur, below is a description of all possible fault codes used within this specification, and the usual interpretations. Fault Code 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 101 102 Description Method not supported. This method is not supported on this device.
Fault Code 103 201 Description correct type, but falls outside the valid values; for example an integer is too high or a string value for a protocol contains an invalid protocol. The parameter in question is given in the fault string in the format "invalid parameter - parameter_name". Malformed parameter. This is given when a parameter of the correct name is present, but cannot be read for some reason; for example the parameter is supposed to be an integer, but is given as a string.
12 Participant disconnect reasons These are the possible values of the “disconnectReason” field in participant information responses: Value Unspecified unspecifiedError remoteTeardown localTeardown noAnswer Moved Rejected rejectedImmediately Busy Timeout gatekeeperError networkError protocolError dnsFailed destinationUnreachable gatekeeperEnded videoPortAllocationExceeded portAllocationExceeded disconnectAll incompatibleVncVersion failedToConnectToServer authenticationFailed serviceUnavailable capabilityNeg
13 References [1] XML-RPC, http://www.xmlrpc.com/ [2] RFC 2616, http://www.faqs.org/rfcs/rfc2616.html Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.
Appendix A - Conference layouts The participant.add and participant.modify methods allow a particular layout to be specified for video sent to that participant via the “cpLayout” parameter. The “cpLayout” string parameter can take the following values: • default - use the MCU’s default view family • family - use the specified layout family; see below • layout - use a specific layout; see below • conferenceCustom - use the conference custom layout.
34 35 36 37 38 39 40 49 50 51 52 53 54 41 55 42 56 57 43 44 58 59 45 46 47 48 Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.
Appendix B - Linking conferences across MCUs For the purposes of this description, two conferences are said to be "linked" if there is a bi-directional H.323 connection between them and each MCU is sending a video channel to the other, showing the active speaker full screen. The audio communicated between the MCUs will be the usual mix of active speakers. For clarification, the linked conferences are given different names (“linked1” and “linked2”) in the explanation, but they can have the same name.
admin conferenceName linked1 conferenceID 1234 B.2 Example message 2 - creating conference "linked2" on "mcu2" conference.
B.3 Example message 3 - calling into "linked2" from "linked1" participant.
B.4 Example message 4 - setting the new "linked2" participant to use a full screen view layout participant.
B.5 Message responses The response to each of the above method invocations should be the same normal success indication: status operation successful Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.
Appendix C - Revision Numbers Note: This feature is available from API version 2.4 onwards. An application can determine the API version supported by a device from the apiVersion value returned in the response to a device.query request. In order to reduce the size of responses when querying the MCU, the following methods support a “revision number” system: f participant.enumerate f conference.enumerate f autoAttendant.
There are two solutions to this problem; the first is the listAll parameter and the second is described in the next section. A client may periodically include the listAll Boolean parameter set to true to indicate that the MCU should return every record available, (enumeration limits still apply so multiple calls using the standard enumeration protocol may be required).
Appendix D - HTTP Keep-alives Note: This feature is available from API version 2.4 onwards. Another method of reducing the amount of TCP traffic when polling the MCU (see Appendix C) via the API is to use HTTP keep-alives. This method can be used with other Codian products that also support the API, such as the IP VCR and ISDN GW.
