diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_Chat_State.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_Chat_State.xml | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Interface_Chat_State.xml b/qt4/spec/Channel_Interface_Chat_State.xml new file mode 100644 index 000000000..27515d2e8 --- /dev/null +++ b/qt4/spec/Channel_Interface_Chat_State.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Chat_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2007 Collabora Limited </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.Channel.Interface.ChatState"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + + <tp:mapping name="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring>A map from contacts to their chat states.</tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact</tp:docstring> + </tp:member> + <tp:member name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring>The contact's chat state</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="ChatStates" tp:name-for-bindings="Chat_States" + access="read" type="a{uu}" tp:type="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map containing the chat states of all contacts in this + channel whose chat state is not Inactive.</p> + + <p>Contacts in this channel, but who are not listed in this map, + may be assumed to be in the Inactive state.</p> + + <p>In implementations that do not have this property, its value may be + assumed to be empty until a + <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates + otherwise.</p> + + <tp:rationale> + <p>This property was not present in older versions of telepathy-spec, + because chat states in XMPP are not state-recoverable (if you + miss the change notification signal, there's no way to know the + state). However, this property still allows clients to recover + state changes that were seen by the CM before the client started + to deal with the channel.</p> + + <p>In CMs that follow older spec versions, assuming Inactive will + mean that initial chat states will always be assumed to be + Inactive, which is the best we can do. XEP 0085 specifies + Inactive as the "neutral" state to be assumed unless told + otherwise.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="SetChatState" tp:name-for-bindings="Set_Chat_State"> + <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring> + The new state. + </tp:docstring> + </arg> + <tp:docstring> + Set the local state and notify other members of the channel that it + has changed. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + <signal name="ChatStateChanged" tp:name-for-bindings="Chat_State_Changed"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring> + The new state of this contact. + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the state of a member of the channel has changed. + This includes local state. + </tp:docstring> + </signal> + <tp:enum name="Channel_Chat_State" type="u"> + <tp:enumvalue suffix="Gone" value="0"> + <tp:docstring> + The contact has effectively ceased participating in the chat. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Inactive" value="1"> + <tp:docstring> + The contact has not been active for some time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Active" value="2"> + <tp:docstring> + The contact is actively participating in the chat. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Paused" value="3"> + <tp:docstring> + The contact has paused composing a message. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Composing" value="4"> + <tp:docstring> + The contact is composing a message to be sent to the chat. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for channels for receiving notifications of remote contacts' + state, and for notifying remote contacts of the local state.</p> + + <p>Clients should assume that a contact's state is Channel_Chat_State_Inactive + unless they receive a notification otherwise.</p> + + <p>The Channel_Chat_State_Gone state is treated differently to other states:</p> + <ul> + <li>It may not be used for multi-user chats</li> + <li>It may not be explicitly sent</li> + <li>It should be automatically sent when the channel is closed</li> + <li>It must not be sent to the peer if a channel is closed without being used</li> + <li>Receiving it must not cause a new channel to be opened</li> + </ul> + + <p>The different states are defined by XEP-0085, but may be applied to any suitable protocol.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |