TANDBERG 3.0 manuale d’uso

Reference guide Codian Remote Management API Document version 3.0 September 2008[...]

Copyright © TANDBERG 2008 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.com[...]

Copyright © TANDBERG 2008 Co nt e n t s 1 Introduc tion ................................................................................................................... ................... 1 1.1 HTTP and HTTPS ............................................................................................................. ..........................[...]

Copyright © TANDBERG 2008 6 ISDN Gatewa y methods ........................................................................................................... ...... 38 6.1 Common structures .......................................................................................................... ......................................... 38 6.2 cal[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 1 1 Intr oduc tion 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 X ML-RPC protocol. XML-RPC is a simple protocol for remote procedure cal[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 2 2 Proto co l over vi ew 2.1 Authentication In order to manage the device, the controlling applicat ion must authenticate itself as a user with relevant privileges. Accordingly, each message contai ns a user name and password; see section 2.4.1 for details of the format. It is worth no[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 3 <member> <name>durationSeconds</name> <value> <int>3600</int> </value> </member> </struct> </value> </param> </params> </methodCall> If the command was successful, the MCU sends a success re sponse. For exam[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 4 </member> <member> <name>faultString</name> <value> <string>duplicate conference name</string> </value> </member> </struct> </value> </fault> </methodResponse> The complete list of command messages, their re[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 5 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 se[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 6 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 repe ated while the device continues to pro[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 7 Operator Description - Unary minus + Unary plus ! Logical negation ~ Bitwise negation An example filter would be !( expression 1 && expression 2 )[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 8 3 Messages suppor ted by multiple product t ypes The methods in this section are co mmon to many devices, including vi deo conferencing servers, IP VCR products, ISDN GW products, and IP GW products. No t all methods are supported by all product types, and not all fields will be prese[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 9 Field Type Comments domainName (optional) String The domain name of this port. nameServer (optional) String a.b.c.d format. nameServerSecondary (optional) String a.b.c.d format. linkStatus Boolean true if the link is up, false if the link is down. speed Integer one of 10, 100 or 1000,[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 10 The "log" array consists of structures which contai n 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.q[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 11 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[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 12 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 tr ue, this endpoint will use box-wide default motion sharp[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 13 This method returns: Response Type Comments enumerateID (optional) String 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. gateways array of structs See below for details. The array “gateways[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 14 4 C onfer enc e rela ted methods Methods in this section are only implemented on produc ts, such as the Codian MCU 4200 seri es, which act as a video conferencing server. Throughout this sect ion, the term MCU refers to any such device. 4.1 conference.create Parameter Type Comments c[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 15 Parameter Type Comments reservedVideoPorts (optional) Integar repetition(optional) String One of: none , daily , weekly , everyTwoWeeks or monthly . weekDay(optional) String Must be prese nt if repetition is monthly . One of monday , tuesday , wednesday , thursday , friday , saturday[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 16 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 flo[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 17 Parameter Type Comments weekDays String terminationType String terminationDate dateTime.iso8601 numberOfRepeats Integer h239Important Boolean Optional. Sets the h239 channel to be important. locked Boolean Optional. Locks or unlocks the conference. customLayoutEnabled Boolean newPart[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 18 Valid expressions within the enumerate filter are as follows: Expression Type Comments active Boolean True if the conference is active. completed Boolean True if the conference has finished. scheduled Boolean True if the conference is a scheduled conference (regardless of if it has b[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 19 Field Type 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 cont rol setting for this conference. See the chai[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 20 4.6 conference.streaming.query This returns some details on the current st ate of streaming viewers for a conference. Parameter Type Comments conferenceName String Name of the conference from which streaming information is required. This will return a structure with the following fie[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 21 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 conferenc e of that name. 4.7 conference.streaming.modify Modifies the current l[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 22 4.9 conference.paneplacement.modify Modifies the pane placement configuration of a particular conferen ce. Parameter Type Comments conferenceName String Name of th e conference to be queried. enabled (optional) Boolean true to enab le pane placement, false to disable. panes (optional[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 23 Parameter Type Comments (optional) the only protocols th at the API can currently use. participantType (optional) String 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 parti cipants can only b[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 24 Parameter Type Comments form suitable for a widescreen (16:9) display. videoTxMaxResolution String One of: cif , 4cif or max . videoRxMaxResolution String Same as above. autoConnect Boolean If this is true and a participant whose e164, dns, or IP address matches this participant’s [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 25 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 pa rticipant in a conference (activeState). For example, if the parameter layoutC ontrolEnabled is included in a [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 26 Parameter Type Comments important (optional) Boolean This setting shoul d not be present if operationScope is "configuredState". Specifies whether this participant is important. audioTxMuted Boolean This setti ng should not be present if operationScope is "configuredSt[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 27 Parameter Type Comments participantProtocol String participantType String newConferenceName String 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[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 28 Field Type Comments participantType String conferenceName String autoAttendantUniqueId String connectionUniqueId Integer Correspon ds to the uniqueId returned by a conference or autoattendant. currentState (optional) Struct The current state of the participant as used by the MCU. Det[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 29 Field Type Comments address String gatewayAddress String The address used to co nnect to the remote endpoint in question. Only returned when the address is known (i.e. the participant was or is to be called out by the MCU, or the participant is an ad_hoc participant calling in which [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 30 Field Type Comments audioRxGainMillidB Integer Only pr esent if the audioRxGainMode is fixed . audioTxMuted Boolean true if audi o is not being transmitted to this participant. videoRxCodec String videoRxLost Integer videoRxReceived Integer videoTxCodec String videoTxReportedLost Int[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 31 Field Type Comments callIdentifier base64 The h323 id of this caller. borderWidth Integer 0 (no border), or 1, 2, or 3 for +1/+2/+3. autoAttendantConfiguredName String If this participant is connected to an auto attendant, this field holds the name of that auto attendant: the valu e [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 32 Parameter Type Comments verticalPosition (optional) String Specifies where to show the message: “top”, “middle” or “bottom”. Message is always horizontally centered, and omitting this parameter is equivalent to choosing “middle”. durationSeconds (optional) Integer The[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 33 This method returns: Response Type Comments enumerateID(optional) String The value whic h 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. autoAttendants array of structs See below for contents. and an ar[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 34 5 IP VCR methods Methods in this section are present only where the pro duct 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 rec[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 35 5.3 recording.delete This method deletes a record ing from the IP VCR. Parameter Type Comments recordingId Integer The recording ID for the recording to delete. This should be the identi fier as returned by recording.enumerate. A "no such recording" fault is return ed if th[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 36 5.5 recording.stop This method stops a recording in progre ss on the IP VCR software version 2.2(1.15) and later. The connection between the IP VCR and the endpoi nt (or endpoints) involved in the call will be dropped. Parameter Type Comments recordingId Integer The recording ID for [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 37 Field Type Comments pointToPointIncomingPrefix String pointToPointOutgoingPrefix String The folder’s configured point to point recordi ng prefixes. These values are only present with IP VCR software version 2.3 and later.[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 38 6 ISDN Gate way methods The following methods are present on ISDN gate way products, such as the ISDN GW 3220. 6.1 Common structures Participant records Several functions return participant reco rds, which have the following fields: Field Type Comments uniqueId Integer A uni que inde[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 39 6.2 calls.active.enumerate Returns a list of all currently ac tive calls on the ISDN gateway. Parameter Type Comments enumerateID (optional) String An enumer ateID, as specified in section 2. This returns the following structure: Response Type Comments enumerateID (optional) String A[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 40 The calls structure contains the following members: Field Type Comments uniqueId Integer A unique identifier for this call. participantOne Struct participantTwo Struct Participant identification structures, as defined in common structures above. startTime dateTime.iso8601 The start t[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 41 Response Type Comments the search order is low to high. directoryNumber String The directory number of this port. The bChannels structure has the following members: Field Type Comments id Integer The channel index. active Boolean True if this channel is active. voice Boolean True if [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 42 7 IP Gatewa y 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 Type Comments corpdirURI String The full path of [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 43 8 Depreca ted messages These messages were supported in ve rsion 1.0 of the MCU 4200 Series Mana gement 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 [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 44 Response Type Comments displayName String The name used by the endpoint to identify itself. This may be different to the participantName. Only returned when the participant is connected. address String The address used to connect to the remote endpoint in question. Only returned wh e[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 45 Response Type Comments deferConnection Boolean displayName string The name used by the endpoint to identify itself. This may be different to the participantName. Only available after the participant has connected. displayNameOverrideStatus Boolean Indicates whether the displayName va[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 46 Response Type Comments participant - see appendi x A. This parameter will be present only for participants configured via the API. currentLayout Integer Actual layout in use for the video stream being sent by the MCU to this participant. This parameter will not be present if the part[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 47 9 Relat ed informa tion sources 9.1 system.xml While not strictly part of the XML-RPC API, some in formation 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 [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 48 10 Required user privileges The following table summarises which users are permit ted to perform which remote management operations. Method Valid users device.query Any user with administrator privileges. device.network.query Any user wi th administrator privileges. device.health.que[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 49 11 Fa u l t c o d e s 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 whic h faults may occur, below is a description of all possible fault codes us[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 50 Fault Code Description correct type, but falls ou tside 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 &q[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 51 12 P ar ticipant disc onnec t reasons These are the possible values of the “disconnectRe ason” field in participant informa tion responses: Value Description Unspecified unspecifiedError remoteTeardown localTeardown noAnswer Moved Rejected rejectedImmediately Busy Timeout gatekee[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 52 13 Refer enc es [1] XML-RPC, http://www.xmlrpc.com/ [2] RFC 2616, http://www.faqs.org/rfcs/r fc2616.html[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 53 Appendix A - C onfer enc e lay outs The participant.add and participant.modify methods allow a particul ar 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 [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 3.0 54 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 55 Appendix B - Linking confer enc es across MCU s For the purposes of this description, two conferences are said to be "li nked" if there is a bi-direct ional H.323 connection between them and each MCU is sending a vide o channel to the other, showing the active speaker full [...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 56 <string>admin</string> </value> </member> <member> <name>conferenceName</name> <value> <string>linked1</string> </value> </member> <member> <name>conferenceID</name> <value> <string>[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 57 B.3 Example message 3 - calling into "linked2" from "linked1" <?xml version="1.0"?> <methodCall> <methodName>participant.add</methodName> <params> <param> <value> <struct> <member> <name>authent[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 58 B.4 Example message 4 - setting the new "linked2" participant to use a full screen view layout <?xml version="1.0"?> <methodCall> <methodName>participant.modify</methodName> <params> <param> <value> <struct> <memb[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 59 B.5 Message responses The response to each of the ab ove method invocations should be the same normal success indication: <?xml version="1.0"?> <methodResponse> <params> <param> <value> <struct> <member> <name>status</name&[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 60 Appendix C - Revision Numbers Note : This feature is available from API version 2.4 onwa rds. 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[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 61 There are two solutions to this proble m; the first is the listAll parame ter 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 limit[...]

Copyright © TANDBERG 2008 Reference Guide Version 3.0 rev 1.0 62 Appendix D - HT TP K eep-alives Note : This feature is available fr om API version 2.4 onwards. Another method of reducing the amount of TCP traffic wh en polling the MCU (see Appendix C ) via the API is to use HTTP keep-alives. This method can be used with other Codian products th a[...]