git.maemo.org Git - theonering/blob - src/tp/_generated/Channel_Type_Streamed_Media.py

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """ Copyright © 2005-2009 Collabora Limited
   4  Copyright © 2005-2009 Nokia Corporation
   5  Copyright © 2006 INdT
   6
   7     This library is free software; you can redistribute it and/or
   8 modify it under the terms of the GNU Lesser General Public
   9 License as published by the Free Software Foundation; either
  10 version 2.1 of the License, or (at your option) any later version.
  11
  12 This library is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 Lesser General Public License for more details.
  16
  17 You should have received a copy of the GNU Lesser General Public
  18 License along with this library; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ChannelTypeStreamedMedia(dbus.service.Interface):
  27     """\
  28       A channel that can send and receive streamed media such as audio or video.
  29     Provides a number of methods for listing and requesting new streams, and
  30     signals to indicate when streams have been added, removed and changed
  31     status.
  32
  33       To make a media call to a contact, clients should call CreateChannel
  34         with ChannelType
  35         = StreamedMedia,
  36         TargetHandleType
  37         = Contact, and one of TargetHandle
  38         or TargetID
  39         (which should yield a channel with the local user in Members,
  40         and the remote contact as TargetHandle
  41         but not in any group members list), then call
  42         RequestStreams to initiate the call (at
  43         which point the contact should appear in the channel's RemotePendingMembers).
  44
  45       In the past, several other patterns have been used to place outgoing
  46         calls; see
  47         'Requesting StreamedMedia Channels' on the Telepathy wiki
  48         for the details.
  49
  50       Incoming calls should be signalled as TargetHandleType
  51         = Contact, TargetHandle
  52         set to the remote contact, with the local user in LocalPendingMembers;
  53         to accept the call, AddMembers
  54         can be used to move the local user to the group's members.
  55
  56       When the local user accepts an incoming call, the connection manager
  57         SHOULD change the direction of any streams with pending local send
  58         to be sending, without altering whether those streams are
  59         receiving.
  60
  61
  62         This matches existing practice, and means that a client
  63           can answer incoming calls and get an unmuted microphone/activated
  64           webcam without having to take additional action to accept the
  65           stream directions.
  66
  67         It does, however, introduce a race condition: a client believing
  68           that it is accepting an audio-only call by calling AddMembers
  69           can inadvertantly accept an audio + video call (and hence activate
  70           sending from a webcam without the user's permission) if a video
  71           stream is added just before AddMembers is processed. This race
  72           should be removed when this specification is revised.
  73
  74
  75     In general this should be used in conjunction with the MediaSignalling
  76     interface to exchange connection candidates and codec choices with
  77     whichever component is responsible for the streams. However, in certain
  78     applications where no candidate exchange is necessary (eg the streams are
  79     handled by specialised hardware which is controlled directly by the
  80     connection manager), the signalling interface can be omitted and this
  81     channel type used simply to control the streams.
  82     """
  83
  84     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', in_signature='', out_signature='a(uuuuuu)')
  85     def ListStreams(self):
  86         """
  87         Returns an array of structs representing the streams currently active
  88         within this channel. Each stream is identified by an unsigned integer
  89         which is unique for each stream within the channel.
  90
  91         """
  92         raise NotImplementedError
  93
  94     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', in_signature='au', out_signature='')
  95     def RemoveStreams(self, Streams):
  96         """
  97         Request that the given streams are removed. If all streams are
  98           removed, the channel MAY close.
  99
 100         Clients SHOULD NOT attempt to terminate calls by removing all the
 101           streams; instead, clients SHOULD terminate calls by removing the
 102           Group.SelfHandle
 103           from the channel, using either
 104           RemoveMembers
 105           or
 106           RemoveMembersWithReason.
 107
 108
 109         """
 110         raise NotImplementedError
 111
 112     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', in_signature='uu', out_signature='')
 113     def RequestStreamDirection(self, Stream_ID, Stream_Direction):
 114         """
 115         Request a change in the direction of an existing stream. In particular,
 116         this might be useful to stop sending media of a particular type,
 117         or inform the peer that you are no longer using media that is being
 118         sent to you.
 119
 120         Depending on the protocol, streams which are no longer sending in
 121         either direction should be removed and a
 122         StreamRemoved signal emitted.
 123         Some direction changes can be enforced locally (for example,
 124         BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending),
 125         others may not be possible on some protocols, and some need agreement
 126         from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND
 127         flag will be set in the
 128         StreamDirectionChanged signal, and the
 129         signal
 130         emitted again without the flag to indicate the resulting direction when
 131         the remote end has accepted or rejected the change.
 132
 133         """
 134         raise NotImplementedError
 135
 136     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', in_signature='uau', out_signature='a(uuuuuu)')
 137     def RequestStreams(self, Contact_Handle, Types):
 138         """
 139         Request that streams be established to exchange the given types of
 140         media with the given member. In general this will try and establish a
 141         bidirectional stream, but on some protocols it may not be possible to
 142         indicate to the peer that you would like to receive media, so a
 143         send-only stream will be created initially. In the cases where the
 144         stream requires remote agreement (eg you wish to receive media from
 145         them), the StreamDirectionChanged signal
 146         will be emitted with the
 147         MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
 148         with the flag cleared when the remote end has replied.
 149
 150         If streams of the requested types already exist, calling this
 151           method results in the creation of additional streams. Accordingly,
 152           clients wishing to have exactly one audio stream or exactly one
 153           video stream SHOULD check for the current streams using
 154           ListStreams before calling this
 155           method.
 156
 157         """
 158         raise NotImplementedError
 159
 160     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', signature='uuu')
 161     def StreamAdded(self, Stream_ID, Contact_Handle, Stream_Type):
 162         """
 163         Emitted when a new stream has been added to this channel.
 164           Clients SHOULD assume that the stream's
 165           Media_Stream_State is initially Disconnected.
 166
 167         If a connection manager needs to represent the addition of a stream
 168           whose state is already Connecting or Connected, it MUST do this
 169           by emitting StreamAdded, closely followed by
 170           StreamStateChanged indicating a
 171           change to the appropriate state.
 172
 173
 174           Historically, it was not clear from the StreamAdded signal what
 175             the state of the stream was. telepathy-spec 0.17.22
 176             clarified this.
 177
 178
 179         Similarly, clients SHOULD assume that the initial
 180           Media_Stream_Direction of a newly added stream
 181           is Receive, and that the initial
 182           Media_Stream_Pending_Send is
 183           Pending_Local_Send.
 184
 185         If a connection manager needs to represent the addition of a stream
 186           whose direction or pending-send differs from those initial values,
 187           it MUST do so by emitting StreamAdded, closely followed by
 188           StreamDirectionChanged indicating a
 189           change to the appropriate direction and pending-send state.
 190
 191
 192           StreamAdded doesn't itself indicate the stream's direction; this
 193             is unfortunate, but is preserved for compatibility.
 194
 195           This is the appropriate direction for streams added by a remote
 196             contact on existing connection managers, and does not violate
 197             user privacy by automatically sending audio or video (audio streams
 198             start off muted, video streams start off not sending). For
 199             streams added by the local user using the client receiving the
 200             signal, the true direction can also be determined from the return
 201             value of the RequestStreams
 202             method.
 203
 204           Existing clients typically operate by maintaining a separate
 205             idea of the directions that they would like the streams to have,
 206             and enforcing these intended directions by calling
 207             RequestStreamDirection whenever
 208             needed.
 209
 210
 211         """
 212         pass
 213
 214     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', signature='uuu')
 215     def StreamDirectionChanged(self, Stream_ID, Stream_Direction, Pending_Flags):
 216         """
 217         Emitted when the direction or pending flags of a stream are
 218           changed.
 219
 220         If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user
 221           has requested that we begin sending on this stream.
 222           RequestStreamDirection
 223           should be called to indicate whether or not this change is
 224           acceptable.
 225
 226
 227           This allows for a MSN-style user interface, "Fred has asked you
 228             to enable your webcam. (Accept | Reject)", if desired.
 229
 230
 231         """
 232         pass
 233
 234     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', signature='uus')
 235     def StreamError(self, Stream_ID, Error_Code, Message):
 236         """
 237         Emitted when a stream encounters an error.
 238
 239         """
 240         pass
 241
 242     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', signature='u')
 243     def StreamRemoved(self, Stream_ID):
 244         """
 245         Emitted when a stream has been removed from this channel.
 246
 247         """
 248         pass
 249
 250     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.StreamedMedia', signature='uu')
 251     def StreamStateChanged(self, Stream_ID, Stream_State):
 252         """
 253         Emitted when a member's stream's state changes.
 254
 255         """
 256         pass
 257