diff options
Diffstat (limited to 'spec/Connection_Interface_Capabilities.xml')
| -rw-r--r-- | spec/Connection_Interface_Capabilities.xml | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml new file mode 100644 index 000000000..1385d1ce9 --- /dev/null +++ b/spec/Connection_Interface_Capabilities.xml @@ -0,0 +1,162 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 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 +Library 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <method name="AdvertiseCapabilities"> + <arg direction="in" name="add" type="a(su)"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>a string channel type</li> + <li>a bitwise OR of type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <arg direction="in" name="remove" type="as"> + <tp:docstring> + An array of D-Bus interface names of channel types to remove + </tp:docstring> + </arg> + <arg direction="out" type="a(su)"> + <tp:docstring> + An array of structures describing the current capabilities containing: + <ul> + <li>a string channel type</li> + <li>a bitwise OR of type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used by user interfaces to indicate which channel types they are able + to handle on this connection. Because these may be provided by + different client processes, this method accepts channel types to add + and remove from the set already advertised on this connection. The type + of advertised capabilities (create versus invite) is protocol-dependent + and hence cannot be set by the this method. In the case of a client + adding an already advertised channel type but with new channel type + specific flags, the connection manager should simply add the new flags + to the set of advertised capabilities.</p> + + <p>Upon a successful invocation of this method, the CapabilitiesChanged + signal will be emitted for the user's own handle (as returned by + GetSelfHandle) the by the connection manager to indicate the changes + that have been made. This signal should also be monitored to ensure + that the set is kept accurate - for example, a client may remove + capabilities or type specific capability flags when it exits + which are still provided by another client.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + <signal name="CapabilitiesChanged"> + <arg name="caps" type="a(usuuuu)"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>an integer handle representing the contact</li> + <li>a string channel type</li> + <li>a bitwise OR of the contact's old generic capability flags</li> + <li>a bitwise OR of the contact's new generic capability flags</li> + <li>a bitwise OR of the contact's old type specific capability flags</li> + <li>a bitwise OR of the contact's new type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Announce that there has been a change of capabilities on the + given handle, or on the connection itself if the handle is zero. + </tp:docstring> + </signal> + <method name="GetCapabilities"> + <arg direction="in" name="handles" type="au"> + <tp:docstring> + An array of contact handles for this connection, or zero to query capabilities available on the connection itself + </tp:docstring> + </arg> + <arg direction="out" type="a(usuu)"> + <tp:docstring> + An array of structures containing: + <ul> + <li>an integer handle representing the contact</li> + <li>a string channel type</li> + <li>a bitwise OR of generic capability flags for the type</li> + <li>a bitwise OR of type specific capability flags for the type</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of capabilities for the given contact handles, or + the connection itself (where handle is zero). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The handle does not represent a contact + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections where it is possible to know what channel + types may be requested before the request is made to the connection object. + Each capability represents a commitment by the connection manager that it + will ordinarily be able to create a channel when given a request with the + given type and handle.</p> + + <p>Capabilities can pertain to a certain contact handle, representing + activities such as having a text chat or a voice call with the user, or can + be on the connection itself (where the handle will be zero), where they + represent the ability to create channels for chat rooms or activities such + as searching and room listing. The activities are represented by the D-Bus + interface name of the channel type for that activity.</p> + + <p>The generic capability flags are defined by ConnectionCapabilityFlag.</p> + + <p>In addition, channel types may have type specific capability flags of their + own, which are described in the documentation for each channel type.</p> + + <p>This interface also provides for user interfaces notifying the connection + manager of what capabilities to advertise for the user. This is done by + using the AdvertiseCapabilities method, and deals with the interface names + of channel types and the type specific flags pertaining to them which are + implemented by available client processes.</p> + </tp:docstring> + </interface> + <tp:flags name="Connection_Capability_Flags" value-prefix="Connection_Capability_Flag" type="u"> + <tp:flag suffix="Create" value="1"> + <tp:docstring> + The given channel type and handle can be given to RequestChannel to + create a new channel of this type. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Invite" value="2"> + <tp:docstring> + The given contact can be invited to an existing channel of this type. + </tp:docstring> + </tp:flag> + </tp:flags> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |