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 contents 1 introduction ...................................................................................................................................... 1 1.1 http and https..................................................................................................
Copyright © tandberg 2008 6 isdn gateway methods ................................................................................................................. 38 6.1 common structures ...................................................................................................................
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...
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....
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-...
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...
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...
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...
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 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...
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...
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...
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...
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...
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...
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...
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...
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...
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...
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 ...
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...
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...
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...
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...
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 ...
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,...
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...
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...
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...
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 ...
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...
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...
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...
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...
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...
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...
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...
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...
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..
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...
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...
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...
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 ...
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...
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”...
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...
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...
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...
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...
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...
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...
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...
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...
Copyright © tandberg 2008 reference guide version 3.0 rev 3.0 52 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.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 ...
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 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,...
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.
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.
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.
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.
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...
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...
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...