summaryrefslogtreecommitdiff
path: root/extensions/Channel_Interface_Hold.xml
blob: 6e04ffb3a3370eb4ef10d096fad92a4e74741c0d (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
<?xml version="1.0" ?>
<node name="/Channel_Interface_Hold" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
  <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
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.

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.

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.
  </tp:license>

  <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"
    tp:causes-havoc='not yet API-stable'>
    <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Interface for channels where you or other members may put
        the channel on hold. This only makes sense for channels where
        you are streaming media to or from the members.</p>

      <p>If you are placed on hold, this indicates that some or all members
        of the channel will no longer be receiving media streams from you.
        If the channel has the MediaSignalling interface, client applications
        should stop sending media to all members of the channel.</p>

      <p>Depending on the protocol, it might not be possible to tell that
        you're on hold, in which case the connection manager should always
        indicate that you're not on hold unless it finds out otherwise.</p>

      <p>If you place a channel on hold, this indicates that you do not wish
        to be sent media streams by any of its members and will be ignoring
        any media streams you continue to receive. It also requests that the
        connection manager free up any resources that are only needed for
        an actively used channel (e.g. in a GSM or PBX call, it will be
        necessary to place an active call on hold before you can start
        another call).</p>
    </tp:docstring>

    <tp:enum name="Channel_Hold_State" type="u">
      <tp:docstring>
        The possible hold states of a call.
      </tp:docstring>
      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          Neither the local user nor a remote member have placed the call on
          hold.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Local" value="1">
        <tp:docstring>
          The local user has put the call on hold.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Remote" value="2">
        <tp:docstring>
          The call has been put on hold by a remote member.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Both" value="3">
        <tp:docstring>
          The local user and a remote member have both placed the call
          on hold.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <method name="GetHoldState">
      <arg direction="out" type="u" tp:type="Channel_Hold_State">
        <tp:docstring>
          The channel's current hold state
        </tp:docstring>
      </arg>
      <tp:docstring>
        Return the channel's current hold state.
      </tp:docstring>
    </method>

    <signal name="HoldStateChanged">
      <arg name="state" type="u" tp:type="Channel_Hold_State">
        <tp:docstring>
          An integer representing the new hold state
        </tp:docstring>
      </arg>
      <tp:docstring>
        Emitted to indicate that the hold state has changed for this channel.
        This may occur as a consequence of you requesting a change with
        RequestHold, or the state changing as a result of a request from a
        remote member or another process.
      </tp:docstring>
    </signal>

    <method name="RequestHold">
      <arg direction="in" name="hold" type="b">
        <tp:docstring>
          A boolean indicating whether or not the channel should be on hold
        </tp:docstring>
      </arg>
      <tp:docstring>
        Request that the channel be put on hold (be instructed not to send
        any media streams to you) or be taken off hold. Success is indicated
        by the HoldStateChanged signal being emitted and by a successful
        return from this method.
      </tp:docstring>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The requested hold state cannot be achieved; for example,
            if only a limited number of channels can be in the "not on hold"
            state, attempts to exceed this number will raise NotAvailable.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->