TANDBERG Codian Remote Management API Reference Manual

Manual is about: TANDBERG Monitor Reference Guide

Page of 66

Download

Print this page

Bookmark us

Reference guide

Codian Remote

Management API

Document version 3.0

September 2008

1 2 3 4 5 6 7 Next › »

Summary of Codian Remote Management API

Page 1
Reference guide codian remote management api document version 3.0 september 2008.
Page 2
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.
Page 3: Contents
Copyright © tandberg 2008 contents 1 introduction ...................................................................................................................................... 1 1.1 http and https..................................................................................................
Page 4
Copyright © tandberg 2008 6 isdn gateway methods ................................................................................................................. 38 6.1 common structures ...................................................................................................................
Page 5: Introduction
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 1 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...
Page 6: Protocol Overview
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 2 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....
Page 7
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 3 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-...
Page 8: 2.3
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 4 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. Appen...
Page 9
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 an...
Page 10
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 shou...
Page 11
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 ).
Page 12: 3.1
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 8 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 pro...
Page 13: 3.3
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 li...
Page 14: 3.5
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 10 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...
Page 15: 3.7
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 wit...
Page 16: 3.8
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 true, this...
Page 17
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 str...
Page 18: Conference Related Methods
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 14 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 c...
Page 19
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 present if repetition is monthly . One of monday , tu...
Page 20: 4.2
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" s...
Page 21: 4.3
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 th...
Page 22
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 ...
Page 23
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 c...
Page 24: 4.6
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 20 4.6 conference.Streaming.Query this returns some details on the current state of streaming viewers for a conference. Parameter type comments conferencename string name of the conference from which streaming information is required. Thi...
Page 25: 4.7
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 conference of that name. 4.7 conference.S...
Page 26: 4.9
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 conference. Parameter type comments conferencename string name of the conference to be queried. Enabled (optional) boolean true to enable pan...
Page 27
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 23 parameter type comments (optional) the only protocols that 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 ...
Page 28: 4.11
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,...
Page 29: 4.12
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 participant in a conference (activestate). For example, if the p...
Page 30: 4.13
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 26 parameter type comments important (optional) boolean this setting should not be present if operationscope is "configuredstate". Specifies whether this participant is important. Audiotxmuted boolean this setting should not be present if...
Page 31: 4.16
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 preconfigu...
Page 32
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 28 field type comments participanttype string conferencename string autoattendantuniqueid string connectionuniqueid integer corresponds to the uniqueid returned by a conference or autoattendant. Currentstate (optional) struct the current ...
Page 33
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 29 field type comments address string gatewayaddress string the address used to connect 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 partic...
Page 34
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 30 field type comments audiorxgainmillidb integer only present if the audiorxgainmode is fixed . Audiotxmuted boolean true if audio is not being transmitted to this participant. Videorxcodec string videorxlost integer videorxreceived inte...
Page 35: 4.17
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 h...
Page 36: 4.19
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”. Durat...
Page 37: 4.21
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 33 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, then no further data is available from the mcu. Autoattendants ar...
Page 38: Ip Vcr Methods
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 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 record...
Page 39: 5.3
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 35 5.3 recording.Delete this method deletes a recording from the ip vcr. Parameter type comments recordingid integer the recording id for the recording to delete. This should be the identifier as returned by recording.Enumerate. A "no suc...
Page 40: 5.5
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 36 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 type com...
Page 41
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 recording prefixes. These values are only present with ip vcr software version 2.3 and later..
Page 42: Isdn Gateway Methods
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 38 6 isdn gateway methods the following methods are present on isdn gateway products, such as the isdn gw 3220. 6.1 common structures participant records several functions return participant records, which have the following fields: field...
Page 43: 6.2
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 39 6.2 calls.Active.Enumerate returns a list of all currently active calls on the isdn gateway. Parameter type comments enumerateid (optional) string an enumerateid, as specified in section 2. This returns the following structure: respons...
Page 44: 6.4
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 structu...
Page 45
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 ...
Page 46: Ip Gateway Methods
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 42 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 t...
Page 47: Deprecated Messages
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 43 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”...
Page 48: 8.3
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 th...
Page 49
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. Displaynameoverridest...
Page 50
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 46 response type comments participant - see appendix 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...
Page 51: Related Information Sources
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 47 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. H...
Page 52: Required User Privileges
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 48 10 required user privileges the following table summarises which users are permitted to perform which remote management operations. Method valid users device.Query any user with administrator privileges. Device.Network.Query any user w...
Page 53: Fault Codes
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 49 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 d...
Page 54
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 50 fault code 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 fo...
Page 55
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 51 12 participant disconnect reasons these are the possible values of the “disconnectreason” field in participant information responses: value description unspecified unspecifiederror remoteteardown localteardown noanswer moved rejected r...
Page 57
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 53 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 ...
Page 59: B.1
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 55 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,...
Page 60: B.2
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 56 admin conferencename linked1 conferenceid 1234 b.2 example message 2 - creating conference "linked2" on "mcu2" conference.Create authenticationuser admin conferencename linked2 conferenceid 5678.
Page 61: B.3
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 57 b.3 example message 3 - calling into "linked2" from "linked1" participant.Add authenticationuser admin conferencename linked1 participantname remote_mcu address 5678 gatewayaddress 10.2.1.27 cplayout layout1.
Page 62: B.4
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 participant.Modify authenticationuser admin conferencename linked2 participantname 1_codian mcu 4210 operationscope active cplayout layout1.
Page 63: B.5
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 59 b.5 message responses the response to each of the above method invocations should be the same normal success indication: status operation successful.
Page 64: C.1
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 onwards. An application can determine the api version supported by a device from the apiversion value returned in the response to a device.Query reques...
Page 65: C.2
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 61 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 re...
Page 66
Copyright © tandberg 2008 reference guide version 3.0 rev 1.0 62 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...