diff options
Diffstat (limited to 'qt4/spec/Client_Handler.xml')
| -rw-r--r-- | qt4/spec/Client_Handler.xml | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/qt4/spec/Client_Handler.xml b/qt4/spec/Client_Handler.xml deleted file mode 100644 index 3a922e8cc..000000000 --- a/qt4/spec/Client_Handler.xml +++ /dev/null @@ -1,337 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Handler" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</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.Client.Handler"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Client"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Handlers are the user interface for a channel. They turn an abstract - Telepathy channel into something the user wants to see, like a text - message stream or an audio and/or video call.</p> - - <p>For its entire lifetime, each channel on a connection known to the - channel dispatcher is either being processed by the channel dispatcher, - or being handled by precisely one Handler.</p> - - <p>Because each channel is only handled by one Handler, handlers may - perform actions that only make sense to do once, such as acknowledging - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - messages, doing the actual streaming for <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - channels with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface, or transferring the file in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">FileTransfer</tp:dbus-ref> - channels.</p> - - <p>When a new incoming channel (one with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> - = FALSE) is offered to - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s - by the channel dispatcher, it also offers the Approvers a list of all - the running or activatable handlers whose - <tp:member-ref>HandlerChannelFilter</tp:member-ref> property - (possibly as cached in the .client file) indicates that they - are able to handle the channel. The Approvers can choose one of - those channel handlers to handle the channel.</p> - - <p>When a new outgoing channel (one with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> - = TRUE) appears, the channel dispatcher passes it to an appropriate - channel handler automatically. - </p> - - </tp:docstring> - - <property name="HandlerChannelFilter" - tp:name-for-bindings="Handler_Channel_Filter" - type="aa{sv}" access="read" tp:type="Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specification of the channels that this channel handler can - deal with. It will be offered to approvers as a potential - channel handler for bundles that contain only suitable channels, - or for suitable channels that must be handled separately.</p> - - <p>This property works in exactly the same way as the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> - property. In particular, it cannot change while the handler process - continues to own the corresponding Client bus name.</p> - - <p>In the .client file, it is represented in the - same way as ObserverChannelFilter, but the group has the same - name as this interface and the keys start with - HandlerChannelFilter instead of ObserverChannelFilter.</p> - </tp:docstring> - </property> - - <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, channels destined for this handler are automatically - handled, without invoking approvers.</p> - - <tp:rationale> - <p>The intended usage is to allow a client handling one channel to - pick up closely related channels. Suppose a client capable of - handling both Text and StreamedMedia, - <code>org.freedesktop.Telepathy.Client.Empathy</code>, is - handling a StreamedMedia channel. That client can take a second - well-known bus name, say - <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>, - and configure an object at - <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code> - with BypassApproval = TRUE, - whose <tp:member-ref>HandlerChannelFilter</tp:member-ref> - matches closely related Text channels by their Bundle property.</p> - </tp:rationale> - - <p>For service-activatable handlers, this property should be specified - in the handler's <tt>.client</tt> file as follows:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Handler] -BypassApproval=true -</pre> - </tp:docstring> - </property> - - <tp:simple-type name="Handler_Capability_Token" type="s" - array-name="Handler_Capability_Token_List"> - <tp:docstring> - A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character - and an identifier for a capability defined by that interface. The - capability identifier SHOULD be in lower case. If an interface - references an external specification which is case-insensitive (such - as MIME), then names from that specification MUST be normalized to - lower-case before providing them to this Telepathy API, so that - implementations can safely rely on simple byte-by-byte comparison. - - <tp:rationale> - These aren't D-Bus core Properties, and we want them to look visibly - different. - </tp:rationale> - - <p>So far, all client capabilities are defined by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface.</p> - </tp:docstring> - </tp:simple-type> - - <property name="Capabilities" tp:name-for-bindings="Capabilities" - type="as" tp:type="Handler_Capability_Token[]" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The set of additional capabilities supported by this handler. - This describes things like support for streamed media codecs and - NAT traversal mechanisms: see the Contact Capabilities - interface for more details.</p> - - <p>For handlers that have a <code>.client</code> file, the - channel dispatcher may discover this property from the - <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code> - group; for each capability, that group contains a key - whose name is the capability, with value <code>true</code>. - Keys with other values SHOULD NOT appear in this group.</p> - - <p>For instance, the <code>.client</code> file for a streamed media - handler that supports ICE-UDP NAT traversal, Speex audio, - and Theora and H264 video might contain this group:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Handler.Capabilities] -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true -</pre> - - <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref> - property, this property cannot change while the Handler owns its - Client bus name. However, the <code>.client</code> file, if any, - can change (due to upgrades or installation of pluggable codecs), - and the capabilities really supported by the handler might not - exactly match what is cached in the <code>.client</code> file.</p> - - <tp:rationale> - <p>The client file is installed statically and is intended to list - codecs etc. that the handler guarantees it can support (e.g. by - having a hard dependency on them), whereas the running handler - process might be able to find additional codecs.</p> - </tp:rationale> - </tp:docstring> - </property> - - <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when this client should handle these - channels, or when this client should present channels that it is already - handling to the user (e.g. bring them into the foreground).</p> - - <tp:rationale> - <p>Clients are expected to know what channels they're already handling, - and which channel object path corresponds to which window or tab. - This can easily be done using a hash table keyed by channels' object - paths.</p> - </tp:rationale> - - <p>This method can raise any D-Bus error. If it does, the - handler is assumed to have failed or crashed, and the channel - dispatcher MUST recover in an implementation-specific way; it MAY - attempt to dispatch the channels to another handler, or close the - channels.</p> - - <p>If closing the channels, it is RECOMMENDED that the channel - dispatcher attempts to close the channels using - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, - but resorts to calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> - (if available) or ignoring the channel (if not) if the same handler - repeatedly fails to handle channels.</p> - - <p>After HandleChannels returns successfully, the client process is - considered to be responsible for the channel until it its unique - name disappears from the bus.</p> - - <tp:rationale> - <p>If a process has multiple Client bus names - some temporary and - some long-lived - and drops one of the temporary bus names in order - to reduce the set of channels that it will handle, any channels - that it is already handling should remain unaffected.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o" direction="in"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - with which the channels are associated. The - well-known bus name to use is that of the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Connection" type="o" direction="in"> - <tp:docstring> - The Connection with which the channels are associated. The - well-known bus name to use can be derived from this object - path by removing the leading '/' and replacing all subsequent - '/' by '.'. - </tp:docstring> - </arg> - - <arg name="Channels" type="a(oa{sv})" direction="in" - tp:type="Channel_Details[]"> - <tp:docstring> - The channels and their immutable properties. Their well-known - bus name is the same as that of the Connection. - </tp:docstring> - </arg> - - <arg name="Requests_Satisfied" type="ao" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The requests satisfied by these channels.</p> - - <tp:rationale> - <p>If the handler implements Requests, this tells it - that these channels match previous <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> - calls that it may have received.</p> - - <p>There can be more than one, if they were EnsureChannel - requests.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="User_Action_Time" type="t" direction="in"> - <tp:docstring> - The time at which user action occurred, or 0 if this channel - is to be handled for some reason not involving user action. - Handlers SHOULD use this for focus-stealing prevention, - if applicable. - This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> - but is unsigned for historical reasons. - </tp:docstring> - </arg> - - <arg name="Handler_Info" type="a{sv}" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. Currently defined - keys are:</p> - - <dl> - <dt><code>request-properties</code> - a{oa{sv}}</dt> - <dd>A map from <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - paths listed in <var>Requests_Satisfied</var> to - <tp:type>Qualified_Property_Value_Map</tp:type>s containing - namespaced immutable properties of each request.</dd> - </dl> - - <p>When more keys are defined for this dictionary, all will be - optional; handlers MAY safely ignore any entry in this - dictionary.</p> - </tp:docstring> - </arg> - - <!-- FIXME: invent a way to say "any error is possible" in spec markup --> - </method> - - <property name="HandledChannels" tp:name-for-bindings="Handled_Channels" - type="ao" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the channels that this process is currently handling.</p> - - <p>There is no change notification.</p> - - <tp:rationale> - <p>This property exists for state recovery - it makes it possible - for channel handling to survive a ChannelDispatcher crash.</p> - - <p>If the channel dispatcher is automatically replaced, the - replacement can discover all Handlers by looking for the Client - well-known bus names, and discover which channels they are - currently handling. Once this has been done, all unhandled - channels can be re-dispatched, and the only issue visible to - the user is that unhandled channels that they have already - approved might be sent back to Approvers.</p> - </tp:rationale> - - <p>The value of this property SHOULD be the same for all Client - instances that share a unique bus name, and SHOULD include all - channels that are being handled, even if they were conceptually - handled by a different Client instance.</p> - - <tp:rationale> - <p>Otherwise, when a process released a temporary Client name, - channels that it handled because of that Client name would no - longer be state-recoverable.</p> - </tp:rationale> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |