diff options
Diffstat (limited to 'spec/Channel_Interface_Hold.xml')
| -rw-r--r-- | spec/Channel_Interface_Hold.xml | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml new file mode 100644 index 0000000..ef5a08f --- /dev/null +++ b/spec/Channel_Interface_Hold.xml @@ -0,0 +1,222 @@ +<?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:xor-requires> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> + </tp:xor-requires> + <tp:changed version="0.17.4">first API-stable version</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels where you may put the channel on hold. + This only makes sense for channels where + you are streaming media to or from the members. (To see whether the + other participant has put you on hold, see <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref>.)</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> + + <method name="GetHoldState" tp:name-for-bindings="Get_Hold_State"> + <tp:docstring> + Return whether the local user has placed the channel on hold. + </tp:docstring> + + <arg name="HoldState" direction="out" type="u" + tp:type="Local_Hold_State"> + <tp:docstring> + The state of the channel + </tp:docstring> + </arg> + + <arg name="Reason" direction="out" type="u" + tp:type="Local_Hold_State_Reason"> + <tp:docstring> + The reason why the channel is in that state + </tp:docstring> + </arg> + </method> + + <signal name="HoldStateChanged" tp:name-for-bindings="Hold_State_Changed"> + <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 + <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a + result of a request from + another process. + </tp:docstring> + + <arg name="HoldState" type="u" tp:type="Local_Hold_State"> + <tp:docstring> + The state of the channel + </tp:docstring> + </arg> + + <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason"> + <tp:docstring> + The reason for the state change + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Local_Hold_State" type="u"> + <tp:docstring> + The hold state of a channel. + </tp:docstring> + + <tp:enumvalue value="0" suffix="Unheld"> + <tp:docstring> + All streams are unheld (the call is active). New channels SHOULD + have this hold state. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Held"> + <tp:docstring> + All streams are held (the call is on hold) + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Pending_Hold"> + <tp:docstring> + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="3" suffix="Pending_Unhold"> + <tp:docstring> + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Local_Hold_State_Reason" type="u"> + <tp:docstring> + The reason for a change to the Local_Hold_State. Clients MUST + treat unknown values as equivalent to Local_Hold_State_Reason_None. + </tp:docstring> + + <tp:enumvalue value="0" suffix="None"> + <tp:docstring> + The reason cannot be described by any of the predefined values + (connection managers SHOULD avoid this reason, but clients MUST + handle it gracefully) + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Requested"> + <tp:docstring> + The change is in response to a user request + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Resource_Not_Available"> + <tp:docstring> + The change is because some resource was not available + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="RequestHold" tp:name-for-bindings="Request_Hold"> + <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 xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the channel be put on hold (be instructed not to send + any media streams to you) or be taken off hold.</p> + + <p>If the connection manager can immediately tell that the requested + state change could not possibly succeed, this method SHOULD + return the NotAvailable error. If the requested state is the + same as the current state, this method SHOULD return successfully + without doing anything.</p> + + <p>Otherwise, this method SHOULD immediately set the hold state to + Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold + (as appropriate), emitting + <tp:member-ref>HoldStateChanged</tp:member-ref> if this is a change, + and return successfully.</p> + + <p>The eventual success or failure of the request is indicated by a + subsequent HoldStateChanged signal, changing the hold state to + Local_Hold_State_Held or Local_Hold_State_Unheld.</p> + + <p>If the channel has multiple streams, and the connection manager + succeeds in changing the hold state of one stream but fails to + change the hold state of another, it SHOULD attempt to revert + all streams to their previous hold states.</p> + + <p>The following state transitions SHOULD be used, where + appropriate:</p> + + <ul> + <li>Successful hold: + (Unheld, any reason) → (Pending_Hold, Requested) → + (Held, Requested) + </li> + <li>Successful unhold: + (Held, any reason) → (Pending_Unhold, Requested) → + (Unheld, Requested) + </li> + <li>Attempting to unhold fails at the first attempt to acquire a + resource: + (Held, any reason) → (Pending_Unhold, Requested) → + (Held, Resource_Not_Available) + </li> + <li>Attempting to unhold acquires one resource, but fails to acquire + a second, and takes time to release the first: + (Held, any reason) → (Pending_Unhold, Requested) → + (Pending_Hold, Resource_Not_Available) → + (Held, Resource_Not_Available) + </li> + </ul> + </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: --> |