diff options
Diffstat (limited to 'spec/Call1_Stream_Interface_Media.xml')
| -rw-r--r-- | spec/Call1_Stream_Interface_Media.xml | 774 |
1 files changed, 774 insertions, 0 deletions
diff --git a/spec/Call1_Stream_Interface_Media.xml b/spec/Call1_Stream_Interface_Media.xml new file mode 100644 index 00000000..d8500d73 --- /dev/null +++ b/spec/Call1_Stream_Interface_Media.xml @@ -0,0 +1,774 @@ +<?xml version="1.0" ?> +<node name="/Call1_Stream_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="im.telepathy1.Call1.Stream.Interface.Media"> + <tp:added version="0.25.2">(as stable API)</tp:added> + <tp:requires interface="im.telepathy1.Call1.Stream"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface deals with how to connect a stream to an + endpoint. It contains all that is required to describe the + local endpoint, to succesfully establish a connection. While a + call is established, one may try to connect to multiple remote + endpoints at the same time. This is called forking in the SIP + jargon. Informations related to the connections are on the + <tp:dbus-ref + namespace="imt1.Call1.Stream">Endpoint</tp:dbus-ref> + objects. Once the call is established, there MUST be a single + endpoint left.</p> + + <h4>ICE restarts</h4> + + <p>If the CM wants to do an ICE restart, then the + <tp:member-ref>ICERestartPending</tp:member-ref> property is set, + and the <tp:member-ref>ICERestartRequested</tp:member-ref> signal is + emitted. The streaming implementation should then call + <tp:member-ref>SetCredentials</tp:member-ref> again. This will trigger + the actual ICE restart, and cause + <tp:member-ref>LocalCandidates</tp:member-ref> to be cleared.</p> + + <p>For more information on ICE restarts see + <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245 + section 9.1.1.1</a></p> + </tp:docstring> + + <tp:enum type="u" name="Stream_Flow_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The type of <tp:member-ref>SendingState</tp:member-ref> + and <tp:member-ref>ReceivingState</tp:member-ref>. + </tp:docstring> + <tp:enumvalue suffix="Stopped" value="0"> + <tp:docstring> + No data is flowing (or expected to be flowing) at this time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Start" value="1"> + <tp:docstring> + The streaming implementation has been told to start or receiving, + but has not yet indicated that it is doing so. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Stop" value="2"> + <tp:docstring> + The streaming implementation has been told to stop sending or + receiving data, but it has not yet indicated that it has done so. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Started" value="3"> + <tp:docstring> + The streaming implementation is successfully sending or receiving + data, and everything is going swimmingly. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="SendingState" tp:name-for-bindings="Sending_State" + type="u" tp:type="Stream_Flow_State" access="read"> + <tp:docstring> + Indicates whether the streaming implementation is/should be sending + media for this stream. The streaming implementation should be able to + rely on reading this value and listening to + <tp:member-ref>SendingStateChanged</tp:member-ref> to + determine whether it should be sending media or not. It should not + need to listen to the Hold interfaces on the Call/Content. + Feedback on success should be given via + <tp:member-ref>CompleteSendingStateChange</tp:member-ref>. Failures + should be reported via <tp:member-ref>ReportSendingFailure</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="SendingStateChanged" + tp:name-for-bindings="Sending_State_Changed"> + <tp:docstring> + Change notification for <tp:member-ref>SendingState</tp:member-ref>. + Note that this information is duplicated onto the Stream interface, so + that UIs can ignore the Media interface, and streaming implementations + can ignore everything but the media interface. + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State"> + <tp:docstring> + The new value of SendingState. + </tp:docstring> + </arg> + </signal> + + <method name="CompleteSendingStateChange" + tp:name-for-bindings="Complete_Sending_State_Change"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called in response to + <tp:member-ref>SendingStateChanged</tp:member-ref>(Pending_*, *) to + indicate that the media state has successfully progressed from + Pending_{Start, Stop, Pause} to the corresponding non-pending + state.</p> + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State" direction="in"> + <tp:docstring> + The new (non-pending) value of SendingState. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="im.telepathy1.Error.InvalidArgument"> + <tp:docstring> + The state change made no sense, and was ignored by the CM. The + most likely cause for this is a race-condition between the CM + emitting a new state change and the streaming implementation + responding to the previous state change. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ReportSendingFailure" + tp:name-for-bindings="Report_Sending_Failure"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Can be called at any point to indicate a failure in the outgoing + portion of the stream. + </tp:docstring> + <arg name="Reason" type="u" tp:type="Call_State_Change_Reason" + direction="in"/> + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"/> + <arg name="Message" type="s" direction="in"/> + </method> + + <property name="ReceivingState" tp:name-for-bindings="Receiving_State" + type="u" tp:type="Stream_Flow_State" access="read"> + <tp:docstring> + The counterpart of <tp:member-ref>SendingState</tp:member-ref>. + Indicates whether the streaming implementation is/should be expecting + to receive media for this stream. The CM should only tell the + streaming implementation to stop receiving if it has been told to put + the stream on hold, or the stream has been removed from the call. + </tp:docstring> + </property> + + <signal name="ReceivingStateChanged" + tp:name-for-bindings="Receiving_State_Changed"> + <tp:docstring> + Change notification for <tp:member-ref>ReceivingState</tp:member-ref>. + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State"> + <tp:docstring> + The new value of ReceivingState. + </tp:docstring> + </arg> + </signal> + + <method name="CompleteReceivingStateChange" + tp:name-for-bindings="Complete_Receiving_State_Change"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called in response to + <tp:member-ref>ReceivingStateChanged</tp:member-ref>(Pending_*, *) to + indicate that the media state has successfully progressed from + Pending_{Start, Stop, Pause} to the corresponding non-pending + state.</p> + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State" direction="in"> + <tp:docstring> + The new (non-pending) value of ReceivingState. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="im.telepathy1.Error.InvalidArgument"> + <tp:docstring> + The state change made no sense, and was ignored by the CM. The + most likely cause for this is a race-condition between the CM + emitting a new state change and the streaming implementation + responding to the previous state change. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ReportReceivingFailure" + tp:name-for-bindings="Report_Receiving_Failure"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Can be called at any point to indicate a failure in the incoming + portion of the stream. + </tp:docstring> + <arg name="Reason" type="u" tp:type="Call_State_Change_Reason" + direction="in"/> + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"/> + <arg name="Message" type="s" direction="in"/> + </method> + + <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used to set the username fragment and password for streams that have + global credentials.</p> + </tp:docstring> + <arg name="Username" type="s" direction="in"> + <tp:docstring> + The username to use when authenticating on the stream. + </tp:docstring> + </arg> + <arg name="Password" type="s" direction="in"> + <tp:docstring> + The password to use when authenticating on the stream. + </tp:docstring> + </arg> + </method> + + <tp:enum type="u" name="Call_Stream_Candidate_Type"> + <tp:docstring> + The network topology that an IP candidate represents. This can + sometimes be used to infer what kind of performance characteristics + (latency, bandwith, etc) can be expected of connections made to this + candidate. + </tp:docstring> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + This is not an IP candidate. This is a reserved value, and should + not be seen on the bus. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Host" value="1"> + <tp:docstring> + This candidate represents a direct connection to the host, as its + address is taken directly the host's IP stack. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Reflexive" value="2"> + <tp:docstring> + This candidate probably represents a connection to the host through + a NAT device, as its address was discovered by sending a binding + request to a STUN server or similar. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Peer_Reflexive" value="3"> + <tp:docstring> + This candidate probably represents a good route between the host and + its peer, as its address was discovered by sending a STUN binding + request to one of the candidates advertised by the peer. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Relay" value="4"> + <tp:docstring> + This candidate represents the address of a relay server (usually + somewhere on the public internet). This candidate is the most likely + to work, but all media will go via a relay server, so latency is + likely to be higher than other types of candidate. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Multicast" value="5"> + <tp:docstring> + This candidate represents a Multicast group. This value should only + appear if the Stream's <tp:member-ref>Transport</tp:member-ref> is + set to Multicast. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Media_Stream_Base_Proto" type="u"> + <tp:enumvalue suffix="UDP" value="0"> + <tp:docstring>UDP (User Datagram Protocol)</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="TCP" value="1"> + <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Candidate_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:</p> + + <dl> + <dt><code>type</code> - u</dt> + <dd>The type of candidate + (<tp:type>Call_Stream_Candidate_Type</tp:type>)</dd> + + <dt><code>foundation</code> - s</dt> + <dd>The foundation of this candidate</dd> + + <dt><code>protocol</code> - u</dt> + <dd>Underlying protocol of the candidate + (<tp:type>Media_Stream_Base_Proto</tp:type>) </dd> + + <dt><code>priority</code> - u</dt> + <dd>Priority of the candidate (should be a number between 0 and + 65535). Most ICE implementations will prefer the highest priority + candidate pair that manages to connect. For backwards + compatibility with non-ICE SIP clients, the lowest priority + candidate may be sent as a raw UDP fallback candidate. + It is recommended that a relay candidate is used as the lowest + priority candidate if possible. If both IPv4 and IPv6 raw udp + fallback candidates are available, they should be set to the + same priority and advertised to the CM at the same time. The CM + will decide which to advertise to the remote end.</dd> + + <dt><code>base-ip</code> - s</dt> + <dd>The underlying Host address where media sent to this + (non-host-type) candidate will eventually arrive.</dd> + + <dt><code>base-port</code> - u</dt> + <dd>The underlying Host port where media sent to this + (non-host-type) candidate will eventually arrive.</dd> + + <dt><code>username</code> - s</dt> + <dd>Username of this candidate + (only if credentials are per candidate)</dd> + + <dt><code>password</code> - s</dt> + <dd>Password of this candidate + (only if credentials are per candidate)</dd> + + <dt><code>ttl</code> - u</dt> + <dd>The TTL mandated for RTP/RTCP packets sent to a multicast group + (only valid for Multicast Streams)</dd> + </dl> + </tp:docstring> + <tp:member name="Key" type="s"> + <tp:docstring>One of the well-known keys documented here, or an + implementation-specific key.</tp:docstring> + </tp:member> + <tp:member name="Value" type="v"> + <tp:docstring>The value corresponding to that key.</tp:docstring> + </tp:member> + </tp:mapping> + + <tp:enum type="u" name="Stream_Component"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Media streams can use more than one UDP socket: one for RTP (data) + and one for RTCP (control). Most of the time, they are adjacent + to each other, but some protocols (xmpp) signal each port separately. + </tp:docstring> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The stream transport type is unknown or not applicable + (should not appear over dbus). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Data" value="1"> + <tp:docstring> + This is the high-traffic data socket, containing the audio/video + data for the stream. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Control" value="2"> + <tp:docstring> + This is the low-traffic control socket, usually containing feedback + about packet loss etc. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Candidate" array-name="Candidate_List"> + <tp:docstring>A Stream Candidate.</tp:docstring> + <tp:member name="Component" type="u" tp:type="Stream_Component"> + <tp:docstring>The component number.</tp:docstring> + </tp:member> + <tp:member name="IP" type="s"> + <tp:docstring>The IP address to use.</tp:docstring> + </tp:member> + <tp:member name="Port" type="u"> + <tp:docstring>The port number to use.</tp:docstring> + </tp:member> + <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info"> + <tp:docstring>Additional information about the candidate.</tp:docstring> + </tp:member> + </tp:struct> + + <method name="AddCandidates" tp:name-for-bindings="Add_Candidates"> + <tp:docstring> + Add candidates to the + <tp:member-ref>LocalCandidates</tp:member-ref> property and + signal them to the remote contact(s). Note that connection managers + MAY delay the sending of candidates until + <tp:member-ref>FinishInitialCandidates</tp:member-ref> is called. + </tp:docstring> + <arg name="Candidates" direction="in" + type="a(usua{sv})" tp:type="Candidate[]"> + <tp:docstring> + The candidates to be added. + </tp:docstring> + </arg> + </method> + + <method name="FinishInitialCandidates" + tp:name-for-bindings="Finish_Initial_Candidates"> + <tp:docstring> + This indicates to the CM that the initial batch of candidates + has been added, and should now be processed/sent to the remote side. + <tp:rationale> + Protocols supporting Raw UDP SHOULD wait for FinishInitialCandidates, + and then set the lowest priority candidate as the Raw UDP candidate. + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="im.telepathy1.Error.NotAvailable"> + <tp:docstring> + The minimal required candidates have not been set. For + example, for an RTP protocol, at least one candidate on the + component 1 (RTP) must have been set. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:enum type="u" name="Stream_Transport_Type"> + <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A transport that can be used for streaming. + </tp:docstring> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The stream transport type is unknown or not applicable + (for streams that do not have a configurable transport). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Raw_UDP" value="1"> + <tp:docstring> + Raw UDP, with or without STUN. All streaming clients are assumed to + support this transport, so there is no handler capability token for + it in the <tp:dbus-ref namespace="imt1.Channel.Type" + >Call1</tp:dbus-ref> interface. + [This corresponds to "none" or "stun" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="ICE" value="2"> + <tp:docstring> + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="GTalk_P2P" value="3"> + <tp:docstring> + Google Talk peer-to-peer connectivity establishment, as implemented + by libjingle 0.3. + [This corresponds to "gtalk-p2p" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="WLM_2009" value="4"> + <tp:docstring> + The transport used by Windows Live Messenger 2009 or later, which + resembles ICE draft 19. + [This corresponds to "wlm-2009" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="SHM" value="5"> + <tp:added version="0.21.2"/> + <tp:docstring> + Shared memory transport, as implemented by the GStreamer + shmsrc and shmsink plugins. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Multicast" value="6"> + <tp:added version="0.21.5"/> + <tp:docstring> + Multicast transport. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Transport" tp:name-for-bindings="Transport" + type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes"> + <tp:docstring> + The transport for this stream. + </tp:docstring> + </property> + + <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates" + type="a(usua{sv})" tp:type="Candidate[]" access="read"> + <tp:docstring> + [FIXME]. Change notification is via the + <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal. + </tp:docstring> + </property> + + <signal name="LocalCandidatesAdded" + tp:name-for-bindings="Local_Candidates_Added"> + <tp:docstring> + Emitted when local candidates are added to the + <tp:member-ref>LocalCandidates</tp:member-ref> property. + </tp:docstring> + <arg name="Candidates" type="a(usua{sv})" tp:type="Candidate[]"> + <tp:docstring> + Candidates that have been added. + </tp:docstring> + </arg> + </signal> + + <tp:struct name="Stream_Credentials"> + <tp:docstring>A username and password pair.</tp:docstring> + + <tp:member name="Username" type="s"> + <tp:docstring>The username.</tp:docstring> + </tp:member> + + <tp:member name="Password" type="s"> + <tp:docstring>The password.</tp:docstring> + </tp:member> + </tp:struct> + + <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" + type="(ss)" tp:type="Stream_Credentials" access="read"> + <tp:docstring> + The local credentials are sent to the remote site over the + signalling protocol. They are used in ICE to make sure that + the connectivity checks come from the right peer. Change + notification is via the + <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal. + + This property will be a pair of empty strings if ICE has not yet been + started. + </tp:docstring> + </property> + + <signal name="LocalCredentialsChanged" + tp:name-for-bindings="Local_Credentials_Changed"> + <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed> + <tp:docstring> + Emitted when the value of + <tp:member-ref>LocalCredentials</tp:member-ref> changes to a non-empty + value. This should only happen when the streaming implementation calls + <tp:member-ref>SetCredentials</tp:member-ref>, so this signal is + mostly useful for debugging. + </tp:docstring> + <arg name="Username" type="s" /> + <arg name="Password" type="s" /> + </signal> + + <signal name="RelayInfoChanged" + tp:name-for-bindings="Relay_Info_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>RelayInfo</tp:member-ref> changes. + </tp:docstring> + <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" /> + </signal> + + <signal name="STUNServersChanged" + tp:name-for-bindings="STUN_Servers_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>STUNServers</tp:member-ref> changes. + </tp:docstring> + <arg name="Servers" type="a(su)" tp:type="Socket_Address_IP[]" /> + </signal> + + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" + type="a(su)" tp:type="Socket_Address_IP[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The IP addresses of possible STUN servers to use for NAT + traversal, as dotted-quad IPv4 address literals or RFC2373 + IPv6 address literals. Change notification is via the + <tp:member-ref>STUNServersChanged</tp:member-ref> + signal. The IP addresses MUST NOT be given as DNS hostnames.</p> + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RelayInfo" type="aa{sv}" access="read" + tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Well-known map keys are:</p> + + <dl> + <dt><code>ip</code> - s</dt> + <dd>The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + </tp:rationale> + </dd> + + <dt><code>type</code> - s</dt> + <dd> + <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this + key is omitted), <code>tcp</code> for TCP, or + <code>tls</code>.</p> + + <p>The precise meaning of this key depends on the + <tp:member-ref>Transport</tp:member-ref> property: if + Transport is ICE, <code>tls</code> means + TLS over TCP as referenced by ICE draft 19, and if + Transport is GTalk_P2P, <code>tls</code> means + a fake SSL session over TCP as implemented by libjingle.</p> + </dd> + + <dt><code>port</code> - q</dt> + <dd>The UDP or TCP port of the relay server as an ASCII unsigned + integer</dd> + + <dt><code>unique-id</code> - s</dt> + <dd>A string identifying the relay server. If two RelayInfo entries + have the same unique-id, but different <code>type</code>s, there + is usually little point in connecting to both. Use + <code>priority</code> to determine which version to prefer in this + case. Can also be used by the streaming implementation to avoid + connecting to the same relay multiple times if relaying is + required for both audio and video.</dd> + + <dt><code>priority</code> - u</dt> + <dd>A number determining which version of a server to prefer (if + multiple are present with the same <code>unique-id</code>, + the one with the highest priority should be used, or the streaming + implementation should use the one whose <code>type</code> has the + most desirable properties)</dd> + + <dt><code>username</code> - s</dt> + <dd>The username to use</dd> + + <dt><code>password</code> - s</dt> + <dd>The password to use</dd> + + <dt><code>component</code> - u</dt> + <dd>The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + <tp:rationale> + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + </tp:rationale> + </dd> + </dl> + + <tp:rationale> + <p>An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.</p> + </tp:rationale> + + <p>The type of relay server that this represents depends on + the value of the <tp:member-ref>Transport</tp:member-ref> + property. If Transport is ICE, this is a TURN server; + if Transport is GTalk_P2P, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.</p> + + <p>If relaying is not possible for this stream, the list is + empty.</p> + + <p>Change notification is given via the + <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="ServerInfoRetrieved" + tp:name-for-bindings="Server_Info_Retrieved"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that the initial information about STUN and Relay servers + has been retrieved, i.e. the + <tp:member-ref>HasServerInfo</tp:member-ref> property is + now true.</p> + </tp:docstring> + </signal> + + <property name="HasServerInfo" type="b" + tp:name-for-bindings="Has_Server_Info" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the + <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p> + + <tp:rationale> + Streaming implementations that can't cope with STUN and + relay servers being added later SHOULD wait for this + property to become true before proceeding. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="EndpointsChanged" + tp:name-for-bindings="Endpoints_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property + changes. + </tp:docstring> + <arg name="Endpoints_Added" type="ao"> + <tp:docstring> + Endpoints that were added. + </tp:docstring> + </arg> + <arg name="Endpoints_Removed" type="ao"> + <tp:docstring> + Endpoints that no longer exist. + </tp:docstring> + </arg> + </signal> + + <property name="Endpoints" tp:name-for-bindings="Endpoints" + type="ao" access="read"> + <tp:docstring> + <p>The list of <tp:dbus-ref namespace="imt1.Call1.Stream" + >Endpoint</tp:dbus-ref> objects that exist for this + stream.</p> + + <p>Change notification is via the + <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="ICERestartRequested" + tp:name-for-bindings="ICE_Restart_Requested"> + <tp:docstring> + Emitted when the remote side requests an ICE restart (e.g. third party + call control, when the remote endpoint changes). The streaming + implementation should call + <tp:member-ref>SetCredentials</tp:member-ref> again. + </tp:docstring> + </signal> + + <property name="ICERestartPending" + tp:name-for-bindings="ICE_Restart_Pending" access="read" type="b"> + <tp:docstring> + State recovery for <tp:member-ref>ICERestartRequested</tp:member-ref>. + Set when the signal is emitted, and unset when + <tp:member-ref>SetCredentials</tp:member-ref> is called. + Useful for debugging. + </tp:docstring> + </property> + + <method name="Fail" tp:name-for-bindings="Fail"> + <tp:docstring> + Signal an unrecoverable error for this stream, and remove it. If all + streams are removed from a content, then it will also be removed. + </tp:docstring> + <arg direction="in" name="Reason" type="(uuss)" + tp:type="Call_State_Reason"> + <tp:docstring> + A structured reason for stream removal. + </tp:docstring> + </arg> + </method> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |