summaryrefslogtreecommitdiff
path: root/spec/Call_Stream.xml
blob: 5f1321eb62b5ea1469fa51c071d25430a66866a1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<?xml version="1.0" ?>
<node name="/Call_Stream"
  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="org.freedesktop.Telepathy.Call1.Stream">
    <tp:added version="0.19.0">(draft 1)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>One stream inside a <tp:dbus-ref
      namespace="ofdT.Call1">Content</tp:dbus-ref>.  A stream is
      a single flow of packets to and from a single remote endpoint.
      If your call connects to multiple people, you could have
      multiple streams.</p>
      <p>For protocols that support muting streams separately, this object MAY
      also implement the <tp:dbus-ref
      namespace="ofdT.Call1.Interface">Mute</tp:dbus-ref> interface</p>
    </tp:docstring>

    <method name="SetSending" tp:name-for-bindings="Set_Sending">
      <tp:docstring>
        Set the stream to start or stop sending media from the local
        user to other contacts.
      </tp:docstring>

      <arg name="Send" type="b" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If True, the
            <tp:member-ref>LocalSendingState</tp:member-ref> should
            change to <tp:value-ref type="Sending_State">Sending</tp:value-ref>, if it isn't
            already.</p>

          <p>If False, the
            <tp:member-ref>LocalSendingState</tp:member-ref> should
            change to <tp:value-ref type="Sending_State">None</tp:value-ref>, if it isn't
            already.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
        <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
          <tp:docstring>If the call has not been accepted yet, calling
            SetSending(True) is an error. See
            <tp:member-ref>LocalSendingState</tp:member-ref> for details.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
      <tp:docstring>
        <p>Request that a remote contact stops or starts sending on
          this stream.</p>

        <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref>
          property defines whether the protocol allows the local user to
          request the other side start sending on this stream.</p>
      </tp:docstring>

      <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Contact from which sending is requested</p>
        </tp:docstring>
      </arg>

      <arg name="Receive" type="b" direction="in">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>If true, request that the given contact starts to send media.
            If false, request that the given contact stops sending media.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The request contact is valid but is not involved in this
            stream.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The protocol does not allow the local user to request the
            other side starts sending on this stream.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="RemoteMembersChanged"
        tp:name-for-bindings="Remote_Members_Changed">
      <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed>
      <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes.
      </tp:docstring>

      <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
        <tp:docstring>
          A mapping from channel-specific handles to their updated sending
          state, whose keys include at least the members who were added,
          and the members whose states changed.
        </tp:docstring>
      </arg>
      <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The identifiers of the contacts in the <var>Updates</var> map.
        </tp:docstring>
      </arg>
      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          The channel-specific handles that were removed from the keys
          of the <tp:member-ref>RemoteMembers</tp:member-ref>
          property, as a result of the contact leaving this stream
        </tp:docstring>
      </arg>
      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
        <tp:docstring>
          A structured reason for the change.
        </tp:docstring>
      </arg>
    </signal>

    <signal name="LocalSendingStateChanged"
        tp:name-for-bindings="Local_Sending_State_Changed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes.
      </tp:docstring>

      <arg name="State" type="u" tp:type="Sending_State">
        <tp:docstring>
          The new value of
          <tp:member-ref>LocalSendingState</tp:member-ref>.
        </tp:docstring>
      </arg>

      <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason">
        <tp:docstring>
          A structured reason for the change.
        </tp:docstring>
      </arg>
    </signal>

    <tp:enum name="Sending_State" type="u">
      <tp:docstring>
        Enum indicating whether a contact is sending media.
      </tp:docstring>

      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          The contact is not sending media and has not been asked to
          do so.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Pending_Send" value="1">
        <tp:docstring>
          The contact has been asked to start sending media.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Sending" value="2">
        <tp:docstring>
          The contact is sending media.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Pending_Stop_Sending" value="3">
        <tp:docstring>
          The contact has been asked to stop sending media.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:mapping name="Contact_Sending_State_Map">
      <tp:docstring>
        A map from a contact to his or her sending state.
      </tp:docstring>
      <tp:member name="Contact" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The contact handle.
        </tp:docstring>
      </tp:member>
      <tp:member name="Sending" type="u" tp:type="Sending_State">
         <tp:docstring>
           The sending state of the contact.
         </tp:docstring>
      </tp:member>
    </tp:mapping>

    <property name="Interfaces" tp:name-for-bindings="Interfaces"
      type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
      <tp:added version="0.19.11"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Extra interfaces provided by this stream, such as <tp:dbus-ref
            namespace="ofdT.Call1">Stream.Interface.Media</tp:dbus-ref>.
          This SHOULD NOT include the Stream interface itself, and cannot
          change once the stream has been created.</p>
      </tp:docstring>
    </property>

    <property name="RemoteMembers" tp:name-for-bindings="Remote_Members"
        type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
      <tp:changed version="0.21.2">renamed from Senders</tp:changed>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A map from remote contacts to their sending state.</p>

        <p>Media sent to this stream will be sent to all members listed here.
          All members listed here will also appear in <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">CallMembers</tp:dbus-ref>,
          and each CallMembers member will be listed in at most one Stream per
          Content. Therefore, to hide things from a member of the
          call, UIs only need to mute one Stream per Content.</p>

        <p>Contacts' handles in this map indicate whether they are
          sending media to this stream. Sending_State_Pending_Send indicates
          contacts who are not sending but have been asked to do so. The
          local user's sending state is shown in <tp:member-ref
          >LocalSendingState</tp:member-ref>.</p>

        <p>This mapping is also used by the streaming implementation to map
          from <tp:dbus-ref namespace="ofdT.Call1.Content"
          >MediaDescription</tp:dbus-ref>s to Streams. In this use-case,
          all of the senders in this stream will be represented in
          <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media"
          >RemoteMediaDescriptions</tp:dbus-ref>. This use-case should not
          affect anything that does not handle media streaming.</p>
      </tp:docstring>
    </property>

    <property name="RemoteMemberIdentifiers" type="a{us}" tp:type="Handle_Identifier_Map"
      access="read" tp:name-for-bindings="Remote_Member_Identifiers">
      <tp:docstring>
        The string identifiers for handles mentioned in
        <tp:member-ref>RemoteMembers</tp:member-ref>, to
        give clients the minimal information necessary to create contacts
        without waiting for round-trips.
      </tp:docstring>
    </property>

    <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State"
        type="u" access="read" tp:type="Sending_State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The local user's sending state. Media sent on this stream
          should be assumed to be received, directly or indirectly, by
          every other contact in the
          <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change
          notification is given via the
          <tp:member-ref>LocalSendingStateChanged</tp:member-ref>
          signal.</p>

        <tp:rationale>
          Implementations of the first Call draft had the self handle
          in the <tp:member-ref>RemoteMembers</tp:member-ref> (then
          called Members) map and this showed that it's annoying
          having to keep track of the self handle so that it can be
          special-cased.
        </tp:rationale>

        <p>A value of <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> for
          this property indicates that the other side requested the
          local user start sending media (which can be done by calling either
          <tp:member-ref>SetSending</tp:member-ref> or <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref>).</p>

        <p>When <tp:dbus-ref
          namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is
          called, all streams with a local sending state of
          <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> and the associated
          <tp:dbus-ref namespace="ofdT.Call1.Content"
          >Disposition</tp:dbus-ref> set to
          <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref> are
          automatically set to sending.</p>
      </tp:docstring>
    </property>

    <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving"
        type="b" access="read" tp:immutable="yes">
      <tp:added version="0.21.2"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If true, the user can request that a remote contact starts
          sending on this stream.</p>

        <tp:rationale>Not all protocols allow the user to ask the
          other side to start sending media.</tp:rationale>
      </tp:docstring>
    </property>
  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->