diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_Group.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_Group.xml | 1166 |
1 files changed, 0 insertions, 1166 deletions
diff --git a/qt4/spec/Channel_Interface_Group.xml b/qt4/spec/Channel_Interface_Group.xml deleted file mode 100644 index 92de9c5c4..000000000 --- a/qt4/spec/Channel_Interface_Group.xml +++ /dev/null @@ -1,1166 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2006 INdT</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.Group"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List"> - <tp:docstring>A structure representing a contact whose attempt to - join a group is to be confirmed by the local user using - <tp:member-ref>AddMembers</tp:member-ref>.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added"> - <tp:docstring> - The contact to be added to the group - </tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Contact_Handle" name="Actor"> - <tp:docstring> - The contact requesting or causing the change - </tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason"> - <tp:docstring> - The reason for the change - </tp:docstring> - </tp:member> - <tp:member type="s" name="Message"> - <tp:docstring> - A human-readable message from the Actor, or an empty string - if there is no message - </tp:docstring> - </tp:member> - </tp:struct> - - <method name="AddMembers" tp:name-for-bindings="Add_Members"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to invite to the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Invite all the given contacts into the channel, or accept requests for - channel membership for contacts on the pending local list.</p> - - <p>A message may be provided along with the request, which will be sent - to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and - CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT - <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this - message should be provided.</p> - - <p>Attempting to add contacts who are already members is allowed; - connection managers must silently accept this, without error.</p> - </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:error name="org.freedesktop.Telepathy.Error.NotCapable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> - </tp:possible-errors> - </method> - - <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members"> - <tp:deprecated version="0.17.6">Use GetAll on the D-Bus - Properties D-Bus interface to get properties including Members, - RemotePendingMembers and LocalPendingMembers instead, falling back to - this method and GetLocalPendingMembersWithInfo if necessary. - </tp:deprecated> - - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Members"> - <tp:docstring> - array of handles of current members - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Local_Pending"> - <tp:docstring> - array of handles of local pending members - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Remote_Pending"> - <tp:docstring> - array of handles of remote pending members - </tp:docstring> - </arg> - <tp:docstring> - Returns arrays of all current, local and remote pending channel - members. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u"> - <tp:flag suffix="Can_Add" value="1"> - <tp:docstring> - The <tp:member-ref>AddMembers</tp:member-ref> method can be used to - add or invite members who are - not already in the local pending list (which is always valid). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Can_Remove" value="2"> - <tp:docstring> - The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used - to remove channel members - (removing those on the pending local list is always valid). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Can_Rescind" value="4"> - <tp:docstring> - The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used - on people on the remote - pending list. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Add" value="8"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>AddMembers</tp:member-ref> on - contacts who are not currently pending members. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Remove" value="16"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are currently channel members. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Accept" value="32"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>AddMembers</tp:member-ref> on - contacts who are locally pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Reject" value="64"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are locally pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Rescind" value="128"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are remote pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Channel_Specific_Handles" value="256"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - The members of this group have handles which are specific to - this channel, and are not valid as general-purpose handles on - the connection. Depending on the channel, it may be possible to - check the <tp:member-ref>HandleOwners</tp:member-ref> property or - call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the - owners of these handles, which should be done if you wish to (e.g.) - subscribe to the contact's presence. - </p> - - <p> - Connection managers must ensure that any given handle is not - simultaneously a general-purpose handle and a channel-specific - handle. - </p> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Only_One_Group" value="512"> - <tp:docstring> - Placing a contact in multiple groups of this type is not allowed - and will raise NotAvailable (on services where contacts may only - be in one user-defined group, user-defined groups will have - this flag). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Handle_Owners_Not_Available" value="1024"> - <tp:docstring> - In rooms with channel specific handles (ie Channel_Specific_Handles - flag is set), this flag indicates that no handle owners are - available, apart from the owner of the - <tp:member-ref>SelfHandle</tp:member-ref>. - - <tp:rationale> - This used to be an important optimization to avoid repeated - GetHandleOwners calls, before we introduced the - <tp:member-ref>HandleOwners</tp:member-ref> property and - <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. - </tp:rationale> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Properties" value="2048"> - <tp:docstring> - This flag indicates that all the properties introduced in - specification 0.17.6 are fully supported. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Members_Changed_Detailed" value="4096"> - <tp:docstring> - Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref> - will be emitted for changes to this group's members in addition to - <tp:member-ref>MembersChanged</tp:member-ref>. - Clients can then connect to the former and ignore emission of the - latter. This flag's state MUST NOT change over the lifetime of a - channel. - - <tp:rationale> - If it were allowed to change, client bindings would have to always - connect to MembersChanged just in case the flag ever went away (and - generally be unnecessarily complicated), which would mostly negate - the point of having this flag in the first place. - </tp:rationale> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Depart" value="8192"> - <tp:added version="0.17.21"/> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - the <tp:member-ref>SelfHandle</tp:member-ref>. - - <tp:rationale> - This would be set for XMPP Multi-User Chat or IRC channels, - but not for a typical implementation of streamed media calls. - </tp:rationale> - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags" - access="read" tp:name-for-bindings="Group_Flags"> - <tp:docstring> - An integer representing the bitwise-OR of flags on this - channel. The user interface can use this to present information about - which operations are currently valid. Change notification is via - the <tp:member-ref>GroupFlagsChanged</tp:member-ref> signal. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetGroupFlags if - Channel_Group_Flag_Properties is not present.</tp:added> - </property> - - <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags"> - <arg direction="out" type="u" tp:type="Channel_Group_Flags" - name="Group_Flags"> - <tp:docstring> - The value of the GroupFlags property - </tp:docstring> - </arg> - <tp:docstring> - Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use GetAll on the D-Bus - Properties D-Bus interface to get properties including GroupFlags - instead, falling back to this method if necessary.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:mapping name="Handle_Owner_Map"> - <tp:docstring> - A map from channel-specific handles to their owners. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetHandleOwners if - Channel_Group_Flag_Properties is not present.</tp:added> - - <tp:member type="u" name="Channel_Specific_Handle" - tp:type="Contact_Handle"> - <tp:docstring> - A nonzero channel-specific handle - </tp:docstring> - </tp:member> - <tp:member type="u" name="Global_Handle" tp:type="Contact_Handle"> - <tp:docstring> - The global handle that owns the corresponding channel-specific - handle, or 0 if this could not be determined - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map" - access="read" tp:name-for-bindings="Handle_Owners"> - <tp:docstring> - A map from channel-specific handles to their owners, including - at least all of the channel-specific handles in this channel's members, - local-pending or remote-pending sets as keys. Any handle not in - the keys of this mapping is not channel-specific in this channel. - Handles which are channel-specific, but for which the owner is - unknown, MUST appear in this mapping with 0 as owner. Change - notification is via the - <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. - </tp:docstring> - <tp:added version="0.17.6"/> - </property> - - <signal name="HandleOwnersChanged" - tp:name-for-bindings="Handle_Owners_Changed"> - <tp:docstring> - Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref> - property changes. - </tp:docstring> - <tp:added version="0.17.6">This signal should not be relied on - unless Channel_Group_Flag_Properties is present.</tp:added> - - <arg name="Added" type="a{uu}" tp:type="Handle_Owner_Map"> - <tp:docstring> - A map from channel-specific handles to their owners, in which the - keys include all the handles that were added to the keys of the - HandleOwners property, and all the handles in that property whose - owner has changed - </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 - HandleOwners property, as a result of the contact leaving this group - in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal - </tp:docstring> - </arg> - </signal> - - <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners"> - <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of integer handles representing members of the channel - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners"> - <tp:docstring> - An array of integer handles representing the owner handles of - the given room members, in the same order, or 0 if the - owner is not available - </tp:docstring> - </arg> - <tp:docstring> - If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on - the channel, then the handles of the group members are specific - to this channel, and are not meaningful in a connection-wide - context such as contact lists. This method allows you to find - the owner of the handle if it can be discovered in this channel, - or 0 if the owner is not available. - </tp:docstring> - <tp:deprecated version="0.17.6">Clients should use the - HandleOwners property and HandleOwnersChanged signal if - Channel_Group_Flag_Properties is present.</tp:deprecated> - <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.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag, - so handles in this channel are globally meaningful and calling - this method is not necessary - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - One of the given handles is not a member - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetLocalPendingMembers" - tp:name-for-bindings="Get_Local_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns the To_Be_Added handle (only) for each structure in the - <tp:member-ref>LocalPendingMembers</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the LocalPendingMembers - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <method name="GetLocalPendingMembersWithInfo" - tp:name-for-bindings="Get_Local_Pending_Members_With_Info"> - <tp:added version="0.15.0" /> - <tp:docstring> - Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the LocalPendingMembers - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]" - name="Info"> - <tp:docstring> - An array of structs containing: - <ul> - <li> - A handle representing the contact requesting channel membership - </li> - <li> - A handle representing the contact making the request, or 0 if - unknown - </li> - <li> - The reason for the request: one of the values of - <tp:type>Channel_Group_Change_Reason</tp:type> - </li> - <li> - A string message containing the reason for the request if any (or - blank if none) - </li> - </ul> - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <property name="LocalPendingMembers" access="read" - type="a(uuus)" tp:type="Local_Pending_Info[]" - tp:name-for-bindings="Local_Pending_Members"> - <tp:docstring> - An array of structs containing handles representing contacts - requesting channel membership and awaiting local approval with - <tp:member-ref>AddMembers</tp:member-ref>. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties is - not present, clients should fall back to using the - deprecated GetLocalPendingMembersWithInfo method, or fall back - from that to the deprecated GetAllMembers method.</tp:added> - </property> - - <property name="Members" tp:name-for-bindings="Members" - access="read" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The members of this channel. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties - is not set, fall back to calling GetAllMembers.</tp:added> - </property> - - <method name="GetMembers" tp:name-for-bindings="Get_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns the <tp:member-ref>Members</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the Members - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <property name="RemotePendingMembers" access="read" type="au" - tp:type="Contact_Handle[]" tp:name-for-bindings="Remote_Pending_Members"> - <tp:docstring> - An array of handles representing contacts who have been - invited to the channel and are awaiting remote approval. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties - is not set, fall back to calling GetAllMembers.</tp:added> - </property> - - <method name="GetRemotePendingMembers" - tp:name-for-bindings="Get_Remote_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns an array of handles representing contacts who have been - invited to the channel and are awaiting remote approval. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the - <tp:member-ref>RemotePendingMembers</tp:member-ref> - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed"> - <tp:docstring> - Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property - changes. - </tp:docstring> - <tp:added version="0.17.6">This signal should not be relied on - unless Channel_Group_Flag_Properties is present.</tp:added> - - <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> - <tp:docstring> - The new value of the SelfHandle property. - </tp:docstring> - </arg> - </signal> - - <property name="SelfHandle" type="u" tp:type="Contact_Handle" - access="read" tp:name-for-bindings="Self_Handle"> - <tp:docstring> - The handle for the user on this channel (which can also be a - local or remote pending member), or 0 if the user is not a member at - all (which is likely to be the case, for instance, on <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref> - channels). Note that this is different from the result of - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref> - on some protocols, so the value of this handle should - always be used with the methods of this interface. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetSelfHandle if - Channel_Group_Flag_Properties is not present.</tp:added> - </property> - - <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle" - name="Self_Handle"/> - <tp:docstring> - Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref> - property. - </tp:docstring> - <tp:deprecated version="0.17.6">Clients should retrieve the - SelfHandle property using GetAll instead, - if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <signal name="GroupFlagsChanged" tp:name-for-bindings="Group_Flags_Changed"> - <arg name="Added" type="u" tp:type="Channel_Group_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been set - </tp:docstring> - </arg> - <arg name="Removed" type="u" tp:type="Channel_Group_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been cleared - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the flags as returned by - <tp:member-ref>GetGroupFlags</tp:member-ref> are changed. - The user interface should be updated as appropriate. - </tp:docstring> - </signal> - - <tp:enum name="Channel_Group_Change_Reason" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The reason for a set of handles to move to one of - <tp:member-ref>Members</tp:member-ref>, - <tp:member-ref>LocalPendingMembers</tp:member-ref> or - <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed - from the group. A client may supply a reason when attempting to - remove members from a group with - <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons - are supplied by the CM when emitting - <tp:member-ref>MembersChanged</tp:member-ref> and - <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason - codes have different meanings depending on the <var>Actor</var> in a - MembersChanged signal.</p> - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>No reason was provided for this change.</p> - - <p>In particular, this reason SHOULD be used when representing - users joining a named chatroom in the usual way, users leaving - a chatroom by their own request, and normal termination of a - StreamedMedia call by the remote user.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed from - a group for this reason and the actor is not the SelfHandle, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Terminated</code>.</p> - - <p>If the SelfHandle is removed from a group for this reason and - the actor is also the SelfHandle, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Offline" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a user going offline. Also used when - user is already offline, but this wasn't known previously.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called is offline, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason Offline.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If a handle is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Offline</code>.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Kicked" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a kick operation.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Busy" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a busy indication.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called is busy, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason Busy.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Busy</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invited" value="4"> - <tp:docstring> - The change is due to an invitation. This reason SHOULD only be used - when contacts are added to the remote-pending set (to indicate that - the contact has been invited) or to the members (to indicate that - the contact has accepted the invitation). - - <tp:rationale> - Otherwise, what would it mean? - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Banned" value="5"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a kick+ban operation.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Error" value="6"> - <tp:docstring> - The change is due to an error occurring. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invalid_Contact" value="7"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because the requested contact does not exist.</p> - - <p>For instance, if the user invites a nonexistent contact to a - chatroom or attempts to call a nonexistent contact, this could - be indicated by the CM adding that contact's handle to - remote-pending for reason None or Invited, then removing it for - reason Invalid_Contact. In the case of a 1-1 StreamedMedia - call, the CM SHOULD remove the self handle from the Group - in the same signal.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="No_Answer" value="8"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because the requested contact did not respond.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called did not respond, or the - local user did not respond to an incoming call, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason No_Answer.</p> - - <tp:rationale> - Documenting existing practice. - </tp:rationale> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.NoAnswer</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Renamed" value="9"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because a contact's unique identifier changed. - There must be exactly one handle in the removed set and exactly - one handle in one of the added sets. The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref> - signal on the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref> - interface will have been emitted for the same handles, - shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Permission_Denied" value="10"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because there was no permission to contact the - requested handle.</p> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Separated" value="11"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If members are removed with this reason code, the change is - because the group has split into unconnected parts which can only - communicate within themselves (e.g. netsplits on IRC use this - reason code). - </p> - <p> - If members are added with this reason code, the change is because - unconnected parts of the group have rejoined. If this channel - carries messages (e.g. <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref> - channels) applications must - assume that the contacts being added are likely to have missed some - messages as a result of the separation, and that the contacts - in the group are likely to have missed some messages from the - contacts being added. - </p> - <p>Note that from the added contacts' perspective, they have been - in the group all along, and the contacts we indicate to be in - the group (including the local user) have just rejoined - the group with reason Separated. Application protocols in Tubes - should be prepared to cope with this situation. - </p> - - <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be - removed from channels with this reason.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="MembersChanged" tp:name-for-bindings="Members_Changed"> - <arg name="Message" type="s"> - <tp:docstring> - A string message from the server, or blank if not - </tp:docstring> - </arg> - <arg name="Added" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members added to the channel - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members removed from the channel - </tp:docstring> - </arg> - <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending local approval - </tp:docstring> - </arg> - <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending remote approval - </tp:docstring> - </arg> - <arg name="Actor" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact handle of the person who made the change, or 0 - if not known - </tp:docstring> - </arg> - <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason"> - <tp:docstring> - A reason for the change - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when contacts join any of the three lists (members, local - pending or remote pending) or when they leave any of the three lists. - There may also be a message from the server regarding this change, - which may be displayed to the user if desired.</p> - - <p>All channel-specific handles that are mentioned in this signal - MUST be represented in the value of the - <tp:member-ref>HandleOwners</tp:member-ref> property. - In practice, this will mean that - <tp:member-ref>HandleOwnersChanged</tp:member-ref> is - emitted <em>before</em> emitting a MembersChanged signal in which - channel-specific handles are added, but that it is emitted - <em>after</em> emitting a MembersChanged signal in which - channel-specific handles are removed.</p> - - <p>See <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - for an overview of how group state changes are used to indicate the - progress of a call.</p> - </tp:docstring> - </signal> - - <tp:mapping name="Handle_Identifier_Map"> - <tp:docstring> - A map from handles to the corresponding normalized string identifier. - </tp:docstring> - <tp:added version="0.17.17"/> - - <tp:member type="u" name="Handle" tp:type="Contact_Handle"> - <tp:docstring> - A nonzero handle - </tp:docstring> - </tp:member> - <tp:member type="s" name="Identifier"> - <tp:docstring> - The same string that would be returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> - for this handle. - </tp:docstring> - </tp:member> - </tp:mapping> - - <signal name="MembersChangedDetailed" - tp:name-for-bindings="Members_Changed_Detailed"> - <arg name="Added" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members added to the channel - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members removed from the channel - </tp:docstring> - </arg> - <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending local approval - </tp:docstring> - </arg> - <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending remote approval - </tp:docstring> - </arg> - <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Information about the change, which may include the following - well-known keys:</p> - - <dl> - <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt> - <dd>The contact handle of the person who made the change; 0 or - omitted if unknown or not applicable.</dd> - - <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt> - <dd>A reason for the change.</dd> - - <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt> - <dd> - <p>The string identifiers for handles mentioned in this signal, to - give clients the minimal information necessary to react to the - event without waiting for round-trips. Connection managers - SHOULD include the identifiers for members added to the group and - for the actor (if any); they MAY omit the identifiers for handles - which have been removed from the group.</p> - - <tp:rationale> - <p>On IRC, an event such as a netsplit could cause the vast - majority of a channel to leave. Given that clients should - already know the identifiers of a channel's members, including - potentially hundreds of strings in the netsplit signal is - unnecessary.</p> - </tp:rationale> - - <p>Clients MUST NOT assume that the presence or absence of a - handle in this mapping is meaningful. This mapping is merely - an optimization for round-trip reduction, and connection - managers MAY add additional handles, omit some handles, or - omit the mapping completely.</p> - </dd> - - <dt>message (s)</dt> - <dd>A string message from the server regarding the change</dd> - - <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt> - <dd>A (possibly implementation-specific) DBus error describing the - change, providing more specific information than the - <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This - MUST only be present if it is strictly more informative than - 'change-reason'; if present, 'change-reason' MUST be set to the - closest available reason. - - <tp:rationale> - A SIP connection manager might want to signal "402 Payment - required" as something more specific than Error or - Permission_Denied so that a SIP-aware UI could handle it - specially; including a namespaced error permits this to be done - without <tp:type>Channel_Group_Change_Reason</tp:type> being - extended to encompass every error any CM ever wants to report. - </tp:rationale> - </dd> - - <dt>debug-message (s)</dt> - <dd>Debugging information on the change. SHOULD NOT be shown to - users in normal circumstances.</dd> - </dl> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when contacts join any of the three lists (members, local - pending or remote pending) or when they leave any of the three - lists. This signal provides a superset of the information provided by - <tp:member-ref>MembersChanged</tp:member-ref>; - if the channel's <tp:member-ref>GroupFlags</tp:member-ref> - contains Members_Changed_Detailed, then clients may listen exclusively - to this signal in preference to that signal.</p> - - <p>All channel-specific handles that are mentioned in this signal - MUST be represented in the value of the - <tp:member-ref>HandleOwners</tp:member-ref> property. In practice, - this will mean that - <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted - <em>before</em> emitting a MembersChangedDetailed signal in which - channel-specific handles are added, but that it is emitted - <em>after</em> emitting a MembersChangedDetailed signal in which - channel-specific handles are removed.</p> - - <p>See <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - for an overview of how group state changes are used to indicate the - progress of a call.</p> - </tp:docstring> - <tp:added version="0.17.16"/> - </signal> - - <method name="RemoveMembers" tp:name-for-bindings="Remove_Members"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to remove from the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Requests the removal of contacts from a channel, reject their - request for channel membership on the pending local list, or - rescind their invitation on the pending remote list.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group, - it can be removed via this method, in order to leave the group - gracefully. This is the recommended way to leave a chatroom, close - or reject a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call, and so on.</p> - - <p>Accordingly, connection managers SHOULD support - doing this, regardless of the value of - <tp:member-ref>GroupFlags</tp:member-ref>. - If doing so fails with PermissionDenied, this is considered to a bug - in the connection manager, but clients MUST recover by falling back - to closing the channel with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - method.</p> - - <p>Removing any contact from the local pending list is always - allowed. Removing contacts other than the - <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members - is allowed if and only if Channel_Group_Flag_Can_Remove is in the - <tp:member-ref>GroupFlags</tp:member-ref>, - while removing contacts other than the - <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list - is allowed if and only if Channel_Group_Flag_Can_Rescind is in the - <tp:member-ref>GroupFlags</tp:member-ref>.</p> - - <p>A message may be provided along with the request, which will be - sent to the server if supported. See the - Channel_Group_Flag_Message_Remove, - Channel_Group_Flag_Message_Depart, - Channel_Group_Flag_Message_Reject and - Channel_Group_Flag_Message_Rescind - <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this - message should be provided.</p> - </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:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="RemoveMembersWithReason" - tp:name-for-bindings="Remove_Members_With_Reason"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to remove from the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <arg direction="in" name="Reason" type="u" - tp:type="Channel_Group_Change_Reason"> - <tp:docstring> - A reason for the change - </tp:docstring> - </arg> - <tp:docstring> - As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may - be provided where - appropriate. The reason code may be ignored if the underlying - protocol is unable to represent the given reason. - </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:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The provided reason code was invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for channels which have multiple members, and where the members - of the channel can change during its lifetime. Your presence in the channel - cannot be presumed by the channel's existence (for example, a channel you - may request membership of but your request may not be granted).</p> - - <p>This interface implements three lists: a list of current members - (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending - and remote pending members - (<tp:member-ref>LocalPendingMembers</tp:member-ref> and - <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively). - Contacts on the remote - pending list have been invited to the channel, but the remote user has not - accepted the invitation. Contacts on the local pending list have requested - membership of the channel, but the local user of the framework must accept - their request before they may join. A single contact should never appear on - more than one of the three lists. The lists are empty when the channel is - created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal - (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains - Members_Changed_Detailed, the - <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal) - should be emitted when information - is retrieved from the server, or changes occur.</p> - - <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or - <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates - that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from - the channel, and the channel subsequently emits <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>, - clients SHOULD consider the details given in the MembersChanged or - MembersChangedDetailed signal to be the reason why the channel closed.</p> - - <p>Addition of members to the channel may be requested by using - <tp:member-ref>AddMembers</tp:member-ref>. If - remote acknowledgement is required, use of the AddMembers method will cause - users to appear on the remote pending list. If no acknowledgement is - required, AddMembers will add contacts to the member list directly. If a - contact is awaiting authorisation on the local pending list, AddMembers - will grant their membership request.</p> - - <p>Removal of contacts from the channel may be requested by using - <tp:member-ref>RemoveMembers</tp:member-ref>. If a contact is awaiting - authorisation on the local pending - list, RemoveMembers will refuse their membership request. If a contact is - on the remote pending list but has not yet accepted the invitation, - RemoveMembers will rescind the request if possible.</p> - - <p>It should not be presumed that the requester of a channel implementing this - interface is immediately granted membership, or indeed that they are a - member at all, unless they appear in the list. They may, for instance, - be placed into the remote pending list until a connection has been - established or the request acknowledged remotely.</p> - - <p>If the local user joins a Group channel whose members or other state - cannot be discovered until the user joins (e.g. many chat room - implementations), the connection manager should ensure that the channel - is, as far as possible, in a consistent state before adding the local - contact to the members set; until this happens, the local contact should - be in the remote-pending set. For instance, if the connection manager - queries the server to find out the initial members list for the - channel, it should leave the local contact in the remote-pending set - until it has finished receiving the initial members list. - </p> - - <p>If the protocol provides no reliable way to tell whether the complete - initial members list has been received yet, the connection manager - should make a best-effort attempt to wait for the full list - (in the worst case, waiting for a suitable arbitrary timeout) - rather than requiring user interfaces to do so on its behalf.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |