Home

TANDBERG 3 User's Manual

1. ss 44 8 6 participant ten EE 44 9 Related information SOULCES sisscccssssossssosssossosssscossooneseseresvsenssussonssvesesensvedesrsenstenscesevessvesncenssssesses 47 9 1 ELE 47 10 Required user TE E 48 AAA T E a E E N EAE A 49 12 Participant disconnect reasons moooccconnocononacanocononncconanananocononoccnnonananocononoccononanononcnon econo ncnancccananss 51 13 References52 Appendix A Conference layouts ccscccsssccsssscsssscssscccssscssccsessccscsccscssccscseccscssscsssccscssccsesssssssececs 53 Appendix B Linking conferences across MCUS ssssesssessosssoscsosesosessosssoscsosesosessosssosessssosesossssosssosesse 55 B 1 Example message 1 creating conference linked1 on MCU Tee 55 B 2 Example message 2 creating conference linked2 on MCU2 ee 56 B 3 Example message 3 calling into linked2 from linked1 nn 57 B 4 Example message 4 setting the new linked2 participant to use a full screen view layout 58 B 5 MESES EES EEN 59 Appendix C Revision NUMbEMS sssscssssssocssssssvossssesoosssseseocsesesososssoscsasesosesaonsoseseonsssesoonssonssness SEENEN 60 C 1 Discovering record En TE 60 C 2 Kl ee AA A do 61 Appendix D HTTP Keep alives s sssesssesssossssssssesssesssossssesssesssesssosssossssesesessssssesssossssssssesssesssossssssssessse 62 Copyright TANDBERG 2008 1 Introduction This document contains the specification of the TANDBERG Codian Rem
2. Unary plus Logical negation Bitwise negation An example filter would be expression amp amp expression Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 system s current time UTC restartTime dateTime iso8601 The date and time at which the system was last restarted serial String The serial number of the device software Version String The software version of the running software buildVersion String The build version of the running software model String The model of this device e g Codian MCU 4210 apiVersion String The version number of the API implemented by this device activatedFeatures array of structs Currently only contains a string feature with a short description of the feature total VideoPorts Integer The total number of video ports on the device Only present on MCU and VCR products totalAudioOnlyPorts Integer The total numb
3. videoRxMuted Boolean true means that video from this participant will not be seen by other conference participants videoTx Widescreen Boolean If true the video sent to this participant will be in a Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 23 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 address dials into the MCU it will be moved directly to this conference In order to stop the MCU dialing out to the participant as the conference starts use deferConnection autoDisconnect Boolean When set to true the participant will be disconnected from the conference if another participant disconnects and only participants configured to be automatically disconnected remain in the conference border Width Integer 0 no border or 1 2 or 3 for 1 2 3 suppressDtmf Boolean Whether inband DTMF tones should be suppressed removed from the audio stream being received from this participant linkType String Currently must be one of cascadeSlaveToMaster or default Currently this is only taken note of if participantType is by address All participants in a conference must have a participantName
4. Reference Guide Version 3 0 rev 3 0 Copyright TANDBERG 2008 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 The first step is to set up the two conferences It is important to ensure that the conferences have a numeric id set the conferencelD field in conference create because without this configured field it is not possible to call in directly to a conference In this example both conferences are given a numeric id though strictly it is only necessary on the target MCU i e the one that is called rather than the one calling In this specific example linked1 is set up on mcul and linked2 set up on mcu2 The creation of linked1 is shown in example message 1 and it is configured with numeric id 1234 the creation of linked2 is shown in example message 2 and this conference is given the numeric id 5678 Next a participant needs to be added to the linked1 conference and connected to linked2 on the target MCU The most reliable way to accomplish this whic
5. ccccssscssecssecssecsseecssecssecssesssecssscessecsuecssecesscsssecsscsssesesscesscesuecsaceeaeeesseesseesss 22 410 participant add A 22 ATI participant MEIN OVE nn MR dd AA 24 412 o Sache SS AE AS AASTA 25 4 13 participant CONAN iu ni astaan Soa dtat odia Duan Stan TSONA Aatu au Soan SAO E TARARES iS EAiE Siae 26 4 14 participant disCONNMECt ecssesssscsssssssssssssssecssecsnecsseccsscssscsesssescessccsnecssecssscsssecesscsasessscesscsessceaseesuecsueesaceesscenseesseetse 26 e SEN HarH IPANtMOVE POR rnnnennimn ne uossesceatecsuasaassdsecusesodscoadeve avbssecsbate nissan 26 4 16 AA 27 4 17 A Csiesnssreiennerarnaanai ear a i aan r ian eia 31 4 18 participant Ee GC 31 419 participant diagnostics nn 32 420 autoAttendant enuMerate nn 32 4 21 a toAtt ndant d strOy E 33 5 IPVCERmethod sunni 34 5 1 een ale aldo a 34 5 2 recordio CONGU smart 34 5 3 REENEN 35 5 4 COIN SHUMETALC nia sand nas mono 35 5 5 ee e e nono bilinear 36 5 6 AAA 36 Copyright O TANDBERG 2008 6 ESA ee 38 6 1 Common SUL CLUES is siecscsnccn sacl E iaa 38 6 2 calls active enumerate niining ai i a iaa aare 39 6 3 calls completed enumerate inner 39 6 4 ISG ports UE 40 TAT E DT 42 7 1 COMP CIU Rouen inann AN TS 42 7 2 corpdirURILCONfigU auku luka 42 8 Deprecated messages muuna 43 8 1 Ch Ou 8 57 E 43 8 2 COMO Un E 43 8 3 conference participant modify ire 44 8 4 conference participant rEMOVE ns 44 8 5 conference participant add
6. e Codian MCU products software version 2 3 and later e Codian IP VCR products software version 2 3 and later e Codian ISDN GW products software version 1 4 and later e Codian IP GW products software version 2 0 and later By default HTTPS is provided on TCP port 443 although Codian devices can be configured to receive HTTP and HTTPS connections on non standard TCP port numbers if required The Codian devices implements HTTP 1 1 as defined by RFC 2616 2 1 2 XML RPC For the background and details of XML RPC please refer to the specification 1 In this implementation all parameters and return values are part of a lt struct gt and are all explicitly named For example the device query method returns the current time value as a structure member named currentTime rather than as a single value of type lt dateTime iso8601 gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 For each command sent provided the
7. in the case of configured participants it does not remove the configuration thus allowing later re connection with participant connect gt in the case of ad hoc participants it does not remove the record of the previous connection 4 15 participant move This method is used to move a participant from one conference to another Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 26 Parameter Type Comments participantProtocol String participantType String new ConferenceName 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 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 Several calls may be required to receive data about all participants see the notes on enumeratelD below Parameter Type Comments enumerateFilter String An enumerate filter string optional enumeratelD optional String The value returned by the last enumeration call If this parameter is omitted a new enumeration is started operati
8. 21 autoAttendant destroy Parameter Type Comments autoAttendantUniguelD String Identifier for the auto attendant to be destroyed Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 Parameter Type Comments recordingName optional String The name to be used for the recording If no name is specified a default name is used folderld optional Integer The folder in which this recording is to be placed If not specified the top level folder will be used address String The hostname IP address or e164 number to connect to participantProtocol String Either h323 or sip The protocol to be used for this optional connection This defaults to h323 gatewayAddress optional String The address of an h323 gateway if required Only used if protocol is h323 useSIPRegistrar optional Boolean Only valid if protocol is sip Defaults to false This may give an operation failed fault with a reason given in the fault string if the operation fails In IP VCR release 2 3 and later if this call succeeds then the success response includes the i
9. 4 setting the new linked2 participant to use a full screen view layout lt xml version 1 0 gt lt methodCall gt lt methodName gt participant modify lt methodName gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt authenticationUser lt name gt lt value gt lt string gt admin lt string gt lt value gt lt member gt lt member gt lt name gt conferenceName lt name gt lt value gt lt string gt linked2 lt string gt lt value gt lt member gt lt member gt lt name gt participantName lt name gt lt value gt lt string gt 1_Codian MCU 4210 lt string gt lt value gt lt member gt lt member gt lt name gt operationScope lt name gt lt value gt lt string gt active lt string gt lt value gt lt member gt lt member gt lt name gt cpLayout lt name gt lt value gt lt string gt layout1 lt string gt lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodCall gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 B 5 Message responses The response to each of the above method invocations should be the same normal success indication lt xml version 1 0 gt lt methodResponse gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt status lt name gt lt value gt lt string gt operation successful lt string gt
10. 5 4 recording enumerate This function enumerates the recordings stored on the IP VCR Parameter Type Comments enumeratelD optional String An enumeratelD as specified in section 2 enumerateFilter optional String A filter expression Valid expressions within the enumerate filter are Expression Type Comments recordingld Integer The unique index of this recording internal Boolean True if the recording is stored internally external Boolean True if the recording is stored externally inProgress Boolean True if the recording is in the process of being made This returns the following Response Type Comments enumeratelD optional String An enumeratelD as specified in section 2 recordings array of structures See below for layout of the structures The recordings array contains the following structures Field Type Comments recordingName String The name of this recording recordingld Integer A unique identifier for this recording folderld Integer The unique identifier of the folder in which this recording is stored numericld String The numeric Id registered with the SIP registrar or h323 gatekeeper pin String The PIN of this recording status String The current status of the recording This can be any of the following idle initialising invalid uploading deleting or recording playbackEnabled Bo
11. String operationalStatus String One of active shuttingDown or shutDown 3 4 device restartlog guery Used to return the restart log also known as the system log on the web interface Response Type Comments log arr ay Contains the restart log in structures as described below Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 all optional and will only be present if gatekeeperUsage is not disabled address String The address of the gatekeeper dnsStatus String The status of the DNS resolution one of inProgress resolved or failed ip String If the dnsStatus is resolved contains the IP address of the gatekeeper activeRegistrations Integer The number of active registration pendingRegistrations Integer The number of registrations in progress registrationPrefix String The registration prefix u
12. The conference name must be unique numericld optional String lt 32 Numeric identifier of the conference chars conferenceld deprecated String lt 32 Deprecated alternative for numericld chars register WithGatekeeper optional Boolean Register the conference s numericld with the gatekeeper register WithSIPRegistrar optional Boolean Register this conference with the SIP registrar i startTime optional dateTime iso8601 If you do not specify a time the conference starts immediately durationSeconds optional Integer The length of each repeating conference instance in seconds If this parameter is absent or set to 0 the conference is permanent endTime optional deprecated dateTime iso8601 If you do not specify an end time then the conference will be permanent until itis explicitly deleted This parameter is deprecated and present for backward compatibility reasons only Application code should use durationSeconds instead pin optional String lt 32 If present this is the string of numeric chars digits that people need to enter to join the conference description optional String lt 32 chars multicastStreamingEnabled optional Boolean unicastStreamingEnabled optional Boolean h239Enabled optional Boolean private Boolean Determines the visibility of this conference This parameter corresponds t
13. h323 participants channelCount Integer The number of ISDN channels in use Only present for ISDN participants channels array of integers The channels in use by this call Only present for ISDN participants It is worth pointing out that while in the functions below these structures are called participantOne and participant Two if the call was not initiated by the web interface or API which is not currently possible then participantOne will be the calling party and participant Two the called party Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 38 6 2 calls active enumerate Returns a list of all currently active calls on the ISDN gateway Parameter Type Comments enumeratelD optional String An enumeratelD as specified in section 2 This returns the following structure Response Type Comments enumeratelD optional String An enumeratelD as specified in section 2 calls array of struct See below for layout of the structures The calls structure contains the following fields Field Type Comments uniqueld Integer A unique identifier for this call participantOne Struct Structures containing participant information as participantTwo Struct define in common structures above startTime dateTime iso8601 The start time of the call voiceCall Boolean True if this is a
14. if operationScope is activeState useSipRegistrar Boolean These parameters override the configured values transportProtocol String password String deferConnection Boolean autoConnect Boolean linkType String maxBitRateToMCU Integer maxBitRateFromMCU Integer motionSharpnessTradeoff String One of default if set to the global default optional setting preferMotion preferSharpness and balanced Optional and valid for both configuredState and activeState scopes displayNameOverrideStatus Boolean All of these parameters are optional and override change the values provided in the display NameOverrideValue String participant add call Depending on the value of cpLayout String the operationScope parameter these either if layoutControlEnabled Boolean configuredState change the stored audioRxMuted Boolean configuration of a participant or if activeState audioRxGainMode String change the active participant state resulting in audioRxGainMillidB Integer real time changes to that participant videoRxMuted Boolean videoTxWidescreen Boolean autoDisconnect Boolean suppressDtmf Boolean Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 25 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
15. is endOnGivenDate this is the day that the conference repetition will end on numberOfRepeats optional Integer If terminationType is afterNRepeats this is the number of repeats to end after customLayoutEnabled optional Boolean true if the layout is enabled false otherwise newParticipantsCustomLayout Boolean true if new participants use the custom optional layout false otherwise Only valid if customLayoutEnabled is true customLayout optional Integer A layout index as described in appendix A Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 15 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 only present for MCU software versions 2 2 1 6 onwards Conferences created through the management API will appear in the list of conferences accessible via the web interface and vice versa 4 2 conference modify Parameter Type Comments conferenceName String lt 32 Name o
16. lt fault gt lt methodResponse gt 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 3 Unicode support Parameters in this version of the API can be in ASCII text or unicode UTF8 In order to distinguish between these encodings any of several methods can be used If no method is present ASCII is assumed 2 3 1 HTTP Headers There are two different ways of specifying unicode in the HTTP headers either using Accept Encoding utf 8 or modifying the Content Type header to read Content Type text xml charset utf SH 2 3 2 XML Header At the top of each XML file the lt xml gt tag is required This API will accept an additional encoding parameter with value UTF 8 for this tag i e lt xml version 1 0 encoding UTF 8 gt 2 4 Common message elements 2 4 1 Authentication All messages must contain a user name and password as follows Parameter Type Comments authenticationUser String Name of a user with sufficient privilege for the operation being performed The name is case sensitive authenticationPassword String The corresponding user s password This parameter is ignored if the user has no password set note that this differs from the web interface where a blank passw
17. lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodResponse gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 59 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 gt participant enumerate gt conference enumerate gt autoAttendant enumerate When the MCU responds to a method that supports revision numbers it returns an extra integer field called currentRevision The following is an example of such a field lt member gt lt name gt currentRevision lt name gt lt value gt lt int gt 18 lt int gt lt value gt lt member gt The revision number is a monotonically increasing value that increases every time any query is made on the MCU via the API In order to reduce the size of subsequent query responses the parameter lastRevision may be passed in as part of a request for example lt member gt lt name gt lastRevision lt name gt lt value gt lt int gt 18 lt int gt lt value gt lt member gt This indicates to the MCU that only records that have changed since this revision number
18. message is correctly formatted according to the XML RPC spec the device responds with a message indicating success or failure The response message may also contain any data that was requested Command messages are sent in XML format For example the following message schedules a conference on an MCU to begin at 10 45 on 18 February 2005 and last for one hour POST RPC2 HTIP 1 1 User Agent Frontier 5 1 2 WinNT Host 10 2 1 100 Content Type text xml Content length 713 lt xml version 1 0 gt lt methodCall gt lt methodName gt conference create lt methodName gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt authenticationUser lt name gt lt value gt lt string gt api_test lt string gt lt value gt lt member gt lt member gt lt name gt authenticationPassword lt name gt lt value gt lt string gt 123456 lt string gt lt value gt lt member gt lt member gt lt name gt conferenceName lt name gt lt value gt lt string gt Meeting 1 lt string gt lt value gt lt member gt lt member gt lt name gt startTime lt name gt lt value gt lt dateTime iso8601 gt 20050218T10 45 00 lt dateTime iso8601 gt lt value gt lt member gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 2 lt member gt lt name gt durat ionSeconds lt name gt lt value gt lt int gt 3600 lt int gt lt valu
19. should be returned For example in participant enumerate if a lastRevision parameter is provided then the enumeration response will only include participants that have changed since this revision Note that when using revision numbers with enumerate methods the same lastRevision parameter should be used for each stage of the enumeration even though a greater currentRevision parameter will be returned at each stage Not doing so could result in records which have changed not being returned Likewise having completed an enumeration the only currentRevision parameter which should be stored is the one that was returned with the first stage of the enumeration This is the revision number that should be used as the lastRevision parameter next time an enumeration cycle is started Using the same revision numbers throughout enumerations is necessary to ensure that all records that have changed are reported but it does mean that a record may be reported more than once occasionally when there has only been one change to it C 1 Discovering record removal The problem with only returning records in responses when they have changed is that if a record is removed there is no way for the client to distinguish between it being removed and just not having changed Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 60 There are two solutions to this problem the first is the listAll parameter and the second i
20. that is unique to the conference but it need not be unique across all conferences Participants can be added before or during a conference A participant which is added at any time via the API will be added to the configured list of participants and thus will be called at the start of the conference by the MCU for any conference which has any sort of repetition to avoid this a participant must be removed directly using participant remove Note If a participantName matches the name of an endpoint in the list of configured endpoints via the web interface go to Endpoints the two are treated as unrelated This is because in the web interface named configured endpoints have the participantT ype value by name whereas API participants are of type by_address 4 11 participant remove This call removes a participant from the database of configured participants and also removes this participant from any conferences It will also remove all records of this participant s presence in a conference Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participant Type String Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 24 4 12 participant modify Depending on the operationScope parameter below this call modifies the configuration of a participant config
21. values will be present for active conferences only activeStartTime dateTime iso8601 If the conference is currently active these activeEndTime dateTime iso8601 fields show the time span of the current activation If the conference is permanent then activeEndTime will be absent activeConferenceld string A unique ID for the active instance of this conference this conference will have this ID even if for example the conference is renamed while active but each scheduled instance of this conference will have a different activeConferenceld Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 19 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 This will return a structure with the following fields Response Type Comments unicast Viewers Integer The number of unicast streaming viewers multicast Viewers Integer The number of multicast streaming viewers audioStreams optional Array An array of stream structs defined below These videoStreams optional Array are only present if there are any streams of either type currently in use audioRTCPReceiverReports Integer The number of RTCP receiver reports for th
22. voice only call false for a video call aggregationCall Boolean True if this is an aggregation call false otherwise callProgress String The state of the call One of initial calling out connected or dying encryption String Either a11 some or none depending on the current encryption state of the media channels on the IP side of the call ISDN encryption String Either a11 some or none depending on the current encryption state of the media channels on the ISDN side of the call maxDuration Integer The maximum duration of this call in seconds If there is no maximum this value is 0 calledNumber String The number originally called or unknown if this number is unknown 6 3 calls completed enumerate Returns completed call records from the gateway This function takes no parameters Parameter Type Comments enumeratelD optional String An enumeratelD as specified in section 2 This returns the following structure Response Type Comments enumeratelD optional String An enumeratelD as specified in section 2 calls array of struct See below for layout of the structures Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 39 The calls structure contains the following members Field Type Comments uniqueld Integer A unique identifier for this call participantOn
23. 10 serial The serial number of this MCU softwareVersion The software version currently running buildVersion The build version of the software currently running hostName The host name of the system uptimeSeconds The number of seconds since boot total VideoPorts The total number of video ports on the MCU Not supported on the IP GW totalAudioOnlyPorts The total number of additional audio only ports on the MCU Only optional present if there are any audio only ports Not supported on the IP GW portReservationMode enabled or disabled depending on the Media Port Reservation configuration setting Not supported on the IP GW max VideoResolution The maximum video resolution for the MCU either cif or max if larger video is enabled Not supported on the IP GW Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 47 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 with administrator privileges device health query Any user with administrator privileges gatekeeper guery Any user with administrator privileges conference enumerate Any user with administrator privileges participant enumerate Any user with administrator privileges conference Create Any us
24. 6 Too many conferences The device has reached the limit of the number of conferences that can be configured 7 Too many participants There are already too many participants configured and no more can be created 8 No conference name or auto attendant id supplied A conference name or auto attendant identifier was required but was not present 9 No participant name supplied A participant name is required but was not present 10 No participant address supplied A participant address is required but was not present 11 Invalid start time specified A conference start time is not valid 12 Invalid end time specified A conference end time is not valid 13 Invalid PIN specified A PIN specified is not a valid series of digits 14 Unauthorised The requested operation is not permitted on this device 15 Insufficient privileges The specified user id and password combination is not valid for the attempted operation 16 Invalid enumeratelD value An enumerate ID passed to an enumerate method invocation was invalid Only values returned by the device should be used in enumerate methods 17 Port reservation failure This is in the case that reservedAudioPorts or reservedVideoPorts value is set too high and the device cannot support this 18 Duplicate numeric ID A numeric ID was given but this ID is already in use 19 Unsupported protocol A protocol was used which does not correspond to any valid protocol for this method In particu
25. IP VCR software version 2 3 and later Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 37 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 Type Comments uniqueld Integer A unique index for this participant protocol String Either h323 for IP or h320 for ISDN number String the E164 number IP address or DNS name of the participant Name String The name of this participant e g the h323 name autoAttendant boolean True if this participant is an auto attendant running on the gateway false otherwise incoming boolean True if the call is incoming to the gateway false if the call is outgoing videoCodec String The video codec used for this participant audioCodec String The audio codec used for this participant progress String The state of the connection to this participant One of none initial proceeding alerting connected or finished Only present for active participants Fecc boolean True if far end camera control is established false otherwise Only present for active participants ipAddress String The IP address if the participant Only present for IP participants callldentifier base64 The h323 Call Identifier for this participant Only present for
26. Integer Max media transmit bit rate maxMediaRxBitRate Integer Max media receive bit rate defaultLayout String Refer to appendix A for a list of layouts layoutControlDefault Boolean If true this endpoint will use box wide layout control settings layoutControlEnabled Boolean Only present if layoutControlDefault is false Indicates whether the participant will have control over their layout h239ContributionDefault Boolean If true this endpoint will use box wide h239 contribution settings h239ContributionEnabled Boolean Only present if h239ContributionDefault is false Specifies whether the endpoint will be able contribute h239 initialAudioMuted Boolean Whether this participant would initially have their audio muted initial VideoMuted Boolean Whether this participant would initially have their video muted autoDisconnect Boolean When a participant disconnects from a conference and only participants who have autoDisconnect set to true remain all those participants are disconnected borderWidth Integer 0 no border or 1 2 or 3 for 1 2 3 3 8 gateway enumerate Enumerates configured H 323 gateways on an MCU or IP VCR Parameter Type Comments enumeratelD String The value returned by the last enumeration call If it is optional omitted a new enumeration is started Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 This method returns Response Type Comments en
27. String If present must be h323 sip or vne these are Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 22 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 also be ad_hoc Ad hoc participants can only be added to active conferences address string lt 32 chars The participant s E 164 directory number hostname or IP address gatewayAddress optional string lt 32 chars IP address or hostname of an H 323 gateway useSIPRegistrar optional Boolean Whether to use a registrar in making this a call Ignored if the protocol is not sip transportProtocol String One of default tcp udp or t1s Ignored if the optional protocol is not sip password optional String The password for vnc endpoints deferConnection Boolean If true don t call out to this participant optional immediately but wait for a participant connect command All of the following parameters are optional and control the conferencing behaviour of the MCU with respect to the endpoint in question for example the maximum resolution of the video streams used or whether the participant is able to control their conference view layout maxBitRateToMCU Intege
28. TANDBERG Reference guide Codian Remote Management API Document version 3 0 September 2008 TANDBERG See performance 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 sssnsin ni sissi sistsssss besi ostisssssass bost ssssosti sts ss sss ss 1 1 1 A auch decdddestubabeodd acoseceal dsstexs 1 ME A n a a a S 1 2 Protocol OVEFVICW AA NO 2 2 1 PUES INCI CATION AASMA 2 2 2 eelere EE 2 2 3 Unicode SUP POM iii iii 4 2341 HTTP A rahassa sr EERE LTEN REELE EENE a S EAER RE REE 4 2 352 KML Ee EE 4 2 4 COMMON message Elena mien 4 2 4 1 Tu EE A 2 4 2 Participant identification parameters einen 5 2 4 3 ANA 5 244 FENG nude 6 3 Messages supported by multiple product tYpe s sseeeeeeessessee 8 3 1 NEKE E a ama alla tum aaa a kaid lamava 8 3 2 device NetWork QUA EE 8 3 3 heeten mkm 9 EE M a ELS e 9 3 5 MEPL CS ummistumist aia 10 3 6 lee EE 10 3 7 Ge ne 11 3 8 gateway enumerate cnrs entends k itutakse 12 A Conference related methods E 14 4 1 NN A 14 4 2 cohtefeheemedil ummuksis 16 4 3 COMICS ON mn doi nan 17 44 A EE 17 4 5 conference enumerate EENEG 17 4 6 conference streamMing query cia taa daa 20 4 7 conference streaming modify ii m 21 4 8 conference paneplacement GUEry nee 21 4 9 CONFEereNce paNEplaceMENt MOAIFY
29. The conference enumerate function is used to return some or all conferences scheduled running or completed on the MCU Parameter Type Comments enumeratelD String The value returned by the last enumeration call If it is optional omitted a new enumeration is started enumerateFilter String A filter expression Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 17 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 been completed or not This method returns Response Type Comments enumeratelD 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 conferences array of structs See below for details The array conferences contains structs with the following fields Field Type Comments conferenceName String conferenceType String One of scheduled or ad_hoc uniqueld Integer An id unique among all scheduled and ad hoc conferences each instantiation of a scheduled conference will have the same uniqueld conferenceActive Boolean Indicat
30. ameters passed with this method call The method response returns the following Parameter Type Comments corpdirURI String The full path of the TMS address book 7 2 corpdirURI configure Configures the path to the TMS address book Parameter Type Comments corpdirURI String The full path of the TMS address book Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 Type Comments current Time dateTime iso8601 The system s current time restartTime dateTime iso8601 The date and time at which the system was last restarted The method also returns a conferences lt array gt of lt struct gt for each conference where each lt struct gt contains the following parameters Parameter Type Comments conferenceName String The name of the conference numJoined Integer The number of participants that have ever joined the conference numl eft Integer The number of participants that have ever left the conference The difference between numJoined and numLeft gives the number of cur
31. customLayoutEnabled Boolean Optional fields as for the newParticipantsCustomLayout Boolean conference create method above customLayout Integer chairControl String enforceMaximumAudioPorts Boolean Assumed to be true if absent These can be enforceMaximumVideoPorts Boolean set to false in order to specify no limit on the number of audio video ports Conferences created through the management API will appear in the list of conferences accessible via the web interface Therefore the API can be used to modify conferences scheduled via the web interface and vice versa Note that there is only a very limited amount of control available for ad hoc conferences however 4 3 conference destroy Parameter Type Comments conferenceName String Name of the conference to be destroyed A conference can be destroyed at any time that is before the conference has begun during the conference or after the conference has ended Destroyed conferences are removed entirely from the system this includes all future repetitions of the conference 4 4 conference end Parameter Type Comments conferenceName String Name of the conference to be ended A conference remains in the list of conferences even after the conference has ended until conference destroy is called In particular this can be used to end an instance of a conference without deleting all future repetitions 4 5 conference enumerate
32. dec String audioRxLost Integer audioRxReceived Integer audioTxCodec String audioTxReportedLost Integer audioTxSent Integer audioRxMuted Boolean audioRxGainMode String One of fixed none or automatic Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 29 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 Integer videoTxCodec String videoTxReportedLost Integer videoTxSent Integer videoRxMuted Boolean videoTx Widescreen Boolean autoDisconnect Boolean important Boolean activeSpeaker Boolean true if this participant is currently the active speaker in the conference layoutControlEnabled Boolean activeConferenceld String The active conference ID of the current conference see conference enumerate for details of this field This field is only present if the participant is currently in an active conference currentLayout Integer The 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 or if the MCU is not currently transmitting video to the participant in question The values for this are those described in appe
33. dentification as described above autoAttendantUniqueld String participantName String participantProtocol String participantType String message String The string to send to the participant Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 Parameter Type Comments verticalPosition String Specifies where to show the message top middle optional or bottom Message is always horizontally centered and omitting this parameter is equivalent to choosing middle durationSeconds Integer The length of time in seconds to display the optional message This defaults to 30 seconds 4 19 participant diagnostics Returns diagnostic information about a given participant Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participantType String The method response returns the following Response Type Comments videoTxFrameRate Integer videoRxFrameRate Integer videoRxFramesReceived Integer videoTxChannelBitRate Integer videoTxSelectedBitRate Integer videoTxActualBitRate Integer videoTxLimitReason String One of notLimited viewedSize guality aggregateBandwidth flowControl or endpointLimitation videoRxChannelBitRate Integer
34. e audio streams seen by the MCU audioRT CPSenderReports Integer The number of RTCP sender reports for the audio streams seen by the MCU audioRT CPOther Integer The number of other RTCP packets seen for the audio streams audioRT CPPacketsSent Integer The number of RTCP packets send by the MCU videoRTCPReceiverReports Integer As for the audio equivalents videoRTCPSenderReports Integer videoRTCPOther Integer videoRTCPPacketsSent Integer currentLayout Integer The actual layout in use for the video stream being sent by the MCU to streaming viewers The values for this are described in Appendix A layoutSource String One of family lt x gt conferenceCustom or participantCustom and describes the reason for the current layout focusType String One of participant voiceActivated or h239 focusParticipant Struct A participant identification structure i e with conferenceName participantName participantProtocol and participantT ype members Should only be present if focusT ype is participant border Width Integer 0 no border or 1 2 or 3 for 1 2 3 The stream structures used in the audioStreams videoStreams responses above have the following fields Field Type Comments codec String The codec in use or other for undefined codecs count Integer The number of users of this codec bitRate optional Integer The bit rate of this stream in bits second This is only present for video streams w
35. e Struct Participant identification structures as defined participantTwo Struct in common structures above startTime dateTime iso8601 The start time of the call endTime dateTime iso8601 The end time of the call voiceCall Boolean True if this is a voice only call false for a video call aggregationCall Boolean True if this is an aggregation call false otherwise encryption String Either a11 some or none depending on the current encryption state of the media channels on the IP side of the call ISDN encryption String Either a11 some or none depending on the current encryption state of the media channels on the ISDN side of the call maxDuration Integer The maximum duration of this call in seconds If there is no maximum this value is 0 calledNumber String The number originally called or unknown if this number is unknown The calling and called party are as defined above 6 4 isdn ports query Returns the current status and the settings of an ISDN port The device query call gives the number of ports on the ISDN gateway Parameter Type Comments port Integer The port number to query This is zero based so if there are four ports they are numbered 0 to 3 This function returns the following structure Response Type Comments port Integer The port number type String The interface type One of el j1 t1 or unknown mode String The interface
36. e gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodCall gt 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 lt xml version 1 0 gt lt methodResponse gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt status lt name gt lt value gt lt string gt operation successful lt string gt lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodResponse gt If the command fails the MCU sends a fault response For example in response to a conference create message where the conference name is not unique the MCU returns HTTP 1 1 200 OK Connection close Content Type text xml Content Length 411 lt xml version 1 0 gt lt methodResponse gt lt fault gt lt value gt lt struct gt lt member gt lt name gt faultCode lt name gt lt value gt lt int gt 2 lt int gt lt value gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 lt member gt lt member gt lt name gt faultString lt name gt lt value gt lt string gt duplicate conference name lt string gt lt value gt lt member gt lt struct gt lt value gt
37. eferMotion preferSharpness and balanced audioRxMuted Boolean audioRxGainMode String One of fixed none or automatic audioRxGainMillidB Integer Only returned if audioRxGainMode is fixed videoRxMuted Boolean videoTx Widescreen Boolean layoutControlEnabled Boolean cpLayout String The configured layout behavior for this participant see appendix A autoConnect Boolean Whether or not participants matching this address should be automatically connected to the conference autoDisconnect Boolean Whether or not the participant should be automatically disconnected from the conference when all other participants disconnect border Width Integer 0 no border or 1 2 or 3 for 1 2 3 linkType String One of cascadeSlaveToMaster or default The currentState structure contains the following responses if present Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 28 Field Type Comments address String The address used to connect to the remote gateway Address String 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 provided an address ipAddress String The IP address to which the MCU is connected for this endpoint this will usually be the endpoint itself but may be a gatekeeper or gateway Only pre
38. endpoint dialed in or the MCU dialed out APl created participants in scheduled conferences i e those originated by participant add will be of type by address unless they re added explicitly as temporary ad hoc participants conferenceName String Unigue conference name the conference name space is shared between API generated conferences and all other ad hoc and scheduled MCU conferences autoAttendantUnigueld String If the participant in question is connected to an auto attendant rather than a conference this field contains a unique identifier for that auto attendant When modifying or querying parameters for a specific endpoint participantName participantProtocol and participantType parameters are supplied along with either a conferenceName or an autoAttendantUniqueld The only safe way to find these values is to use the fields returned from participant enumerate 2 4 3 Enumerate functions Due to the potential for a very large number of responses all enumerate functions return an enumerateID response This contains a string value which should be passed to subsequent calls of the same enumerate function in order to retrieve the remainder of the values The use of this parameter is as follows 1 The client computer sends an enumerate call with any necessary parameters e g operationScope and no enumeratelD parameter 2 The device returns with an array containing the requested data and possibly a n
39. er of additional audio only ports on the device Only present on MCU and VCR products portReservationMode String enabled or disabled depending on the Media Port Reservation configuration setting Only present on MCU products maxVideoResolution String One of cif or 4cif Only present on MCU and VCR products isdnPorts Integer The number of ISDN ports Only present on ISDN gateways 3 2 device network query This call takes no parameters The response returns the following Parameter Type Comments YP portA struct see below Contains the configuration and status for port A portB struct see below Contains the configuration and status for port B The format for the two structures above is Field Type Comments enabled Boolean true if the port is enabled otherwise false hostName optional String The host name of this port dhcp optional Boolean true if configured by DHCP otherwise false ipAddress optional String a b c d format subnetMask optional String a b c d format defaultGateway optional String a b c d format Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 tr
40. er with conference creation abilities conference destroy conference modify conference end The owner of the conference or a user with conference creation and full control or administrator privilege P g conference streaming E query The owner of the conference or a user with conference creation and limited control or higher privileges corpdirURI query Any user with administrator privileges corpdirURI configure Any user with administrator privileges participant add Any user with administrator privilege the owner of the conference or a user with conference creation and full control ri ghts autoAttendant enumerate autoAttendant destroy Any user with administrator privileges participant remove participant modify participant move participant diagnostics participant fecc participant message participant connect participant disconnect If the participant is connected to an auto attendant administrator privileges are reguired If the participant is in a conference the user must be the owner of the conference or a user with conference creation and full control or administrator privilege recording callout recording configure recording enumerate folder enumerate Any user with administrator privileges isdn port query calls active query calls comple
41. es whether conference is currently active description String Extra user specified information about the conference pin String The security PIN guestPin String Security pin for a guest numericld String guestNumericld String register WithGatekeeper Boolean register WithSIPRegistrar Boolean multicastStreamingEnabled Boolean unicastStreamingEnabled Boolean h239Enabled Boolean h239Important Boolean Whether the H 239 channel is set to be important locked Boolean Whether the conference is locked or unlocked maximum AudioPorts Integer These fields set the limit on the number of maximum VideoPorts Integer audio audio only and video video audio reservedAudioPorts Integer ports for the conference The reserved reservedVideoPorts Integer values are for port reservation mode whereas the maximum figures apply to non reserved mode and will be absent if no limits have been configured customLayoutEnabled Boolean True if a custom layout has been enabled for this conference customLayout optional Integer The index from appendix A of the custom layout This is only present if the custom Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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
42. ess is known callState String One of dormant alerting connected disconnected connectTime dateTime iso8601 Only returned after the conference has begun disconnectTime dateTime iso8601 Only returned after the participant has disconnected disconnectReason String Only returned after the participant has disconnected Note This participant information is returned for all participants added to the conference using the participant add method even after they have disconnected However this information is only returned for other participants i e those added via the web interface or those who dialed into the conference whilst they are connected but not after they have disconnected 8 3 conference participant modify This method has been deprecated in favour of participant modify See participant modify for details of this function 8 4 conference participant remove This method has been deprecated in favour of participant remove See participant remove for details of this function 8 5 conference participant add This method has been deprecated in favour of participant add See participant add for details of this function 8 6 participant enumerate While this method is not itself deprecated there is deprecated behaviour if there is no operationScope parameter In this case the MCU will return a participant structure with the following members Response Type Com
43. eter is supposed to be an integer but is given as a string The parameter in question is given in the fault string in the format malformed parameter parameter name 201 Operation failed This is a generic fault for when an operation does not succeed as required Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 50 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 rejectedImmediately Busy Timeout gatekeeperError networkError protocolError dnsFailed destinationUnreachable gatekeeperEnded videoPortAllocationExceeded portAllocationExceeded disconnectAll incompatibleVncVersion failedToConnectToServer authenticationFailed service Unavailable capability NegotiationError message QueueOverflow gatekeeperRequiredButAbsent noGatekeeperForDN localGatekeeperRefused remoteGatekeeperRefused remoteGatekeeperUnreachable remoteGatewayResources gatekeeperForced h225SocketError h225ProtocolError h225DecodeError h245SocketError h245ProtocolError h245DecodeError q931DecodeError q931ProtocolError Copyrig
44. ew enumeratelD Copyright O TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 3 If there is an enumeratelD 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 enumeratelD values in responses 4 After all data is returned the device will reply with all remaining results but no enumeratelD This method should only be called using enumeratelD values as provided by the device 2 4 4 Filtering Enumerate functions contain an optional enumerateFilter parameter which can be used to restrict the responses to the enumerate call The valid expressions depend on the function to which they are applied but the syntax is the same for all enumerate functions the section in this document for each function provides a list of valid filters for that function To use the filters the expression is evaluated with any function or expression symbols evaluated for the given entity being enumerated e g if enumerating conferences the active expression will evaluate to true if the conference is active and false otherwise If the result of evaluating the filter is true the entity is returned to the client If the expression evaluates to false the entity in question is not returned to the client and the next entity if any is considered As an example i
45. f the conference to modify chars newConferenceName optional String lt 32 If present the conference will be renamed chars to specified value oldConferenceName String lt 32 Deprecated conference renaming scheme deprecated chars new code should use conferenceName and conferenceName deprecated String lt 32 newConferenceName as above chars numericld String lt 32 Optional fields as per conference create chars described above These fields can only be conferenceld deprecated String used for conferences which are not of type pin String ad_hoc register WithGatekeeper Boolean register WithSIPRegistrar Boolean startTime dateTime iso8601 durationSeconds Integer endTime deprecated dateTime iso8601 Description String multicastStreamingEnabled Boolean unicastStreamingEnabled Boolean h239Enabled Boolean private Boolean reserved VideoPorts Integer reservedAudioPorts Integer maximum VideoPorts Integer maximum AudioPorts Integer repetition String weekDay String whichWeek String Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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
46. f the expression active amp amp scheduled is used when enumerating conference the returned conferences will be only those which are both active and scheduled Filters can consist of atomic expressions joined together with operators and brackets in the traditional manner Whitespace is ignored Functions are valid and any parameters are in a comma separated list in brackets following the function name for example function expression expression2 From a boolean perspective the integer 0 is false and all other numbers are true Integer values can be expressed using any string of valid digits optionally prefixed by Ox for hexadecimal Ot for decimal and 0z for binary If no prefix is specified decimal is assumed The following binary operators are valid in order of priority lowest priority first Operator Description Boolean or amp amp Boolean and Bitwise or A Bitwise exclusive or amp Bitwise and Equality I Inequality lt Less than lt Less than or equal gt Greater than or egual gt Greater than lt lt Bitwise left shift gt gt Bitwise right shift Addition Subtraction Multiplication Division Modulo There are also the following unary operators all of which bind tighter than any binary operator Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 6 Operator Description Unary minus
47. h does not rely on the target MCU s gatekeeper usage is to call from mcu1 into the target conference using mcu2 as a gateway and the target conference s numeric id as the remote address The participant addition is shown in example message 3 as well as the address and gateway It also configures the view layout to be full screen by setting cpLayout to layout1 to make sure that just the active speaker from linked1 is sent to linked2 The final step is slightly more complex it involves modifying the new linked2 participant on mcu2 which was the result of the call from mcu1 The modification required is to change the view layout setting for the video sent from linked2 to linked1 to full screen so that a view of the linked2 active speaker is sent The complication here is that the linked2 participant in question is not a participant created via the API and so the API does not know the name in advance Therefore it is necessary to gt poll membership of linked2 after the connection from linked1 has been made gt identify the participant corresponding to the call gt use its name ina participant modify call to set the view layout The simplest way to identify the participant is to look for an absence of the address field in a conference query response for incoming non API connections this will not be present Example message 4 shows such a participant modify call in this case t
48. he participant name needed was 1_Codian MCU 4210 B 1 Example message 1 creating conference linked1 on mcu1 lt xml version 1 0 gt lt methodCall gt lt methodName gt conference create lt methodName gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt authenticationUser lt name gt lt value gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 55 lt string gt admin lt string gt lt value gt lt member gt lt member gt lt name gt conferenceName lt name gt lt value gt lt string gt linked1 lt string gt lt value gt lt member gt lt member gt lt name gt conferenceID lt name gt lt value gt lt string gt 1234 lt string gt lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodCall gt B 2 Example message 2 creating conference linked2 on mcu2 lt xml version 1 0 gt lt methodCall gt lt methodName gt conference create lt methodName gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt authenticationUser lt name gt lt value gt lt string gt admin lt string gt lt value gt lt member gt lt member gt lt name gt conferenceName lt name gt lt value gt lt string gt linked2 lt string gt lt value gt lt member gt lt member gt lt name gt conferenceID lt name gt lt value gt lt
49. ht O TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 52 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 e default use the MCU s default view family e family lt index gt use the specified layout family see below e layout lt index gt use a specific layout see below e conferenceCustom use the conference custom layout The lt index gt values for family lt index gt correspond to the pane arrangements shown below 1 The lt index gt values for layout lt index gt correspond to the pane arrangements shown below It is worth noting that these indices are also used for the currentLayout parameter from the participant enumerate call gt gt 8 gt A 7 D d A He E E pen i MS i FE KR i E E q F og H d 9 f na T a d Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 53 R o N m Lo No Ka a L Lo Lo Lo uw Lo L Lo Lo Lo lt Lo No D oo R o N m Lo O D 00 e e e mm eo M zz Y 2 F 54
50. if operationScope is configuredState borderWidth optional Integer 0 no border or 1 2 or 3 for 1 2 3 focusT ype optional String One of voiceActivated h239 or participant focusParticipant optional Struct A participant identification structure i e with conferenceName participantName participantProtocol and participantT ype members Should only be present if focusType is participant If there is no operationScope parameter the MCU will attempt to change both active and configured states This is deprecated behaviour and should not be relied upon 4 13 participant connect This method is used primarily for API configured participants with deferConnection set to true but can also be used to reconnect disconnected participants Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participant Type String 4 14 participant disconnect Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participantType String This call causes the MCU to tear down its connection to the specified participant if such a connection exists This is different from participant remove above because gt
51. ipant record is still not considered a dead record because it would be returned by a normal participant enumerate request A dead record will be returned by a method supporting revision numbers if the lastRevision parameter designates a revision at which the record was not yet dead The returned record will contain only the fields necessary for its identification and an extra field dead which will be set to true to indicate that this record should no longer considered to be present on the MCU These dead records are only cached on the MCU for a few minutes therefore a client should not rely on them unless it is doing very regular polling When using less frequent polling using the listAll parameter described above is more appropriate Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 61 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 Any client which supports HTTP keep alives may include the following line in the HTTP header of an API request Connection Keep Alive This indicates to the Codian product that the client supports HTTP keep alives The device then may choose to not close the TCP connection after returning its respo
52. ith a defined codec width optional Integer The maximum width and height of this stream Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 Parameter Type Comments conferenceName String Name of the conference whose layout is to be modified cpLayout optional String The current layout behavior for streaming viewers see Appendix A borderWidth optional Integer 0 no border or 1 2 or 3 for 1 2 3 focusType optional String One of voiceActivated h239 or participant focusParticipant Struct A participant identification structure i e with optional conferenceName participantName participantProtocol and participant ype members Should only be present if focusType is participant 4 8 conference paneplacement query Queries the current pane placement configuration Parameter Type Comments conferenceName String The name of the conference to be queried This returns a struct containing the following response fields Response Type Comments enabled Boolean true if pane placement is enabled and in u
53. lar this is used for participant identification where an invalid protocol is specified 20 Unsupported participant type A participant type was used which does not correspond to any participant type known to the device 21 No such folder A folder identifier was present but does not refer to a valid folder 22 No such recording A recording identifier was present but does not refer to a valid recording 23 No changes requested This is given when a method for changing something correctly identifies an object but no changes to that object are specified 24 No such port This is returned when an ISDN port is given as a parameter which does not exist on an ISDN gateway 101 Missing parameter This is given when a required parameter is absent The parameter in question is given in the fault string in the format missing parameter parameter name 102 Invalid parameter This is given when a parameter was successfully parsed is of the Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 49 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 format invalid parameter parameter_name 103 Malformed parameter This is given when a parameter of the correct name is present but cannot be read for some reason for example the param
54. lowing structures Field Type Comments folderName String The name of the folder folderld Integer A unique identifier for this folder parentFolderld optional Integer The unique identifier for the parent folder of this folder This is not present if the folder has no parent i e is the top level folder externalPath optional String The external NFS path Only present if there is an external path configured exportRecordings optional Boolean Set to true if recordings in this folder are exported via NFS Only present if there is an external path configured register WithGatekeeper Boolean Set to true if the recordings exported externally optional in this folder are to be registered with the gatekeeper Only present if there is an external path configured public Boolean Set to true if this folder is publicly accessible pin String Contains the PIN of this folder autoAttendantld String The numerical ids used to access these functions recordingld String Note that these are not the same as other recordingConsoleld String instances of similar names e g recordingld These must be unique across the device Copyright O TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 36 Field Type Comments pointToPointIncomingPrefix String The folder s configured point to point recording prefixes pointToPointOutgoingPrefix String These values are only present with
55. ments participantName String Participant identification as described above participantProtocol String participant l ype String conferenceName String autoAttendantUniqueld String address String The address used to connect to the remote gatewayAddress String endpoint in question Only returned when the address is known or if the participant is configured via the API which requires the address to be specified when added Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 44 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 value is the result of being overridden maxBitRateToMCU Integer As for participant add in kbps maxBitRateFromMCU Integer callState String One of dormant alerting connected or disconnected connectTime dateTime iso8601 Only returned after the participant is connected This value is always present if the call state is connected it may or may not be defined for participants in the disconnected call state depending on whether they were ever connected disconnectTime dateTime iso8601 Only returned after the participant has disconnected disconnectReaso
56. mode One of terminal network or unknown layer1 Boolean True if layer 1 is up false otherwise layer2 Boolean True if layer 2 is up false otherwise enabled Boolean True if this port has been enabled bChannels array of struct Only present if layer2 is up See below for definition of the structure lowChannel Integer The index of the low channel highChannel Integer The index of the high channel searchHighLow Boolean True if the search order is high to low false if Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 40 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 this a voice call false if a data call Only present if active incoming Boolean True if this call is incoming false if outgoing Only present if active calling String Only present if active called String Only present if active This function will return a No such port fault 24 if the port requested does not exist Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 41 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 par
57. n String Only returned after the participant has disconnected one of the disconnect reason values given in section 12 connectPending boolean true if a participant connect command is required for this participant This parameter will cause either the initial connection to that endpoint in the event that it was configured with deferConnection set or a re connection to that endpoint in the event that it has disconnected audioRxCodec String audioRxLost Integer audioRxReceived Integer audioTxCodec String audioTxReportedLost Integer audioTxSent Integer audioRxMuted Boolean audioRxGainMode String audioRxGainMillidB Integer videoRxCodec String videoRxLost Integer videoRxReceived Integer videoTxCodec String videoTxReportedLost Integer videoTxSent Integer videoRxMuted Boolean videoTx Widescreen Boolean important Boolean activeSpeaker Boolean true if this participant is currently the active speaker in the conference layoutControlEnabled Boolean cpLayout String The configured layout behavior for this Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 45 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 This parameter will not be present if the participant is in an auto at
58. n is as returned in participant enumerate Field Type Comments index Integer The index of the pane to be changed type String Any one of default the default behaviour blank a blank window loudest the current loudest speaker rolling shows a sequence of conference participants changing according to the configured rolling interval h239 the h239 content channel participant a participant as described in the three optional fields participantType String Participant identification Only reguired if type is optional participant these identify a specific participant participantProtocol String optional participantName String optional Because not all panes are guaranteed to be changed this call returns the following structure Response Type Comments panesModified Integer The number of panes successfully modified This will be the number of elements in the panes array on complete success and zero if there is no panes array 4 10 participant add Adds a participant to a conference Parameter Type Comments conferenceName String The name of the conference to which to add the participant participantName String The name of the participant to be added This must be a unique value i e not the same as any existing participant Note that for ad hoc participants this is optional but must be present otherwise participantProtocol
59. ndix A layoutSource String This will be one of family lt x gt conferenceCustom or participantCustom and describes the reason for the current layout This parameter is only present if the currentLayout parameter is also present i e if the participant is in an active conference callDirection String Either incoming or outgoing When the callState field is dormant the callDirection field is not returned preview URL String The location of the preview image this is not a complete URL and reguires a prefix of http lt hostname gt where hostname is the hostname of this MCU before it is used focusType String One of participant voiceActivated or h239 focusParticipant Struct Only present if focusT ype is participant This structure contains participant identification members i e conferenceName participantName participantType and participantProtocol Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 30 Field Type Comments callldentifier base64 The h323 id of this caller border Width 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 value will change as the user navigates through an MCU s configured menu structure mediaEncryption String One of the following values encrypted all media channels to and from thi
60. ng 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 gt SIP page 3 7 addressBookEntry enumerate Enumerates configured endpoints on an MCU or IP VCR Parameter Type Comments enumeratelD String The value returned by the last enumeration call If it is optional omitted a new enumeration is started This method returns Response Type Comments enumeratelD String The value that 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 addressBookEntries array of structs See below for details The array addressBookEntries contains structs with the following fields Field Type Comments Name String The configuration s name address String lt 32 The participant s E 164 directory chars number hostname or IP address protocol String One of h323 sip or vne gatewayName String Present for h323 endpoints which are configured to use a gateway This name corresponds to the name of a gateway returned via gateway enumerate gateway Address String Present for h323 endpoints which are configured to use a gateway This is the addre
61. nse to the request If the connection will be closed the device returns the following line in the HTTP header of its response Connection close The absence of this line indicates that the device will keep the TCP connection open and that the client may use the same connection for a subsequent request The device will not allow a connection to be kept alive if e the current connection has already serviced a set number of requests e the current connection has already been open for a certain amount of time e there are already more than a certain number of connections in a kept alive state These restrictions are in place to limit the resources associated with kept alive connections If a connection is terminated for either of the first two reasons the client will probably find that the connection is back in a keep alive state following the next request The client should never assume a connection will be kept alive Also note that even after a response not containing the connection close header the connection will still be closed if no further requests are made within one minute If requests from the client are likely to be this far apart then there is little to be gained by using HTTP keep alives Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 62
62. nteger recordingld value used to uniquely identify the new recording This value can then be used in later recording configure or recording stop calls for instance 5 2 recording configure Configures a pre existing recording All configuration parameters are optional although a no changes requested fault will occur if there are no optional parameters present Parameter Type Comments recordingld Integer The recording ID for the recording to modify This should be the identifier as returned by recording enumerate recordingName String The name for the recording optional numericld optional String The numeric ID used for this recording pin optional String The PIN for this recording register WithSIPRegistrar Boolean Whether to register this recording with the sip optional registrar registerWithGatekeeper Boolean Whether to register this recording with the h323 optional gatekeeper playbackEnabled Boolean Whether this recording has playback enabled optional Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 34 5 3 recording delete This method deletes a recording from the IP VCR Parameter Type Comments re cordingld Integer 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
63. o the Visibility setting on the web UI which can have the value Public or Private maximumAudioPorts optional Integer These fields set the limit on the number maximum VideoPorts optional Integer of audio audio only and video video reservedAudioPorts optional Integer audio ports for the conference The Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 whichW eek optional String Must be present if repetition is monthly One of first the first X of the month where X is the day specified by weekday second third fourth or last i e last X of the month weekDays optional terminationType optional String String Must be present if repetition is weekly or everyTwoWeeks A comma separated string of weekdays i e any of monday tuesday wednesday thursday friday saturday or sunday e g monday wednesday friday One of noTermination afterNRepeats or endOnGivenDate terminationDate optional dateTime iso8601 If terminationType
64. olean True if the recording can be played back by users register WithSIPRegistrar Boolean True if the numeric ID is registered with the SIP registrar register WithGatekeeper Boolean True if the numeric ID is registered with the h323 gatekeeper Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 35 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 Comments re cordingld Integer The recording ID for the recording to stop This should be the recordingld as returned by recording enumerate A no such recording fault is returned if the recording does not exist or is not in the process of being recorded this method has an effect only on those recordings whose status value as returned by recording enumerate is recording 5 6 folder enumerate This function enumerates all subfolders of a folder Parameter Type Comments enumeratelD optional String An enumeratelD as specified in section 2 This returns the following structure Response Type Comments enumeratelD optional String An enumeratelD as specified in section 2 folders array of structures See below for layout of the structures The folders array contains the fol
65. onScope array of strings This should contain none either or both of currentState or configuredState If currentState is present the active configuration of each participant is returned by the MCU in the currentState structure If configuredState is present the stored configuration is returned in the configuredState structure Valid expressions within the enumerate filter are as follows Expression Type Comments connected Boolean True if the participant is currently connected to a conference disconnected Boolean True if the participant has been connected to a conference but is now disconnected Note that a participant that has not yet connected to a conference e g they have deferred connection specified is neither connected nor disconnected This method returns Response Type Comments enumeratelD optional String The value which should be used in the next call to get the next set of data If this is not present there is no further data available from the MCU participants array of structs See below for contents and an array called participants of structs which contain Field Type Comments participantName string Participant identification as described above participantProtocol String Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 27 Field Type Comments participantType St
66. ontrol 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 iso8601 The time at which the conference started at or will start at durationSeconds Integer How long each repeating instance of the conference should last for If absent the conference is permanent A repetition optional String One of none daily weekly everyTwoWeeks or monthly weekDay optional String Present if repetition is monthly One of monday tuesday wednesday thursday friday saturday or sunday whichWeek optional String Present if repetition is monthly One of first the first X of the month where X is the day specified by weekday second third fourth or last i e last X of the month weekDays optional String A comma separated string of weekdays i e any Of monday tuesday wednesday thursday friday saturday or sunday e g monday wednesday friday This field is present when repetition is weekly or everyTwoWeeks terminationType optional String One of noTermination afterNRepeats or endOnGivenDate terminationDate optional dateTime iso8601 If terminationType is endOnGivenDay this is the day that the conference repetition will end on The following timing
67. ord must be blank Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 or auto attendant the D combination of participantType participantProtocol and participantName is always unigue participantProtocol String Used in conjunction with participantName to uniguely participantType String identify a participant within a connection Typically these parameters should be treated as opague values but the current possibilities are for participantProtocol h323 an endpoint using the H 323 protocol vne a VNC connection e g remote desktop sip an endpoint using the SIP protocol for participantT ype ad_hoc this participant called into the MCU or was dialed out via the web interface and is not in the MCU s endpoint list by_address fully specified participant added through the API ba name MCU configured endpoint irrespective of whether the
68. ote 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 platform or software dependence and was chosen over SOAP because of its simplicity The interface is stateless Currently there is no mechanism for the Codian device to call back the controlling application and therefore the controlling application must poll the device for status as required A future enhancement may provide a mechanism for signaling device status changes to the controlling application The latest version of the Remote Management API is version 2 5 the following table shows which version of Codian products support this version API Version MCU 4200 IP VCR 2200 Codian ISDN IP Gateway 3500 MCU 4500 Recording blade Gateway 3200 Series Media blades 3201 MSE 8320 IP Gateway MSE MSE 8321 8350 blade 2 4 2 2 2 2 1 3 2 5 2 3 and later 2 3 and later 1 4 2 0 1 1 HTTP and HTTPS Codian devices expect to receive HTTP communication over TCP IP connections to port 80 The HTTP messages should be POST s to the URL RPC2 HTTPS a secure encrypted version of HTTP is supported on the following products
69. r The maximum bit rate to the MCU specified as kBit s maxBitRateFromMCU Integer The maximum bit rate from the MCU specified as kBit s motionSharpnessTradeoff String One of default to use the global default setting preferMotion preferSharpness and balanced displayNameOverrideStatus Boolean If true use the specified displayNameOverrideValue text as the participant s display name during the conference display NameOverrideValue string lt 32 chars Value to use as the participant s display name if displayNameOverrideStatus set to true cpLayout String This sets the initial conference view layout for the video sent to this participant Refer to Appendix A for the full list of available layouts layoutControlEnabled Boolean Controls whether this participant is able to change the conference view layout that they see 1 true means that the participant can change the layout using FECC or DTMF 0 false means that they cannot audioRxMuted Boolean 1 true means that audio from this participant will not be heard by other conference participants audioRxGainMode String One of none no extra gain applied automatic automatic gain control applied fixed fixed number of dBs of gain applied audioRxGainMillidB Integer If audio gain mode is fixed this is the number of decibels of gain applied multiplied by 1000 and can be a negative value
70. rent participants Note that until conference destroy is called for a particular conference the conference will remain in the list of conferences even after the conference has ended 8 2 conference query This method is deprecated in favour of conference enumerate and participant enumerate Parameter Type Comments conferenceName String The name of the conference of interest The method response returns the following Parameter Type Comments startTime date Time iso8601 The time at which the conference started at or will start at end Time date Time iso8601 The time at which the conference will end If the conference is permanent then this parameter is absent pin String The PIN The method also returns a participants lt array gt of lt struct gt for each conference where each lt struct gt contains the following parameters Response Type Comments participantName String The participant name supplied in the participant add message Copyright O TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 43 Response Type Comments displayName Strin The name used by the endpoint to identify itself This pray g y P y 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 guestion Only returned when the addr
71. ring conferenceName String autoAttendantUnigueld String connectionUniqueld Integer Corresponds to the uniqueld returned by a conference or autoattendant currentState optional Struct 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 configuredState Struct The stored configuration of the participant if any optional Details of this struct are given below This is only present if requested in the operationScope If the endpoint is not configured the configuredState structure is empty otherwise the configuredState structure contains the following entries Field Type Comments address String The address used to connect to the remote gatewayAddress String endpoint in question Only returned when the address is known useSipRegistrar Boolean Whether to use a registrar in making this a call transportProtocol String One of default tcp udp or tls password String The password for vnc endpoints deferConnection Boolean true if this participant s connection is being deferred displayNameOverrideStatus Boolean Indicates whether the displayName value is the result of being overridden maxBitRateToMCU Integer As for participant add in kbps maxBitRateFromMCU Integer motionSharpnessTradeoff String One of default if set to the global default setting pr
72. s 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 This allows a client to resynchronize to the MCU because it can safely assume that any record not returned by this request or series of requests in the case of enumerations is no longer a record on the MCU For example any participants not returned by participant enumerate when listAll is set to true can be assumed to have been removed from the MCU The listAll parameter can still be used in conjunction with the lastRevision parameter doing so means that every record will be returned but records that have not changed since the specified revision may have many members removed from their substructures Substructures that have had members removed in this way will contain a field named changed instead which will be set to false indicating that there are no changes to the data in this substructure since the specified revision number C 2 Dead records The second approach to the record removal problem is the dead parameter The MCU will maintain a cache of records that have been removed and are in no sense considered active a dead record will never be returned if revision numbers are not being used or if the listAll parameter is set to true e g a previous partic
73. s endpoint are encrypted unencrypted all media channels to and from this endpoint are encrypted mixed some channels are encrypted and some not unknown none of the above this may occur when a participant has very recently connected and no media channels have been established yet audioRxEnergyMillidB Integer The measured energy of a participant s audio sent to the MCU Typically this will be a negative value in the range 30000 30dB for very quiet and 0 very loud audioRxMutedRemotely Boolean Whether this endpoint is muted remotely Note This participant information is returned for all participants added to the conference using the participant add method even after they have disconnected However this information is only returned for other participants i e those added via the web interface or those who dialed into the conference whilst they are connected but not after they have disconnected 4 17 participant fecc Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participant Type String direction String One of up down left right zoomIn zoomOut focusIn focusOut 4 18 participant message Puts a message on the display of a given participant Parameter Type Comments conferenceName String Participant i
74. se false otherwise panes optional array of structs This is only present if enabled above is true The struct definition is as below The panes array contains structures with the following format Field Type Comments type String Any one of default the default behaviour blank a blank window loudest the current loudest speaker rolling shows a sequence of conference participants changing according to the configured rolling interval h239 the h239 content channel participant a participant as identified below index Integer The index of this pane participantType String Participant identification Only present if this pane optional contains a specific participant participantProtocol String optional participantName String optional Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 21 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 pane placement false to disable panes optional array of structs 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 Participant identificatio
75. sed by the device h323ID String The h323 id used by the device mcuServicePrefix String The service prefix used by the device scheduledConferencelDRegistration String The value enabled or disabled corresponds to web interface ID registration for scheduled conferences option This field is only present for MCU product types and only for MCU software versions 2 2 1 3 onwards h323IDStatus String The current status of the ID service prefix mcuServicePrefixStatus String registration process One of idle registering registered deregistering pendingReregistration waitingRetry nolD or idTooLong 3 6 sip query Retrieves information on SIP configuration for an MCU or IP VCR Takes no parameters Response Type Comments configuredRegistrar String The currently configured SIP registrar address This corresponds to the SIP registrar address on the Settings gt SIP web page and will be an empty string value if there is no currently configured SIP re gistrar configuredProxy String This corresponds to the SIP proxy address on the Settings gt SIP web page and will be an empty string value if there is no The currently configured SIP proxy address Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 Response Type Comments currently configured SIP proxy conferenceRegistration String This value is only present if the device bei
76. sent for active participants 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 value is the result of being overridden maxBitRateToMCU Integer As for participant add in kbps maxBitRateFromMCU Integer motionSharpnessTradeoff String One of default if set to the global default setting preferMotion preferSharpness and balanced callState String One of dormant alerting connected or disconnected When dormant the callDirection field is not returned connectTime dateTime iso8601 Only returned after the participant is connected This value is always present if the call state is connected It may or may not be defined for participants in the disconnected state depending on whether they were ever connected disconnectTime dateTime iso8601 Only returned after the participant has disconnected disconnectReason String Only returned after the participant has disconnected this contains one of the disconnect reason strings given in section 8 connectPending Boolean true if sending a participant connect command for this participant will cause either the initial connection to that endpoint in the event that it was configured with deferConnection set or a re connection to that endpoint in the event that it has disconnected audioRxCo
77. ss of the gateway this endpoint is configured to use useSIPRegistrar Boolean Whether this endpoint is configured to use a sip registrar when being called password String The password for vnc endpoints portNumber Integer The port number for vnc endpoints callInParams struct See below for details conferencingParameters struct See below for details The structure callInParams contains the following fields This is used to match incoming participants to endpoint configurations For a positive match a participant must match fields which have values Blank fields are not considered in the comparison Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 useDefault VideoTransmitResolutions Boolean If true this endpoint will use box wide default video transmit resolutions videoTransmitResolutions String One of allowAll 4to30nly 4to3WidescreenOverride or 16to90nly maxMediaTxBitRate
78. string gt 5678 lt string gt lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodCall gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 56 B 3 Example message 3 calling into linked2 from linked1 lt xml version 1 0 gt lt methodCall gt lt methodName gt participant add lt methodName gt lt params gt lt param gt lt value gt lt struct gt lt member gt lt name gt authenticationUser lt name gt lt value gt lt string gt admin lt string gt lt value gt lt member gt lt member gt lt name gt conferenceName lt name gt lt value gt lt string gt linked1 lt string gt lt value gt lt member gt lt member gt lt name gt participantName lt name gt lt value gt lt string gt remote_mcu lt string gt lt value gt lt member gt lt member gt lt name gt address lt name gt lt value gt lt string gt 5678 lt string gt lt value gt lt member gt lt member gt lt name gt gatewayAddress lt name gt lt value gt lt string gt 10 2 1 27 lt string gt lt value gt lt member gt lt member gt lt name gt cpLayout lt name gt lt value gt lt string gt layout1 lt string gt lt value gt lt member gt lt struct gt lt value gt lt param gt lt params gt lt methodCall gt Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 1 0 B 4 Example message
79. ted query Any user with administrator privileges Deprecated methods system query Any user with administrator privileges conference query Any user with privilege conference detail or higher conference participant modify As above for participant modify conference participant remove As above for participant remove conference participant add As above for participant add Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 48 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 Description Code 1 Method not supported This method is not supported on this device 2 Duplicate conference name A conference name was specified but is already in use 3 Duplicate participant name A participant name was specified but is already in use 4 No such conference or auto attendant The conference or auto attendant identification given does not match any conference or auto attendant 5 No such participant The participant identification given does not match any participants
80. tendant rather than a conference nor if the MCU is not currently transmitting video to the participant in question The values for this are those described in appendix A callDirection String Either incoming or outgoing Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 46 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 lt system gt lt manufacturer gt Codian lt manufacturer gt lt model gt MCU 4210 lt model gt lt serial gt MRV1001SM0004B8 lt serial gt lt softwareVersion gt 1 4 1 2 lt softwareVersion gt lt buildVersion gt 6 6 1 2 lt buildVersion gt lt hostName gt TestMCU lt hostName gt lt totalVideoPorts gt 20 lt totalVideoPorts gt lt totalAudioOnlyPorts gt 20 lt totalAudioOnlyPorts gt lt portReservat ionMode gt disabled lt portReservationMode gt lt maxVideoResolution gt cif lt maxVideoResolution gt lt uptimeSeconds gt 2345 lt uptimeSeconds gt lt system gt The meaning of the fields is Field Comments manufacturer The manufacturer of this MCU i e Codian model The model of this particular MCU e g MCU 42
81. ue 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 packetsReceived Integer that all these values are 32 bit signed integers and multicastPacketsSent Integer thus may wrap multicastPacketsReceived Integer bytesSent Integer bytesReceived Integer queueDrops Integer collisions Integer transmitErrors Integer receiveErrors Integer bytesSent64 String 64 bit versions of the above stats using a string bytesReceived64 String rather than an integer All fields above marked optional will be returned only if the interface has been enabled and has been configured 3 3 device health query Returns the current status of the MCU such as health monitors and CPU load Response Type Comments cpuLoad Integer The CPU load as a percentage mediaLoad Integer Loads for the media processors total and split audioLoad Integer between audio and video as percentage values videoLoad Integer These are not present on ISDN gateways fanStatus String One of ok outOfSpec and critical fanStatusWorst String temperatureStatus String temperatureStatus Worst String rtcBatteryStatus String rtcBatteryStatus Worst String voltagesStatus String voltagesStatusWorst
82. umeratelD 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 lt The gateway s E 164 directory number 32 chars hostname or IP address conferencingParameters struct see below 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 maxMediaTxBitRate Integer Max media transmit bit rate maxMediaRxBitRate Integer Max media receive bit rate Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 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 lt 32 Name of the conference to be created chars
83. uredState or the active state of a participant in a conference activeState For example if the parameter layoutControlEnabled is included in a call to participant modify then the effect of the call will depend on operation scope as follows e If operationScope is activeState the active participant s ability to control their layout will immediately change but the configured value will remain unchanged so that if they were to reconnect later the state of layoutControlEnabled would revert back to how it is in the configuration e If operationScope is configuredState the participant s current ability to control their layout will be unaffected but their configuration will be changed so that in future occurrences of the conference or when the participant is reconnected they will have the newly configured state Parameter Type Comments conferenceName String Participant identification as described above autoAttendantUniqueld String participantName String participantProtocol String participant Type String operationScope String One of activeState or configuredState This parameter specifies the scope of the changes to be made be they to the configured state of an endpoint or to the active state of a participant in a conference address String All these parameters are optional They should not gatewayAddress String be present
84. videoRxSelectedBitRate Integer videoRxActualBitRate Integer videoRxLimitReason String One of notLimited viewedSize quality aggregateBandwidth flowControl or endpointLimitation videoTx Width Integer videoTxHeight Integer videoTxInterlaced Boolean videoRxWidth Integer videoRx Height Integer videoRxInterlaced Boolean 4 20 autoAttendant enumerate Parameter Type Comments enumeratelD optional String The value returned by the last enumeration call if omitted a new enumeration is started This function has no valid enumerate filter expressions Copyright TANDBERG 2008 Reference Guide Version 3 0 rev 3 0 32 This method returns Response Type Comments enumeratelD 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 array of structs See below for contents and an array called autoAttendants of structs which contains Response Type Comments autoAttendantUniguelD String autoAttendantConfiguredName String 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 startTime dateTime iso8601 The time at which the auto attendant was created 4

TANDBERG 3 User's Manual

Contents

Download Pdf Manuals

Related Search

Related Contents