diff options
Diffstat (limited to 'qt4/spec')
44 files changed, 2303 insertions, 937 deletions
diff --git a/qt4/spec/Account.xml b/qt4/spec/Account.xml index 991dcbda0..b6a2670c4 100644 --- a/qt4/spec/Account.xml +++ b/qt4/spec/Account.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Account" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <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 @@ -427,7 +427,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The actual presence. If the connection is not online, this should be (Connection_Presence_Type_Offline, "", ""). If the connection is online but does not support the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> interface, this should be (Connection_Presence_Type_Unset, "", ""). The account manager is expected to set this by observing signals from the Connection. @@ -494,6 +494,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="HasBeenOnline" tp:name-for-bindings="Has_Been_Online" + type="b" access="read"> + <tp:docstring> + If true, this account has successfully been put online at some point + in the past. + + <tp:rationale> + UIs could apply a policy that the 'account' parameter can only be + edited in accounts that have never been online, or that + ConnectAutomatically cannot be set on such accounts. The account + manager should not enforce such policies, but it can expose enough + information to UIs that the UI can decide what to do. + </tp:rationale> + </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Account_Manager.xml b/qt4/spec/Account_Manager.xml index 98fe00d9c..6fb9b088c 100644 --- a/qt4/spec/Account_Manager.xml +++ b/qt4/spec/Account_Manager.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Account_Manager" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright> + <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 diff --git a/qt4/spec/Channel.xml b/qt4/spec/Channel.xml index 7b4a7ad8a..2937680bb 100644 --- a/qt4/spec/Channel.xml +++ b/qt4/spec/Channel.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel" 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: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 diff --git a/qt4/spec/Channel_Dispatch_Operation.xml b/qt4/spec/Channel_Dispatch_Operation.xml index 7f61f6f35..a44712c7a 100644 --- a/qt4/spec/Channel_Dispatch_Operation.xml +++ b/qt4/spec/Channel_Dispatch_Operation.xml @@ -21,14 +21,14 @@ MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation" + tp:causes-havoc="not yet final"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel dispatch operation is an object in the ChannelDispatcher - representing a bundle of unrequested channels being announced to + representing a batch of unrequested channels being announced to client - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref> processes.</p> <p>These objects can result from new incoming channels or channels @@ -52,9 +52,9 @@ <p>First, the channel dispatcher SHOULD construct a list of all the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>s + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s that could handle all the channels (based on their <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> property), ordered by priority in some implementation-dependent way. If there are handlers which could handle all the channels, one channel dispatch operation @@ -62,15 +62,34 @@ dispatch operation SHOULD be created for each channel, each with a list of channel handlers that could handle that channel.</p> + <p>If no handler at all can handle a channel, the channel dispatcher + SHOULD terminate that channel instead of creating a channel dispatcher + for it. It is RECOMMENDED that the channel dispatcher closes + the channels using <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + if supported, or <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + otherwise. As a special case, the channel dispatcher SHOULD NOT close + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref> + channels, and if Close fails, the channel dispatcher SHOULD ignore + that channel.</p> + + <tp:rationale> + <p>ContactList channels are strange. We hope to replace them with + something better, such as an interface on the Connection, in a + future version of this specification.</p> + </tp:rationale> + <p>When listing channel handlers, priority SHOULD be given to channel handlers that are already handling channels from the same bundle.</p> <p>If a handler with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">BypassApproval</tp:dbus-ref> - <code>= True</code> could handle the channels in the dispatch + namespace="org.freedesktop.Telepathy.Client.Handler">BypassApproval</tp:dbus-ref> + <code>= True</code> could handle all of the channels in the dispatch operation, then the channel dispatcher SHOULD call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> on that handler, and (assuming the call succeeds) emit <tp:member-ref>Finished</tp:member-ref> and stop processing those channels without involving any approvers.</p> @@ -92,7 +111,7 @@ approver to claim the channels or request that they are handled. See <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> for more details on this.</p> <p>Finally, if the approver requested it, the channel dispatcher SHOULD @@ -142,11 +161,29 @@ </property> <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> - <tp:docstring> - A channel has closed before it could be claimed or handled. If this - is emitted for the last remaining channel in a channel dispatch - operation, it MUST immediately be followed by - <tp:member-ref>Finished</tp:member-ref>. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel has closed before it could be claimed or handled. If + this is emitted for the last remaining channel in a channel + dispatch operation, it MUST immediately be followed by + <tp:member-ref>Finished</tp:member-ref>.</p> + + <p>This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> + method.</p> + + <tp:rationale> + <p>This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to ChannelLost and + <tp:member-ref>Finished</tp:member-ref>, + then download <tp:member-ref>Channels</tp:member-ref> (and + on error, perhaps assume that the operation has already + Finished).</p> + </tp:rationale> </tp:docstring> <arg name="Channel" type="o"> @@ -161,20 +198,9 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of a D-Bus error indicating why the channel closed. If no better reason can be found, - <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY + <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY be used as a fallback; this means that this error SHOULD NOT be given any more specific meaning.</p> - - <p>FIXME: or should we invent a new OtherError for that purpose?</p> - - <p>FIXME: we need to specify errors for these situations:</p> - - <ul> - <li>kicked from a chatroom</li> - <li>outgoing call rejected</li> - <li>outgoing call timed out</li> - <li>incoming call terminated</li> - </ul> </tp:docstring> </arg> @@ -188,13 +214,22 @@ <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" type="as" access="read" tp:type="DBus_Well_Known_Name[]"> <tp:docstring> - The well known bus names (starting with - <code>org.freedesktop.Telepathy.Client.</code>) of the possible - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s - for these channels. The channel dispatcher MUST place the most - preferred handlers first, according to some reasonable heuristic. - As a result, approvers SHOULD use the first handler by default. + <p>The well known bus names (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the possible + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s + for these channels. The channel dispatcher MUST place the most + preferred handlers first, according to some reasonable heuristic. + As a result, approvers SHOULD use the first handler by default.</p> + + <p>The heuristic used to prioritize handlers SHOULD give a higher + priority to handlers that are already running.</p> + + <tp:rationale> + <p>If, for instance, Empathy and Kopete have similar functionality, + and Empathy is running, we should prefer to send channels to it + rather than launching Kopete via service activation.</p> + </tp:rationale> </tp:docstring> </property> @@ -222,7 +257,7 @@ <p>(FIXME: list some possible errors)</p> <p>If the channel handler raises an error from <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>, + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>, this method MAY respond by raising that same error, even if it is not specifically documented here.</p> @@ -232,15 +267,16 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The well-known bus name (starting with <code>org.freedesktop.Telepathy.Client.</code>) of the channel - handler that should handle the channel.</p> + handler that should handle the channel, or the empty string + if the client has no preferred channel handler.</p> </tp:docstring> </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The selected handler is not a syntactically correct - <tp:type>DBus_Bus_Name</tp:type> or does not start with + The selected handler is non-empty, but is not a syntactically + correct <tp:type>DBus_Bus_Name</tp:type> or does not start with "<code>org.freedesktop.Telepathy.Client.</code>". </tp:docstring> </tp:error> @@ -278,13 +314,15 @@ <p>Called by an approver to claim channels for handling internally. If this method is called successfully, the process calling this method becomes the handler for the channel, but - <em>does not</em> have the HandleChannels method called on it.</p> - <!-- FIXME: tp:dbus-ref --> + <em>does not</em> have the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + method called on it.</p> <p>Clients that call Claim on channels but do not immediately close them SHOULD implement the Handler interface and its - CurrentlyHandledChannels property.</p> - <!-- FIXME: tp:dbus-ref --> + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandledChannels</tp:dbus-ref> + property.</p> <p>Approvers wishing to reject channels MUST call this method to claim ownership of them, and MUST NOT call @@ -297,7 +335,14 @@ For instance, for Text channels it is necessary to acknowledge any messages that have already been displayed to the user first - ideally, the approver would display and then - acknowledge the messages.</p> + acknowledge the messages - or to call <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + if the destructive behaviour of that method is desired.</p> + + <p>Similarly, an Approver for StreamedMedia channels can close the + channel with a reason (e.g. "busy") if desired. The channel + dispatcher, which is designed to have no specific knowledge + of particular channel types, can't do that.</p> </tp:rationale> <p>If successful, this method will cause the ChannelDispatchOperation @@ -331,6 +376,11 @@ operation is no longer present and further methods must not be called on it.</p> + <p>Approvers that have a user interface SHOULD stop notifying the user + about the channels in response to this signal; they MAY assume that + on errors, they would have received + <tp:member-ref>ChannelLost</tp:member-ref> first.</p> + <p>Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths in a way that avoids immediate re-use.</p> @@ -341,6 +391,24 @@ <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation instead of the one they intended to handle.</p> </tp:rationale> + + <p>This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> + method.</p> + + <tp:rationale> + <p>This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to + <tp:member-ref>ChannelLost</tp:member-ref> and + Finished, then download <tp:member-ref>Channels</tp:member-ref> + (and on error, perhaps assume that the operation has already + Finished).</p> + </tp:rationale> </tp:docstring> </signal> diff --git a/qt4/spec/Channel_Dispatcher.xml b/qt4/spec/Channel_Dispatcher.xml index c77873db9..8680f6d08 100644 --- a/qt4/spec/Channel_Dispatcher.xml +++ b/qt4/spec/Channel_Dispatcher.xml @@ -2,8 +2,8 @@ <node name="/Channel_Dispatcher" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <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 @@ -21,8 +21,8 @@ USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.ChannelDispatcher" + tp:causes-havoc="not yet final"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The channel dispatcher is responsible for responding to new @@ -67,12 +67,14 @@ specification:</p> <dl> - <dt>Observer</dt> + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt> <dd><p>Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.</p></dd> - <dt>Approver</dt> + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>p <dd> <p>Approvers notify the user that new channels have been created, and also select which channel handler will be used for the channel, @@ -80,7 +82,8 @@ channel handler.</p> </dd> - <dt>Handler</dt> + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt> <dd> <p>Each new channel or set of channels is passed to exactly one handler as its final destination. A typical channel handler is a @@ -99,7 +102,7 @@ <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to create a channel. This initially just creates a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure.</p> @@ -119,10 +122,10 @@ <p>If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Proceed</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Failed</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.</p> <tp:rationale> @@ -166,10 +169,10 @@ <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> property will be set to this value, and it will eventually be passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</p> + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p> </tp:docstring> </arg> @@ -193,14 +196,15 @@ <p>This is partly so the channel dispatcher can call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.</p> </tp:rationale> - <p>If this is a well-known bus name, the channel dispatcher SHOULD + <p>If this is a well-known bus name and the handler has the + Requests interface, the channel dispatcher SHOULD call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> on that Handler after this method has returned.</p> <tp:rationale> @@ -208,13 +212,18 @@ itself as the preferred handler to associate the call to AddRequest with that call.</p> </tp:rationale> + + <p>This is copied to the ChannelRequest that is returned, + as the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref> + property.</p> </tp:docstring> </arg> <arg direction="out" name="Request" type="o"> <tp:docstring> A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object. </tp:docstring> </arg> @@ -236,22 +245,22 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure.</p> <p>If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Proceed</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Failed</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.</p> <tp:rationale> <p>The rationale is as for <tp:dbus-ref - namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>CreateChannel</tp:dbus-ref>.</p> + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p> </tp:rationale> </tp:docstring> @@ -284,12 +293,10 @@ tp:type="Unix_Timestamp64"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel - request is for some reason not involving user action. - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> - property will be set to this value, and it will eventually be - passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</p> + request is for some reason not involving user action.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p> </tp:docstring> </arg> @@ -300,30 +307,10 @@ <code>org.freedesktop.Telepathy.Client.</code>) of the preferred handler for this channel, or an empty string to indicate that any handler would be - acceptable.</p> - - <tp:rationale> - <p>This must be the well-known bus name, not the unique name, - to ensure that all handlers do indeed have the Client API, - and the Client object on the handler can be located easily.</p> - - <p>This is partly so the channel dispatcher can call - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> - on it, and partly so the channel dispatcher - can recover state if it crashes and is restarted.</p> - </tp:rationale> - - <p>If this is a well-known bus name, the channel dispatcher SHOULD - call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref> - on that Handler after this method has returned.</p> - - <tp:rationale> - <p>This ordering allows a Handler which calls EnsureChannel with - itself as the preferred handler to associate the call to - AddRequest with that call.</p> - </tp:rationale> + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + <tp:member-ref>CreateChannel</tp:member-ref>, except as noted + here.</p> <p>If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as @@ -340,11 +327,11 @@ <tp:rationale> <p>An address book application, for example, might call <tp:dbus-ref - namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref> + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> to ensure that a text channel with a particular contact is displayed to the user; it does not care whether a new channel was made. An IM client might call <tp:dbus-ref - namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref> + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> in response to the user double-clicking an entry in the contact list, with itself as the <code>Preferred_Handler</code>; if the user already has a conversation with that contact in another @@ -360,7 +347,7 @@ <arg direction="out" name="Request" type="o"> <tp:docstring> A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object. </tp:docstring> </arg> diff --git a/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml b/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml index b59ef72a3..e3270ce87 100644 --- a/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml +++ b/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -21,10 +21,10 @@ USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList" + tp:causes-havoc="not yet final"> - <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface allows users of the ChannelDispatcher to enumerate @@ -71,11 +71,10 @@ <p>Each dictionary MUST contain at least the following keys:</p> <ul> - <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Interfaces</tp:dbus-ref></li> - <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Connection</tp:dbus-ref></li> - <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Account</tp:dbus-ref></li> - <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Channels</tp:dbus-ref></li> - <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.PossibleHandlers</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Connection</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Account</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers</tp:dbus-ref></li> </ul> </tp:docstring> </tp:member> @@ -119,7 +118,7 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Emitted when a dispatch operation finishes (i.e. exactly once per emission of <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT.Finished</tp:dbus-ref>). + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>). <tp:rationale> Strictly speaking this is redundant with diff --git a/qt4/spec/Channel_Future.xml b/qt4/spec/Channel_Future.xml index 823d8a0da..5bbca17b1 100644 --- a/qt4/spec/Channel_Future.xml +++ b/qt4/spec/Channel_Future.xml @@ -50,7 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ pseudo-interface)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle.DRAFT</tp:dbus-ref> to which this channel belongs.</p> <p>A channel's Bundle property can never change.</p> diff --git a/qt4/spec/Channel_Handler.xml b/qt4/spec/Channel_Handler.xml index 3a8f6b146..edf975e4d 100644 --- a/qt4/spec/Channel_Handler.xml +++ b/qt4/spec/Channel_Handler.xml @@ -17,16 +17,15 @@ 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.ChannelHandler"> + <tp:deprecated version="0.17.23"> + Clients should implement <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref> + instead. + </tp:deprecated> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface exported by client applications which are able to - handle incoming channels. This - interface is intended to be deprecated in favour of - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Client.Handler.DRAFT</tp:dbus-ref> - when that interface comes out of DRAFT; client authors should consider - implementing that interface instead. - </p> + <p>An interface exported by Mission Control 4 client applications which + are able to handle incoming channels.</p> </tp:docstring> <tp:added version="0.17.0"/> diff --git a/qt4/spec/Channel_Interface_Call_State.xml b/qt4/spec/Channel_Interface_Call_State.xml index 0df6e3472..eec6a4b34 100644 --- a/qt4/spec/Channel_Interface_Call_State.xml +++ b/qt4/spec/Channel_Interface_Call_State.xml @@ -20,12 +20,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Interface.CallState"> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - <tp:docstring> - An interface for streamed media channels that can indicate call - progress or call states. The presence of this interface is no guarantee - that call states will actually be signalled (for instance, SIP - implementations are not guaranteed to generate status 180 Ringing, - so a call can be accepted without the Ringing flag ever having been set). + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for streamed media channels that can indicate call + progress or call states. The presence of this interface is no guarantee + that call states will actually be signalled (for instance, SIP + implementations are not guaranteed to generate status 180 Ringing, so a + call can be accepted without the Ringing flag ever having been set).</p> + + <p>To notify the other participant in the call that they are on hold, + see <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Hold</tp:dbus-ref>.</p> </tp:docstring> <tp:added version="0.17.2"/> diff --git a/qt4/spec/Channel_Interface_Group.xml b/qt4/spec/Channel_Interface_Group.xml index 490258fcc..a3319bf3f 100644 --- a/qt4/spec/Channel_Interface_Group.xml +++ b/qt4/spec/Channel_Interface_Group.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <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 @@ -76,6 +76,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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"/> @@ -241,6 +242,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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" @@ -567,8 +581,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:enum name="Channel_Group_Change_Reason" type="u"> <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - No reason was provided for this change. + <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"> @@ -950,16 +978,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A string message, which can be blank if desired </tp:docstring> </arg> - <tp:docstring> - 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. 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_REJECT and - CHANNEL_GROUP_FLAG_MESSAGE_RESCIND - <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this - message should be provided. + <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"/> diff --git a/qt4/spec/Channel_Interface_Hold.xml b/qt4/spec/Channel_Interface_Hold.xml index 835aff926..1e3a832d9 100644 --- a/qt4/spec/Channel_Interface_Hold.xml +++ b/qt4/spec/Channel_Interface_Hold.xml @@ -26,7 +26,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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.</p> + 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 diff --git a/qt4/spec/Channel_Interface_Media_Signalling.xml b/qt4/spec/Channel_Interface_Media_Signalling.xml index 82493316f..5c2931646 100644 --- a/qt4/spec/Channel_Interface_Media_Signalling.xml +++ b/qt4/spec/Channel_Interface_Media_Signalling.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Media_Signalling" 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: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 @@ -103,37 +103,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ within. </tp:docstring> </signal> - <tp:property name="nat-traversal" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A string indicating the NAT traversal techniques employed by the - streams within this channel. Can be protocol-specific values, but the - following values should be used if appropriate:</p> - - <dl> - <dt>none</dt> - <dd>No attempt should be made at NAT traversal.</dd> - <dt>stun</dt> - <dd>If appropriate, a STUN request should be made to the given server - to open a UDP port mapping and determine the external IP.</dd> - - <dt>gtalk-p2p</dt> - <dd>Google Talk peer-to-peer connectivity establishment should be used, - as implemented in libjingle 0.3.</dd> - </dl> + <tp:property name="nat-traversal" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + A string indicating the NAT traversal techniques employed by the + streams within this channel if they do not have a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property. The possible values are the same as for the NATTraversal + property on the streams. </tp:docstring> </tp:property> + <tp:property name="stun-server" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> <tp:docstring> - The IP address or hostname of the STUN server to use for NAT traversal. + The IP address or hostname of the STUN server to use for NAT traversal + if the individual streams do not specify one. </tp:docstring> </tp:property> + <tp:property name="stun-port" type="q"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> <tp:docstring> The UDP port number to use on the provided STUN server. </tp:docstring> </tp:property> + <tp:property name="gtalk-p2p-relay-token" type="s"> + <tp:deprecated version="0.17.22">XMPP connection managers + supporting the Google Talk relay server SHOULD make the necessary + HTTP requests to find a username and password, and use those + to populate the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref> + property on the Media.StreamHandler.</tp:deprecated> <tp:docstring> The authentication token for use with the Google Talk peer-to-peer relay server. diff --git a/qt4/spec/Channel_Interface_Media_Signalling_Future.xml b/qt4/spec/Channel_Interface_Media_Signalling_Future.xml index e1d2d25fb..bbb8b87b2 100644 --- a/qt4/spec/Channel_Interface_Media_Signalling_Future.xml +++ b/qt4/spec/Channel_Interface_Media_Signalling_Future.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Media_Signalling_Future" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 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 @@ -22,7 +22,7 @@ <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.MediaSignalling"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface contains functionality which we intend to incorporate @@ -67,15 +67,37 @@ properties list of the channel class that advertises a contact's ability to receive streamed media calls.</p> - <p>Clients that are able to receive calls with particular NAT - traversal mechanisms MAY include the following filters if - calling <tp:dbus-ref + <p>Clients SHOULD NOT pass ICETransportAvailable and similar + properties to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref> + or similar functions. If they do, the connection manager MUST + accept and ignore any such property that is in the allowed properties + list.</p> + + <tp:rationale> + <p>There is currently no way for clients to influence the choice + of transport: in general, a client making a call can't know the + capabilities of the streaming implementation, or even which + streaming implementation will be used (channels will often be + requested by an address book or similar application that will not + handle the channel itself).</p> + + <p>If a mechanism for transport negotiation is added, it should be + something that happens after the request, but before calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Media.SessionHandler.Ready</tp:dbus-ref>, + so that it is the streaming implementation that chooses the + transport, rather than the requesting client.</p> + </tp:rationale> + + <p>Clients that are able to receive calls with particular transports + MUST include the following filters if calling <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> (clients of a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> SHOULD instead arrange for the ChannelDispatcher to do this, by including the filters in their <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> properties):</p> <ul> @@ -87,71 +109,13 @@ </ul> <p>Connection managers MAY use this information to adjust the - transports for which they advertise support to other contacts. - If a client has indicated support for any particular transports, - the connection manager SHOULD advertise support for - each transport that is supported by any client, and also - supported by the CM itself.</p> + transports for which they advertise support to other contacts.</p> <tp:rationale> - <p>This minimizes the possibility that a call will be started that - cannot in fact succeed, because the intersection of the contacts' - available transports is empty.</p> + <p>In particular, in XMPP, the connection manager will not be + callable unless a client has told it to advertise support for + at least one transport.</p> </tp:rationale> - - <p>If no client has mentioned any of the transports known to the - connection manager in a call to SetSelfCapabilities, the connection - manager SHOULD advertise support for every transport that it can - signal.</p> - - <tp:rationale> - <p>This simplifies implementation on integrated platforms like Maemo, - where it can be assumed that client libraries will support all the - "standard" transports known to any connection manager, and - lowers the "barrier to entry" for new Telepathy clients.</p> - </tp:rationale> - - <p>Clients making outgoing calls for which the same client that made - the request will handle the streaming MAY indicate their ability or - inability to handle particular transports by including - <code>ICETransportAvailable = true</code>, - <code>RawUDPTransportAvailable = false</code>, etc. - in the request properties parameter of their call to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref> - or similar functions. When they do so, the connection manager - SHOULD attempt to use a transport that the client has indicated - it is able to handle; if this is not possible, the connection - manager SHOULD raise an error instead of creating a channel.</p> - - <tp:rationale> - <p>This enables such clients to restrict the CM to the subset of - transports supported by that particular client.</p> - </tp:rationale> - - <p>Clients making outgoing calls for which they will not themselves - handle the streaming (e.g. an address book starting a call which - will be streamed by a separate call UI) SHOULD NOT include those - properties in the request.</p> - - <tp:rationale> - <p>In general, such a client can't know the capabilities of the - streaming implementation, or even which streaming implementation - will be used.</p> - </tp:rationale> - - <p>In the absence of any indication of supported transports from the - client, the connection manager SHOULD assume that the transports - indicated by calling SetSelfCapabilities are available. If - no transports were indicated as supported by calling - SetSelfCapabilities either, it SHOULD assume that any transport - that it can signal will be acceptable.</p> - - <p>If this property, or any of the similar transport availability - properties, is passed to EnsureChannel (as opposed to CreateChannel), - the connection manager SHOULD ignore these properties when checking - whether it can return an existing channel as suitable; these - properties only become significant when the connection manager has - decided to create a new channel.</p> </tp:docstring> </property> @@ -165,8 +129,8 @@ </tp:docstring> </property> - <property name="GoogleP2PTransportAvailable" - tp:name-for-bindings="Google_P2P_Transport_Available" + <property name="GTalkP2PTransportAvailable" + tp:name-for-bindings="GTalk_P2P_Transport_Available" type="b" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, @@ -176,12 +140,23 @@ </tp:docstring> </property> - <property name="MSNTransportAvailable" - tp:name-for-bindings="MSN_Transport_Available" + <property name="WLM85TransportAvailable" + tp:name-for-bindings="WLM_8_5_Transport_Available" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, + but for the transport implemented by Windows Live Messenger 8.5 or + later (which resembles ICE draft 6).</p> + </tp:docstring> + </property> + + <property name="WLM2009TransportAvailable" + tp:name-for-bindings="WLM_2009_Transport_Available" type="b" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, - but for the variant of ICE used by MSN.</p> + but for the transport implemented by Windows Live Messenger 2009 + or later (which resembles ICE draft 19).</p> </tp:docstring> </property> diff --git a/qt4/spec/Channel_Interface_Messages.xml b/qt4/spec/Channel_Interface_Messages.xml index 8cdee3c87..c668067d7 100644 --- a/qt4/spec/Channel_Interface_Messages.xml +++ b/qt4/spec/Channel_Interface_Messages.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Messages" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright> + <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 @@ -706,7 +706,8 @@ USA.</p> </tp:member> </tp:mapping> - <tp:simple-type type="u" name="Message_Part_Index"> + <tp:simple-type type="u" name="Message_Part_Index" + array-name="Message_Part_Index_List"> <tp:added version="0.17.17"/> <tp:docstring> The index of a message part within a message. diff --git a/qt4/spec/Channel_Interface_Password.xml b/qt4/spec/Channel_Interface_Password.xml index 720849a86..76720a69c 100644 --- a/qt4/spec/Channel_Interface_Password.xml +++ b/qt4/spec/Channel_Interface_Password.xml @@ -1,9 +1,9 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> -Copyright (C) 2005, 2006 Collabora Limited -Copyright (C) 2005, 2006 Nokia Corporation -Copyright (C) 2006 INdT +Copyright © 2005-2009 Collabora Limited +Copyright © 2005-2009 Nokia Corporation +Copyright © 2006 INdT </tp:copyright> <tp:license> This library is free software; you can redistribute it and/or diff --git a/qt4/spec/Channel_Interface_Tube.xml b/qt4/spec/Channel_Interface_Tube.xml index b2d0f3181..5d1eda712 100644 --- a/qt4/spec/Channel_Interface_Tube.xml +++ b/qt4/spec/Channel_Interface_Tube.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> <tp:license> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -26,9 +26,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. systems to communicate without having to establish network connections themselves. Currently, two types of tube exist: <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Type.DBusTube</tp:dbus-ref> and + >Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains + >Channel.Type.StreamTube.DRAFT</tp:dbus-ref>. This interface contains the properties, signals and methods common to both types of tube; you can only create channels of a specific tube type, not of this type. A tube channel contains exactly one tube; if you need several @@ -38,10 +38,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. HANDLE_TYPE_CONTACT (for 1-1 communication) or of type HANDLE_TYPE_ROOM (to communicate with others in the room simultaneously).</p> + + <p>As an exception to the usual handling of capabilities, connection managers + for protocols with capability discovery, such as XMPP, SHOULD advertise the + capability representing each Tube type that they support + (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and/or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube.DRAFT</tp:dbus-ref>) + even if no client has indicated via + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> + that such a tube is supported.</p> + + <tp:rationale> + <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref> + if the contact announced to support tubes.</p> + </tp:rationale> </tp:docstring> <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" - access="readwrite" tp:name-for-bindings="Parameters"> + access="read" tp:name-for-bindings="Parameters"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Each tube has a dictionary of arbitrary parameters. Parameters are commonly used to bootstrap legacy protocols where you can't @@ -60,11 +79,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p> <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MAY be included in the request. If it is not included in - the request, the connection manager MUST consider the property to be - empty. This property MAY be changed after the channel creation when - the tube is in the state Not_Offered. If the tube is in another - state, changing this property MUST fail without side effects.</p> + this property MUST NOT be included in the request. This property is undefined until the tube is offered + (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref> + or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>). + Once it has been offered, this property MUST NOT change.</p> + <p>When receiving an incoming tube, this property is immutable and so advertised in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> + signal.</p> </tp:docstring> </property> diff --git a/qt4/spec/Channel_Request.xml b/qt4/spec/Channel_Request.xml index bf1bd38c2..c69266ae7 100644 --- a/qt4/spec/Channel_Request.xml +++ b/qt4/spec/Channel_Request.xml @@ -2,8 +2,8 @@ <node name="/Channel_Request" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <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 @@ -21,8 +21,8 @@ MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.ChannelRequest.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.ChannelRequest" + tp:causes-havoc="not yet final"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel request is an object in the ChannelDispatcher representing @@ -34,9 +34,15 @@ <tp:rationale> <p>See - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.CreateChannel</tp:dbus-ref> for rationale for ChannelRequest being a separate object.</p> </tp:rationale> + + <p>A channel request can be cancelled by any client (not just the one + that requested it). This means that the ChannelDispatcher will + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + the resulting channel, or refrain from requesting it at all, rather + than dispatching it to a handler.</p> </tp:docstring> <property name="Account" tp:name-for-bindings="Account" @@ -62,6 +68,20 @@ </tp:docstring> </property> + <property name="PreferredHandler" tp:name-for-bindings="Preferred_Handler" + type="s" tp:type="DBus_Well_Known_Name" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable.</p> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}" tp:type="Qualified_Property_Value_Map[]" access="read"> @@ -79,6 +99,14 @@ </tp:docstring> </property> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel request. + This property cannot change. + </tp:docstring> + </property> + <method name="Proceed" tp:name-for-bindings="Proceed"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Proceed with the channel request.</p> @@ -105,7 +133,7 @@ </tp:docstring> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable"> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> This method has already been called, so it is no longer available. Stop calling it. @@ -144,7 +172,7 @@ <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to this method, the error SHOULD be - <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> + <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> <p>If the channel has already been dispatched to a handler, then it's too late to call this method, and the channel request will diff --git a/qt4/spec/Channel_Type_Contact_Search.xml b/qt4/spec/Channel_Type_Contact_Search.xml index 0b166bb16..b0e905fd6 100644 --- a/qt4/spec/Channel_Type_Contact_Search.xml +++ b/qt4/spec/Channel_Type_Contact_Search.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Contact_Search" 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: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 @@ -18,135 +18,425 @@ Lesser General Public License for more details.</p> 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.Type.ContactSearch" - tp:causes-havoc='not well-tested'> + <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT" + tp:causes-havoc='experimental'> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:struct name="Search_Key_Info"> - <tp:docstring>A struct representing details on search strings.</tp:docstring> - <tp:member type="b" name="Is_Mandatory"> - <tp:docstring>Booleans indicating if the search key is mandatory. - </tp:docstring> - </tp:member> - <tp:member type="g" name="Type_Signature"> - <tp:docstring>The type signature of the value for this search key. - </tp:docstring> - </tp:member> - </tp:struct> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for searching server-stored user directories. A new + channel should be requested by a client for each search attempt, and + closed when the search is completed or the required result has been + found in order to free unused handles.</p> - <tp:mapping name="Search_Key_Info_Map"> - <tp:docstring>A dictionary mapping string search key names to its search details. - </tp:docstring> - <tp:member type="s" name="Term"/> - <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/> - </tp:mapping> + <p>Before searching, the + <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be + inspected to determine the valid search keys which can be provided to + the <tp:member-ref>Search</tp:member-ref> method. A search request is + then started by providing some of these terms to the Search method, and + the <tp:member-ref>SearchState</tp:member-ref> will change from + <code>Not_Started</code> to <code>In_Progress</code>. As results are + returned by the server, the + <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted + for each contact found; when the search is complete, the search state + will be set to <code>Completed</code>. If the search fails after Search + has been called, the state will change to <code>Failed</code>. A + running search can be cancelled by calling + <tp:member-ref>Stop</tp:member-ref>.</p> + + <p>If the protocol supports limiting the number of results returned by a + search and subsequently requesting more results, after + <tp:member-ref>Limit</tp:member-ref> results have been received the + search state will be set to <code>More_Available</code>. Clients may + call <tp:member-ref>More</tp:member-ref> to request another + <tp:member-ref>Limit</tp:member-ref> results. If allowed by the + connection manager, clients may specify the "page size" by specifying + <tp:member-ref>Limit</tp:member-ref> when calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + </p> + + <p>The client should call the channel's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + method when it is finished with the channel, so that any handles held + only by the channel can be released.</p> + + <p>Each channel can only be used for a single search; a new channel + should be requested for each subsequent search. Connection managers + MUST support multiple ContactSearch channels being open at once (even + to the same server, if applicable).</p> + + <p>It does not make sense to request this channel type using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>; + clients SHOULD request channels of this type using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref> + instead.</p> + + <tp:rationale> + <p>A contact search channel that is already in use for a different + search isn't useful.</p> + </tp:rationale> + </tp:docstring> - <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys"> - <arg direction="out" type="s"> - <tp:docstring> - A string with any instructions from the server - </tp:docstring> - </arg> - <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A dictionary mapping string search key names to its search details. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Returns any instructions from the server along with a dictionary of - search key names to their types, and a boolean indicating if the key is - mandatory. The following well-known search key names should be used - where appropriate:</p> - <dl> - <dt>s:first</dt><dd>The desired contact's given name</dd> - <dt>s:last</dt><dd>The desired contact's family name</dd> - <dt>s:nick</dt><dd>The desired contact's nickname</dd> - <dt>s:email</dt><dd>The e-mail address of the desired contact</dd> - </dl> - </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:possible-errors> - </method> <tp:enum name="Channel_Contact_Search_State" type="u"> - <tp:enumvalue suffix="Before" value="0"> + <tp:enumvalue suffix="Not_Started" value="0"> <tp:docstring>The search has not started</tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="During" value="1"> + <tp:enumvalue suffix="In_Progress" value="1"> <tp:docstring>The search is in progress</tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="After" value="2"> + <tp:enumvalue suffix="More_Available" value="2"> + <tp:docstring>The search has paused, but more results can be retrieved + by calling <tp:member-ref>More</tp:member-ref>.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Completed" value="3"> <tp:docstring>The search has been completed</tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Failed" value="4"> + <tp:docstring>The search has failed</tp:docstring> + </tp:enumvalue> </tp:enum> - <method name="GetSearchState" tp:name-for-bindings="Get_Search_State"> - <arg direction="out" type="u" tp:type="Channel_Contact_Search_State"> - <tp:docstring>The search state represented as one of the values of - ChannelContactSearchState</tp:docstring> + + <property name="SearchState" tp:name-for-bindings="Search_State" + access="read" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring> + The current state of this search channel object. Change notification + is via <tp:member-ref>SearchStateChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="SearchStateChanged" + tp:name-for-bindings="Search_State_Changed"> + <arg name="State" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring>The new search state</tp:docstring> + </arg> + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + If the new state is <code>Failed</code>, the name of a D-Bus error + describing what went wrong. Otherwise, the empty string. + </tp:docstring> + </arg> + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about the state transition, which may + include the following well-known keys:</p> + + <dl> + <dt>debug-message (s)</dt> + <dd>Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + </dl> + + <tp:rationale> + <p>This argument allows for future extensions. For instance, + if moving to state <code>Failed</code> because the server + rejected one of our search terms, we could define a key + that indicates which terms were invalid.</p> + </tp:rationale> + </tp:docstring> </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property + changes. The implementation MUST NOT make transitions other than the + following:</p> + + <ul> + <li><code>Not_Started</code> → <code>In_Progress</code></li> + <li><code>In_Progress</code> → <code>More_Available</code></li> + <li><code>More_Available</code> → <code>In_Progress</code></li> + <li><code>In_Progress</code> → <code>Completed</code></li> + <li><code>In_Progress</code> → <code>Failed</code></li> + </ul> + </tp:docstring> + </signal> + + <tp:simple-type name="Contact_Search_Key" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Any of the following search keys, with the indicated result for + the search:</p> + + <dl> + <dt>The empty string</dt> + <dd>Search for the search term in some implementation-dependent + set of fields, using an implementation-dependent algorithm + (e.g. searching for each word mentioned) + <tp:rationale> + The "one big search box" approach to searching, as is familiar + from Google. The Sametime plugin to Pidgin appears to search in + this way. + </tp:rationale> + </dd> + + <dt>A <tp:type>VCard_Field</tp:type></dt> + <dd>Search for the search term in fields matching that name (for + instance, <code>nickname</code> would search nicknames, and + <code>tel</code> would search any available phone number, + regardless of its work/home/mobile/... status).</dd> + + <dt>A <tp:type>VCard_Field</tp:type> followed by + "<code>;</code>" and a + <tp:type>VCard_Type_Parameter</tp:type> of the form + "<code>type=...</code>"</dt> + <dd>Search for the search term in fields of that name and type + only (for instance, <code>tel;type=mobile</code>).</dd> + + <dt><code>x-telepathy-identifier</code></dt> + <dd>Search for contacts whose identifier in the IM protocol + matches the search term (e.g. contains it as a substring) + <tp:rationale> + Otherwise, starting a search by identifier would require the UI + to know the vCard field name corresponding to identifiers in + this protocol, which might be non-standard (like + <code>x-jabber</code>) or not exist at all. + </tp:rationale> + </dd> + + <dt><code>x-gender</code></dt> + <dd>For the search term "male" or "female", search only for contacts + listed as male or female, respectively. The results for other + search terms are undefined; it is likely that contacts with + unspecified gender will only be matched if this search key + is omitted from the request. + <tp:rationale> + Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu + also supports limiting search results by gender. + </tp:rationale> + </dd> + + <dt><code>x-n-family</code></dt> + <dd>Search for the search term in contacts' family names + (the first component of the vCard field <code>n</code>). + <tp:rationale> + Gadu-Gadu and TOC seem to support this mode of searching. + </tp:rationale> + </dd> + + <dt><code>x-n-given</code></dt> + <dd>Search for the search term in contacts' given names + (the second component of the vCard field <code>n</code>). + <tp:rationale> + As for <code>x-n-family</code>. + </tp:rationale> + </dd> + + <dt><code>x-online</code></dt> + <dd>For the search term "yes", search only for contacts who are + currently online. The results for other search terms are undefined. + <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale> + </dd> + + <dt><code>x-adr-locality</code></dt> + <dd>Search for the search term as a locality or city (the fourth + component of the vCard field <code>adr</code>). + <tp:rationale> + Gadu-Gadu and TOC appear to support this. + </tp:rationale> + </dd> + </dl> + </tp:docstring> + </tp:simple-type> + + <property name="Limit" type="u" access="read" + tp:name-for-bindings="Limit"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If supported by the protocol, the maximum number of results that + should be returned, where <code>0</code> represents no limit. If the + protocol does not support limiting results, this should be + <code>0</code>.</p> + + <p>For example, if the terms passed to + <tp:member-ref>Search</tp:member-ref> match <i>Antonius</i>, + <i>Bridget</i> and <i>Charles</i> and this property is + <code>2</code>, the search service SHOULD only return <i>Antonius</i> + and <i>Bridget</i>.</p> + + <p>This property cannot change during the lifetime of the channel. + This property SHOULD be in the Allowed_Properties of a + <tp:type>Requestable_Channel_Class</tp:type> if and only if the + protocol supports specifying a limit; implementations SHOULD use + <code>0</code> as the default if possible, or a protocol-specific + sensible default otherwise.</p> + </tp:docstring> + </property> + + <property name="AvailableSearchKeys" type="as" access="read" + tp:name-for-bindings="Available_Search_Keys"> <tp:docstring> - Returns the current state of this search channel object. + The set of search keys supported by this channel. Example values + include [""] (for protocols where several address fields are + implicitly searched) or ["x-n-given", "x-n-family", "nickname", + "email"] (for XMPP XEP-0055, without extensibility via Data Forms). + This property cannot change during the lifetime of a channel. + + <tp:rationale> + It can be in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal for round-trip reduction. + </tp:rationale> </tp:docstring> - </method> - <method name="Search"> - <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map"> + </property> + + <tp:mapping name="Contact_Search_Map"> + <tp:docstring>A map from search keys to search terms.</tp:docstring> + <tp:member name="Key" type="s" tp:type="Contact_Search_Key"> + <tp:docstring> + The search key to match against + </tp:docstring> + </tp:member> + + <tp:member name="Term" type="s"> + <tp:docstring> + The term or terms to be searched for in the search key; depending on + the protocol and the server implementation, this may be matched by + exact or approximate equality, substring matching, word matching + or any other matching algorithm + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="Search" tp:name-for-bindings="Search"> + <arg direction="in" name="Terms" + type="a{ss}" tp:type="Contact_Search_Map"> <tp:docstring> A dictionary mapping search key names to the desired values </tp:docstring> </arg> <tp:docstring> - Send a request to start a search for contacts on this connection. A - valid search request will cause the SearchStateChanged signal to be - emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING. + Send a request to start a search for contacts on this connection. This + may only be called while the <tp:member-ref>SearchState</tp:member-ref> + is Not_Started; a valid search request will cause the + <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted + with the state In_Progress. </tp:docstring> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is no longer + Not_Started, so this method is no longer available. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The search terms included something this connection manager cannot + search for. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> </tp:possible-errors> </method> + + <method name="More" tp:name-for-bindings="More"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Request that a search in <tp:member-ref>SearchState</tp:member-ref> + <code>More_Available</code> move back to state <code>In_Progress</code> + and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is not + <code>More_Available</code>. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Stop" tp:name-for-bindings="Stop"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Stop the current search. This may not be called while the + <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called + while the SearchState is In_Progress, + <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, + with the state Failed and the error + <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> + + <p>Calling this method on a search in state Completed or Failed + succeeds, but has no effect.</p> + + <tp:rationale> + <p>Specifying Stop to succeed when the search has finished means that + clients who call Stop just before receiving + <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to + handle a useless error.</p> + </tp:rationale> + + <p>Depending on the protocol, the connection manager may not be + able to prevent the server from sending further results after this + method returns; if this is the case, it MUST ignore any further + results.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so + this method is not yet available. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <signal name="SearchResultReceived" tp:name-for-bindings="Search_Result_Received"> <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring>An integer handle for the contact</tp:docstring> + <tp:docstring>An integer handle for the contact, which will remain + valid at least until this Channel closes</tp:docstring> </arg> - <arg name="Values" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring> + <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of fields representing information about this + contact, in the same format used in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref> + interface. It is possible that a separate call to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref> + would return more information than this signal provides.</p> + + <p>This array SHOULD include the <code>x-telepathy-identifier</code> + field, whose values matches the result of calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> + on the Contact handle.</p> + + <tp:rationale> + <p>UIs will most likely want to show the identifier to the user; + while they could do this by inspecting the signalled handle, + including it in this signal is cheap and removes a roundtrip to + look it up.</p> + </tp:rationale> + </tp:docstring> </arg> <tp:docstring> Emitted when a search result is received from the server. </tp:docstring> </signal> - <signal name="SearchStateChanged" - tp:name-for-bindings="Search_State_Changed"> - <arg name="State" type="u" tp:type="Channel_Contact_Search_State"> - <tp:docstring>An integer representing the new search state</tp:docstring> - </arg> + + <property name="Server" tp:name-for-bindings="Server" + type="s" access="read"> <tp:docstring> - Emitted when the search state (as returned by the GetSearchState - method) changes. + <p>For protocols which support searching for contacts on multiple + servers with different DNS names (like XMPP), the DNS name of the + server being searched by this channel, e.g. + "characters.shakespeare.lit". Otherwise, the empty string.</p> + + <tp:rationale> + <p>XEP 0055 defines a mechanism for XMPP clients to search services + of their choice for contacts, such as users.jabber.org (the "Jabber + User Directory").</p> + </tp:rationale> + + <p>This property cannot change during the lifetime of the channel. + This property SHOULD be in the Allowed_Properties of a + <tp:type>Requestable_Channel_Class</tp:type> if and only if the + protocol supports querying multiple different servers; + implementations SHOULD use a sensible default if possible if this + property is not specified in a channel request.</p> + + <tp:rationale> + <p>This allows a client to perform searches on a protocol it knows + nothing about without requiring the user to guess a valid server's + hostname.</p> + </tp:rationale> </tp:docstring> - </signal> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for searching server-stored user directories. A new channel - should be requested by a client for each search attempt, and it should be - closed when the search is completed or the required result has been found - in order to free unused handles. The search can be cancelled at any time - by calling the channel Close method, although depending upon the protocol - the connection manager may not be able to prevent the server from sending - further results.</p> - - <p>Before searching, the GetSearchKeys method should be used to discover any - instructions sent by the server, and the valid search keys which can be - provided to the Search method. A search request is then started by - providing some of these terms to the Search method, and the search status - will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are - returned by the server, the SearchResultReceived signal is emitted for each - contact found, and when the search is complete, the search status will be - set to CHANNEL_SEARCH_STATE_AFTER.</p> - </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_DBus_Tube.xml b/qt4/spec/Channel_Type_DBus_Tube.xml index 2671a17ad..513d77caa 100644 --- a/qt4/spec/Channel_Type_DBus_Tube.xml +++ b/qt4/spec/Channel_Type_DBus_Tube.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> <tp:license> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -58,6 +58,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Offers a D-Bus tube providing the service specified. </tp:docstring> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> <arg direction="out" name="address" type="s"> <tp:docstring> The string describing the address of the private bus. The client diff --git a/qt4/spec/Channel_Type_File_Transfer.xml b/qt4/spec/Channel_Type_File_Transfer.xml index c88834c1d..61e1bba25 100644 --- a/qt4/spec/Channel_Type_File_Transfer.xml +++ b/qt4/spec/Channel_Type_File_Transfer.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> - Copyright (C) 2008 Collabora Limited + Copyright © 2008-2009 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 @@ -76,6 +76,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>The File channel type may be requested for handles of type HANDLE_TYPE_CONTACT. If the channel is requested for any other handle type then the behaviour is undefined.</p> + + <p>Connection managers SHOULD NOT advertise support for file transfer to + other contacts unless it has been indicated by a call to + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>. + </p> + <tp:rationale> + <p>People would send us files, and it would always fail. That would be silly.</p> + </tp:rationale> </tp:docstring> <property name="State" type="u" tp:type="File_Transfer_State" @@ -146,6 +155,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ property you MUST also include this property. If you omit this property from a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> method call then its value will be assumed to be File_Hash_Type_None.</p> + + <p>For each supported hash type, implementations SHOULD include an entry + in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + with this property fixed to that hash type. If the protocol supports + offering a file without a content hash, implementations SHOULD list + this property in Allowed in a requestable channel class, mapping hash + types they don't understand to None. + </p> </tp:docstring> </property> diff --git a/qt4/spec/Channel_Type_Room_List.xml b/qt4/spec/Channel_Type_Room_List.xml index 10ccac606..93ea77705 100644 --- a/qt4/spec/Channel_Type_Room_List.xml +++ b/qt4/spec/Channel_Type_Room_List.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Room_List" 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: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 @@ -87,7 +87,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dd>The current subject of conversation in the room</dd> <dt>members (u)</dt> - <dd>The number of members of the room</dd> + <dd>The number of members in the room</dd> <dt>password (b)</dt> <dd>True if the room requires a password to enter</dd> diff --git a/qt4/spec/Channel_Type_Stream_Tube.xml b/qt4/spec/Channel_Type_Stream_Tube.xml index b64f4a032..060cd0bb0 100644 --- a/qt4/spec/Channel_Type_Stream_Tube.xml +++ b/qt4/spec/Channel_Type_Stream_Tube.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> <tp:license> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -66,6 +66,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> diff --git a/qt4/spec/Channel_Type_Streamed_Media.xml b/qt4/spec/Channel_Type_Streamed_Media.xml index b89065b48..db0b657e9 100644 --- a/qt4/spec/Channel_Type_Streamed_Media.xml +++ b/qt4/spec/Channel_Type_Streamed_Media.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Streamed_Media" 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: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 @@ -22,7 +22,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> - <tp:enum name="Media_Stream_Type" type="u"> + <tp:enum name="Media_Stream_Type" type="u" + array-name="Media_Stream_Type_List"> <tp:enumvalue suffix="Audio" value="0"> <tp:docstring>An audio stream</tp:docstring> </tp:enumvalue> @@ -86,7 +87,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ name="Pending_Send_Flags"/> </tp:struct> - <tp:simple-type name="Stream_ID" type="u"/> + <tp:simple-type name="Stream_ID" type="u" + array-name="Stream_ID_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An unsigned integer identifying a stream within a channel.</p> + </tp:docstring> + </tp:simple-type> <method name="ListStreams" tp:name-for-bindings="List_Streams"> <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" @@ -118,9 +124,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member-ref>ListStreams</tp:member-ref>) </tp:docstring> </arg> - <tp:docstring> - Request that the given streams are removed. + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given streams are removed. If all streams are + removed, the channel MAY close.</p> + + <p>Clients SHOULD NOT attempt to terminate calls by removing all the + streams; instead, clients SHOULD terminate calls by removing the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group.SelfHandle</tp:dbus-ref> + from the channel, using either + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>. + </p> </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> A stream identifier is unknown @@ -209,11 +230,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied.</p> - <p>If streams of the requested types have already been requested - via this method or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>/<tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialVideo</tp:dbus-ref>, - this method SHOULD return successfully.</p> + <p>If streams of the requested types already exist, calling this + method results in the creation of additional streams. Accordingly, + clients wishing to have exactly one audio stream or exactly one + video stream SHOULD check for the current streams using + <tp:member-ref>ListStreams</tp:member-ref> before calling this + method.</p> </tp:docstring> <tp:changed version="0.17.2"> <p>It is valid to use a handle which is neither @@ -231,10 +253,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - A stream type given is invalid + <tp:docstring> + A stream type given is invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + A stream type given is not implemented by the connection manager. + Since 0.17.23, connection managers SHOULD raise this error + in preference to InvalidArgument. + <tp:rationale> + Connection managers can't know whether an unknown number + is a valid stream type that was introduced in a later spec + version. + </tp:rationale> + </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - That contact is not able to do this stream type + <tp:docstring> + That contact's client does not implement one of the given stream + types. For this method, clients SHOULD consider this error and + NotCapable to be equivalent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + That contact's client does not implement one of the given stream + types. Since 0.17.23, connection managers SHOULD raise + this in preference to NotAvailable. + </tp:docstring> </tp:error> </tp:possible-errors> </method> @@ -257,8 +304,54 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The stream type (a value from MediaStreamType) </tp:docstring> </arg> - <tp:docstring> - Emitted when a new stream has been added to this channel. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new stream has been added to this channel. + Clients SHOULD assume that the stream's + <tp:type>Media_Stream_State</tp:type> is initially Disconnected.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose state is already Connecting or Connected, it MUST do this + by emitting StreamAdded, closely followed by + <tp:member-ref>StreamStateChanged</tp:member-ref> indicating a + change to the appropriate state.</p> + + <tp:rationale> + <p>Historically, it was not clear from the StreamAdded signal what + the state of the stream was. telepathy-spec 0.17.22 + clarified this.</p> + </tp:rationale> + + <p>Similarly, clients SHOULD assume that the initial + <tp:type>Media_Stream_Direction</tp:type> of a newly added stream + is Receive, and that the initial + <tp:type>Media_Stream_Pending_Send</tp:type> is + Pending_Local_Send.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose direction or pending-send differs from those initial values, + it MUST do so by emitting StreamAdded, closely followed by + <tp:member-ref>StreamDirectionChanged</tp:member-ref> indicating a + change to the appropriate direction and pending-send state.</p> + + <tp:rationale> + <p>StreamAdded doesn't itself indicate the stream's direction; this + is unfortunate, but is preserved for compatibility.</p> + + <p>This is the appropriate direction for streams added by a remote + contact on existing connection managers, and does not violate + user privacy by automatically sending audio or video (audio streams + start off muted, video streams start off not sending). For + streams added by the local user using the client receiving the + signal, the true direction can also be determined from the return + value of the <tp:member-ref>RequestStreams</tp:member-ref> + method.</p> + + <p>Existing clients typically operate by maintaining a separate + idea of the directions that they would like the streams to have, + and enforcing these intended directions by calling + <tp:member-ref>RequestStreamDirection</tp:member-ref> whenever + needed.</p> + </tp:rationale> </tp:docstring> </signal> @@ -279,12 +372,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The new pending send flags (as defined in ListStreams) </tp:docstring> </arg> - <tp:docstring> - Emitted when the direction or pending flags of a stream are changed. If - the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has - requested that we begin sending on this stream. - <tp:member-ref>RequestStreamDirection</tp:member-ref> - should be called to indicate whether or not this change is acceptable. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the direction or pending flags of a stream are + changed.</p> + + <p>If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user + has requested that we begin sending on this stream. + <tp:member-ref>RequestStreamDirection</tp:member-ref> + should be called to indicate whether or not this change is + acceptable.</p> + + <tp:rationale> + <p>This allows for a MSN-style user interface, "Fred has asked you + to enable your webcam. (Accept | Reject)", if desired.</p> + </tp:rationale> </tp:docstring> </signal> @@ -367,6 +468,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ which point the contact should appear in the channel's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemotePendingMembers</tp:dbus-ref>).</p> + <p>In the past, several other patterns have been used to place outgoing + calls; see + <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> + for the details.</p> + <p>Incoming calls should be signalled as <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> = Contact, <tp:dbus-ref @@ -377,10 +483,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> can be used to move the local user to the group's members.</p> - <p>In the past, several other patterns have been used to place outgoing - calls; see - <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> - for the details.</p> + <p>When the local user accepts an incoming call, the connection manager + SHOULD change the direction of any streams with pending local send + to be sending, without altering whether those streams are + receiving.</p> + + <tp:rationale> + <p>This matches existing practice, and means that a client + can answer incoming calls and get an unmuted microphone/activated + webcam without having to take additional action to accept the + stream directions.</p> + + <p>It does, however, introduce a race condition: a client believing + that it is accepting an audio-only call by calling AddMembers + can inadvertantly accept an audio + video call (and hence activate + sending from a webcam without the user's permission) if a video + stream is added just before AddMembers is processed. This race + should be removed when this specification is revised.</p> + </tp:rationale> <p>In general this should be used in conjunction with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> @@ -422,6 +542,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ connections (as implemented in libjingle 0.3) to traverse NATs. </tp:docstring> </tp:flag> + <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16"> + <tp:docstring> + The handle is capable of establishing ICE UDP peer-to-peer + connections (as defined by the IETF MMUSIC working group) to traverse + NATs. + </tp:docstring> + </tp:flag> </tp:flags> </interface> diff --git a/qt4/spec/Channel_Type_Streamed_Media_Future.xml b/qt4/spec/Channel_Type_Streamed_Media_Future.xml index 2421ed682..07a181e98 100644 --- a/qt4/spec/Channel_Type_Streamed_Media_Future.xml +++ b/qt4/spec/Channel_Type_Streamed_Media_Future.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Streamed_Media_Future" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 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 @@ -109,18 +109,18 @@ SHOULD include the following filters if calling <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> (clients of a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</tp:dbus-ref> + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> SHOULD instead arrange for the ChannelDispatcher to do this, by including the filters in their <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> properties):</p> <ul> <li>{ ChannelType = StreamedMedia }</li> <li>{ ChannelType = StreamedMedia, InitialAudio = true } - if receiving audio-only or audio+video calls is supported</li> + if receiving calls with audio is supported</li> <li>{ ChannelType = StreamedMedia, InitialVideo = true } - if receiving video-only or audio+video calls is supported</li> + if receiving calls with video is supported</li> </ul> <tp:rationale> @@ -128,21 +128,6 @@ like XMPP, need this information to advertise the appropriate capabilities for their protocol.</p> </tp:rationale> - - <p>If { ChannelType = StreamedMedia } is passed to - SetSelfCapabilities, but no more specific channel class for - audio or video has been passed to that method (in the presence - of a ChannelDispatcher, this would mean that there is at least one - client with that channel class in its HandlerChannelFilter, but - no installed client has the more specific channel classes in its - HandlerChannelFilter), then the connection manager SHOULD advertise - support for every content type (audio or video) that it - supports.</p> - - <tp:rationale> - <p>This lowers the "barrier to entry" by allowing a simple client - to say merely that it supports streamed media at all.</p> - </tp:rationale> </tp:docstring> </property> diff --git a/qt4/spec/Channel_Type_Text.xml b/qt4/spec/Channel_Type_Text.xml index 5c28dce8f..7d6e314b2 100644 --- a/qt4/spec/Channel_Type_Text.xml +++ b/qt4/spec/Channel_Type_Text.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Text" 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: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 @@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:simple-type name="Message_ID" type="u"> + <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List"> <tp:docstring> A unique-per-channel identifier for an incoming message. These SHOULD be allocated in a way that minimizes collisions (in particular, @@ -87,7 +87,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also been called. </tp:docstring> - <tp:deprecated since="0.17.3"> + <tp:deprecated version="0.17.3"> Setting this to true is NOT RECOMMENDED for clients that have some sort of persistent message storage - clients SHOULD only acknowledge messages after they have actually stored them, which is @@ -290,7 +290,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> - <tp:enum name="Channel_Text_Message_Type" type="u"> + <tp:enum name="Channel_Text_Message_Type" type="u" + array-name="Channel_Text_Message_Type_List"> <tp:docstring> The type of message. </tp:docstring> diff --git a/qt4/spec/Channel_Type_Tubes.xml b/qt4/spec/Channel_Type_Tubes.xml index f6829b5da..2cc0131b0 100644 --- a/qt4/spec/Channel_Type_Tubes.xml +++ b/qt4/spec/Channel_Type_Tubes.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> - Copyright (C) 2007-2008 Collabora Limited + Copyright © 2007-2009 Collabora Limited </tp:copyright> <tp:license> This library is free software; you can redistribute it and/or @@ -71,57 +71,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:member> </tp:struct> - <tp:struct name="Socket_Address_IPv4"> - <tp:docstring>An IPv4 address and port.</tp:docstring> - <tp:member type="s" name="Address"> - <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal - numbers, each between 0 and 255 inclusive, e.g. - "192.168.0.1".</tp:docstring> - </tp:member> - <tp:member type="q" name="Port"> - <tp:docstring>The TCP or UDP port number.</tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Socket_Address_IPv6"> - <tp:docstring>An IPv6 address and port.</tp:docstring> - <tp:member type="s" name="Address"> - <tp:docstring>An IPv6 address literal as specified by RFC2373 - section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> - </tp:member> - <tp:member type="q" name="Port"> - <tp:docstring>The TCP or UDP port number.</tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Socket_Netmask_IPv4"> - <tp:docstring>An IPv4 network or subnet.</tp:docstring> - <tp:member type="s" name="Address"> - <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal - numbers, each between 0 and 255 inclusive, e.g. - "192.168.0.1".</tp:docstring> - </tp:member> - <tp:member type="y" name="Prefix_Length"> - <tp:docstring>The number of leading bits of the address that must - match, for this netmask to be considered to match an - address.</tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Socket_Netmask_IPv6"> - <tp:docstring>An IPv6 network or subnet.</tp:docstring> - <tp:member type="s" name="Address"> - <tp:docstring>An IPv6 address literal as specified by RFC2373 - section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> - </tp:member> - <tp:member type="y" name="Prefix_Length"> - <tp:docstring>The number of leading bits of the address that must - match, for this netmask to be considered to match an - address.</tp:docstring> - </tp:member> - </tp:struct> - - <tp:enum name="Tube_Type" type="u"> + <tp:enum name="Tube_Type" type="u" array-name="Tube_Type_List"> <tp:enumvalue suffix="DBus" value="0"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The tube is D-Bus tube as described by the @@ -193,7 +143,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enum> - <tp:enum name="Socket_Access_Control" type="u"> + <tp:enum name="Socket_Access_Control" type="u" + array-name="Socket_Access_Control_List"> <tp:enumvalue suffix="Localhost" value="0"> <tp:docstring> The IP or Unix socket can be accessed by any local user (e.g. diff --git a/qt4/spec/Client.xml b/qt4/spec/Client.xml index d0bb8e5f5..ba29900ac 100644 --- a/qt4/spec/Client.xml +++ b/qt4/spec/Client.xml @@ -20,8 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Client.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Client" + tp:causes-havoc="not yet final"> <tp:added version="0.17.12">(as a draft)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/qt4/spec/Client_Approver.xml b/qt4/spec/Client_Approver.xml index 8f59a1939..62f669408 100644 --- a/qt4/spec/Client_Approver.xml +++ b/qt4/spec/Client_Approver.xml @@ -20,21 +20,30 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Client.Approver.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Client.Approver" + tp:causes-havoc="not yet final"> <tp:added version="0.17.12">(as a draft)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.Client"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Approvers notify the user that new channels have been created, - and allow the user to accept or reject those channels.</p> - - <p>They can also select which channel handler will be used for the + <p>Approvers are clients that notify the user that new channels have + been created by a contact, and allow the user to accept or reject + those channels. The new channels are represented by a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + object, which is passed to the + <tp:member-ref>AddDispatchOperation</tp:member-ref> method.</p> + + <tp:rationale> + <p>For instance, Empathy's tray icon, or the answer/reject window + seen when a Maemo device receives a VoIP call, should be + Approvers.</p> + </tp:rationale> + + <p>Approvers can also select which channel handler will be used for the channel, for instance by offering the user a list of possible - handlers rather than just an accept/reject choice.</p> - - <p>However, the Channel Dispatcher must be able to prioritize + handlers rather than just an accept/reject choice. + However, the Channel Dispatcher must be able to prioritize possible handlers on its own using some reasonable heuristic, probably based on user configuration.</p> @@ -49,12 +58,22 @@ window and highlights contacts there, and one that is part of a full-screen media player.</p> - <p>Any approver can approve the handling of a channel with a - particular channel handler. Approvers can also request that the - channel is rejected. The first approver to reply gets its decision - acted on; any other approvers that reply at the same time will - get a D-Bus error, indicating that the channel has already been - dealt with.</p> + <p>Any approver can approve the handling of a channel dispatch operation + with a particular channel handler by calling the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> + method. Approvers can also attempt to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + channels; if this succeeds, the approver may handle the channels + itself (if it is also a Handler), or close the channels in order to + reject them.</p> + + <p>At the D-Bus level, there is no "reject" operation: approvers wishing + to reject channels SHOULD call the Claim method, then (if it succeeds) + close the channels in any way they see fit.</p> + + <p>The first approver to reply gets its decision acted on; any other + approvers that reply at approximately the same time will get a D-Bus + error, indicating that the channel has already been dealt with.</p> <p>Approvers should usually prompt the user and ask for confirmation, rather than dispatching the channel to a handler @@ -67,16 +86,16 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A specification of the channels in which this approver is interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> - method should be called by the channel dispatcher whenever the - channels in a channel dispatch operation - match this description.</p> - - <p>(FIXME: what happens if some but not all of the channels - match this?)</p> + method should be called by the channel dispatcher whenever at least + one of the channels in a channel dispatch operation matches this + description.</p> <p>This property works in exactly the same way as the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref> - property. In the .client file, it is represented in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> + property. In particular, it cannot change while the approver 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 ApproverChannelFilter instead of ObserverChannelFilter.</p> @@ -92,18 +111,62 @@ operations already exist.</p> <p>The channel dispatcher SHOULD call this method on all approvers - at the same time. If no approvers return from this method + at the same time. If an approver returns an error from this method, + the approver is assumed to be faulty.</p> + + <p>If no approvers return from this method successfully (including situations where there are no matching approvers at all), the channel dispatcher SHOULD consider this to be an error, and recover by dispatching the channel to the most preferred handler.</p> <tp:rationale> - Processes that aren't approvers shouldn't be making connections - anyway - there should always be at least one approver running. + Processes that aren't approvers (or don't at least ensure that there + is some approver) probably shouldn't be making connections + anyway, so there should always be at least one approver running. </tp:rationale> </tp:docstring> + <arg name="Channels" direction="in" + type="a(oa{sv})" tp:type="Channel_Details[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The initial value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Channels</tp:dbus-ref> + property, containing the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + to be dispatched and their properties.</p> + + <tp:rationale> + <p>This can't be signalled to the approver through the Properties + parameter of this method, because Channels is not an immutable + property.</p> + </tp:rationale> + + <p>This argument always contains all of the channels in the channel + dispatch operation, even if not all of them actually match + the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p> + + <tp:rationale> + <p>This seems the least bad way to handle such a situation; + see the discussion on + <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug + #21090</a>.</p> + </tp:rationale> + + <p>The actual channels to be dispatched may reduce as channels are + closed: this is signalled by <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>. + </p> + + <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>. + (if desired) before returning from AddDispatchOperation, since + those signals are guaranteed not to be emitted until after all + AddDispatchOperation calls have returned (with success or failure) + or timed out.</p> + </tp:docstring> + </arg> + <arg name="DispatchOperation" type="o" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The @@ -115,19 +178,16 @@ <arg name="Properties" type="a{sv}" tp:type="Qualified_Property_Value_Map" direction="in"> <tp:docstring> - Properties of the channel dispatch operation. This MUST NOT include - properties that could change, SHOULD include as many properties as - possible given that constraint, and MUST include at least the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Account</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Connection</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Channels</tp:dbus-ref> - and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">PossibleHandlers</tp:dbus-ref> - properties. + <p>Properties of the channel dispatch operation. This MUST NOT + include properties that could change, SHOULD include as many + properties as possible given that constraint, and MUST include at + least the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref> + properties.</p> </tp:docstring> </arg> </method> diff --git a/qt4/spec/Client_Handler.xml b/qt4/spec/Client_Handler.xml index 59c253b28..da4870158 100644 --- a/qt4/spec/Client_Handler.xml +++ b/qt4/spec/Client_Handler.xml @@ -20,16 +20,31 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Client.Handler.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Client.Handler" + tp:causes-havoc="not yet final"> <tp:added version="0.17.12">(as a draft)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.Client"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Channel handlers are the eventual handler for a channel or a - channel bundle; a typical channel handler is a user interface - process handling channels of a particular type.</p> + <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> @@ -60,8 +75,11 @@ 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.DRAFT.ObserverChannelFilter</tp:dbus-ref> - property. In the .client file, it is represented in 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> @@ -105,13 +123,14 @@ paths.</p> </tp:rationale> - <p>This method can raise any D-Bus error. If it does, or if the - handler loses its bus name before all the channels have closed, the + <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.</p> + dispatcher MUST recover in an implementation-specific way; it MAY + attempt to dispatch the channels to another handler, or close the + channels.</p> - <p>It is RECOMMENDED that the channel dispatcher attempts to - close the channels using + <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 @@ -119,6 +138,17 @@ 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"> @@ -140,7 +170,8 @@ </tp:docstring> </arg> - <arg name="Channels" type="a(oa{sv})" direction="in"> + <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. @@ -148,12 +179,17 @@ </arg> <arg name="Requests_Satisfied" type="ao" direction="in"> - <tp:docstring> - The requests satisfied by these channels. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requests satisfied by these channels.</p> <tp:rationale> - There can be more than one, if they were EnsureChannel - requests. + <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> @@ -167,95 +203,23 @@ </tp:docstring> </arg> - <!-- FIXME: invent a way to say "any error is possible" in spec markup --> - </method> - - <method name="AddRequest" tp:name-for-bindings="Add_Request"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the ChannelDispatcher to indicate that channels have been - requested, and that if the request is successful, they will be - handled by this Handler.</p> - - <tp:rationale> - <p>This allows the UI to start preparing to handle the channels - in advance (e.g. render a window with an "in progress" message), - improving perceived responsiveness.</p> - </tp:rationale> - - <p>(FIXME: how do we know the returned channels will be handled by - this handler? Do we just assume that they'll match the - HandlerChannelFilter iff the request does?)</p> - </tp:docstring> - - <arg name="Request" type="o" direction="in"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object, which MUST have been returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">CreateChannel</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">EnsureChannel</tp:dbus-ref> - before this method is called. - - <tp:rationale> - See those methods for the rationale of this ordering. - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map" direction="in"> - <tp:docstring> - <p>Some of the properties of the ChannelRequest. To avoid race - conditions, this dictionary MUST NOT include properties whose - values could subsequently change. It SHOULD include as many - properties as possible, given that constraint.</p> - - <p>In particular, the properties <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">Requests</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> - MUST be included.</p> - </tp:docstring> - </arg> - </method> - - <method name="RemoveFailedRequest" - tp:name-for-bindings="Remove_Failed_Request"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the ChannelDispatcher to indicate that a request - previously passed to <tp:member-ref>AddRequest</tp:member-ref> - has failed and should be disregarded.</p> - </tp:docstring> - - <arg name="Request" type="o" direction="in"> - <tp:docstring> - The request that failed. - </tp:docstring> - </arg> - - <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"> + <arg name="Handler_Info" type="a{sv}" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of the D-Bus error with which the request failed.</p> + <p>Additional information about these channels. No keys are + currently defined.</p> - <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>, - this indicates that the request succeeded, but all the resulting - channels were given to some other handler.</p> + <p>If keys are defined for this dictionary, all will be optional; + handlers MAY safely ignore any entry in this dictionary.</p> </tp:docstring> </arg> - <arg name="Message" type="s" direction="in"> - <tp:docstring> - Any message supplied with the D-Bus error. - </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 Handler is currently handling. - </p> + <p>A list of the channels that this process is currently handling.</p> <p>There is no change notification.</p> @@ -271,6 +235,17 @@ 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> diff --git a/qt4/spec/Client_Interface_Requests.xml b/qt4/spec/Client_Interface_Requests.xml new file mode 100644 index 000000000..1b0de9838 --- /dev/null +++ b/qt4/spec/Client_Interface_Requests.xml @@ -0,0 +1,173 @@ +<?xml version="1.0" ?> +<node name="/Client_Interface_Requests" + 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.Interface.Requests" + tp:causes-havoc="not yet final"> + <tp:added version="0.17.23">(as a draft; functionality + moved from Handler)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client"/> + <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface can be implemented by a Handler to be notified about + requests for channels that it is likely to be asked to handle.</p> + </tp:docstring> + + <method name="AddRequest" tp:name-for-bindings="Add_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that channels have been + requested, and that if the request is successful, they will probably + be handled by this Handler. The ChannelDispatcher SHOULD only + call this method on one handler per request.</p> + + <tp:rationale> + <p>This allows the UI to start preparing to handle the channels + in advance (e.g. render a window with an "in progress" message), + improving perceived responsiveness.</p> + + <p>The use of "probably" is because you can't necessarily tell from + a channel request which handler will handle particular channels. + A reasonable heuristic would be to match the request against the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>, + and respect the preferred handler (if any).</p> + </tp:rationale> + + <p>If the request succeeds and is given to the expected Handler, + the Requests_Satisfied parameter to + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + can be used to match the channel to a previous AddRequest call.</p> + + <tp:rationale> + <p>This lets the UI direct the channels to the window that it + already opened.</p> + </tp:rationale> + + <p>If the request fails, the expected handler is notified by the + channel dispatcher calling its + <tp:member-ref>RemoveRequest</tp:member-ref> method.</p> + + <tp:rationale> + <p>This lets the UI close the window or display the error.</p> + </tp:rationale> + + <p>The channel dispatcher SHOULD remember which handler was notified, + and if the channel request succeeds, it SHOULD dispatch the channels + to the expected handler, unless the channels do not match that + handler's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>. + If the channels are not dispatched to the expected handler, the + handler that was expected is notified by the channel dispatcher + calling its <tp:member-ref>RemoveRequest</tp:member-ref> method + with the NotYours error.</p> + + <tp:rationale> + <p>Expected handling is for the UI to close the window it + previously opened.</p> + </tp:rationale> + + <p>Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.</p> + + <tp:rationale> + <p>Calls to this method are merely a notification.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which MUST have been returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> + before this method is called. + + <tp:rationale> + See those methods for the rationale of this ordering. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + <p>Some of the properties of the ChannelRequest. To avoid race + conditions, this dictionary MUST NOT include properties whose + values could subsequently change. It SHOULD include as many + properties as possible, given that constraint.</p> + + <p>In particular, the properties <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> + MUST be included.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveRequest" + tp:name-for-bindings="Remove_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that a request + previously passed to <tp:member-ref>AddRequest</tp:member-ref> + has failed and should be disregarded.</p> + + <p>Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.</p> + + <tp:rationale> + <p>Calls to this method are merely a notification.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The request that failed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the D-Bus error with which the request failed.</p> + + <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>, + this indicates that the request succeeded, but all the resulting + channels were given to some other handler.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring> + Any message supplied with the D-Bus error. + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Observer.xml b/qt4/spec/Client_Observer.xml index 40c71e739..58b67b3f9 100644 --- a/qt4/spec/Client_Observer.xml +++ b/qt4/spec/Client_Observer.xml @@ -20,11 +20,11 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Client.Observer.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Client.Observer" + tp:causes-havoc="not yet final"> <tp:added version="0.17.12">(as a draft)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.Client"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Observers monitor the creation of new channels. This @@ -65,11 +65,11 @@ to the Observer.</p> </tp:rationale> - <p>Whenever new channels are signalled, the channel dispatcher - will notify all running or activatable observers whose + <p>Whenever a collection of new channels is signalled, the channel + dispatcher will notify all running or activatable observers whose <tp:member-ref>ObserverChannelFilter</tp:member-ref> property (possibly as cached in the .client file) indicates that they are - interested in the channel.</p> + interested in some of the channels.</p> <p>Observers are activated for all channels in which they have registered an interest - incoming, outgoing or automatically created - @@ -78,6 +78,15 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> property.</p> + + <p>Because it might take time for an observer to become ready (for + instance, a Text logger needs to wait until pending messages have been + downloaded), the channel dispatcher must wait (up to some timeout) for + all observers to return from + <tp:member-ref>ObserveChannels</tp:member-ref> before letting anything + destructive happen. Destructive things (e.g. acknowledging messages) + are defined to be done by handlers, therefore HandleWith and Claim + aren't allowed to succeed until all observers are ready.</p> </tp:docstring> <property name="ObserverChannelFilter" @@ -87,11 +96,9 @@ <p>A specification of the channels in which this observer is interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method should be called by the channel dispatcher whenever any of the new - channels in a NewChannels signal match this description.</p> - - <p>(FIXME: open issue: do we want this, and the corresponding - Approver and Handler properties, to be able to change at - runtime?)</p> + channels in a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal match this description.</p> <p>Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:</p> @@ -116,10 +123,28 @@ </dl> - <p>This property never changes while the observer process is - running. For activatable processes, the filter can change due to an - upgrade - the channel dispatcher SHOULD observe changes to .client files - using a mechanism like inotify.</p> + <p>This property never changes while the observer process owns its + Client bus name. For activatable processes, the filter can change + due to an upgrade - the channel dispatcher SHOULD observe changes to + .client files using a mechanism like inotify.</p> + + <tp:rationale> + <p>Not allowing this property to change is a simplification, + particularly for activatable processes (we reject the possibility + that a process with a .client file, when activated, has a filter + that differs from what its .client file said).</p> + + <p>If an Observer wants to add extra channels to its list of + interests at runtime, it can register an additional Client bus name + (for instance, the org.freedesktop.Telepathy.Client.Empathy process + with unique name :1.42 could additionally register + org.freedesktop.Telepathy.Client.Empathy._1_42) with additional + filters. To remove those filters, it can release the bus name; + it could even re-claim the bus name immediately, with different + filters.</p> + + <p>The same principle is applied to Approvers and Handlers.</p> + </tp:rationale> <p>For observers that have a .client file, the channel dispatcher may discover this property from keys of the form @@ -138,15 +163,15 @@ a local client:</p> <pre> -[org.freedesktop.Telepathy.Client.DRAFT] -Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT; +[org.freedesktop.Telepathy.Client] +Interfaces=org.freedesktop.Telepathy.Client.Observer; -[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0] +[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0] org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 org.freedesktop.Telepathy.Channel.Requested b=true -[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 1] +[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1] org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=2 org.freedesktop.Telepathy.Channel.Requested b=true @@ -158,7 +183,18 @@ org.freedesktop.Telepathy.Channel.Requested b=true <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when channels in which the - observer has registered an interest are created.</p> + observer has registered an interest are announced in a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal.</p> + + <p>If the same NewChannels signal announces some channels that match + the filter, and some that do not, then only a subset of the channels + (those that do match the filter) are passed to this method.</p> + + <p>If the channel dispatcher will split up the channels from a single + NewChannels signal and dispatch them separately (for instance + because no installed Handler can handle all of them), it will call + ObserveChannels several times.</p> <p>The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's @@ -167,12 +203,23 @@ org.freedesktop.Telepathy.Channel.Requested b=true <tp:rationale> <p>The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets - ObserveChannel, text channel handler gets + ObserveChannels, text channel handler gets <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> channel handler starts up faster and acknowledges messages, logger never sees those messages.</p> </tp:rationale> + + <p>The channel dispatcher SHOULD NOT change its behaviour based on + whether this method succeeds or fails: there are no defined D-Bus + errors for this method, and if it fails, this only indicates that + an Observer is somehow broken.</p> + + <tp:rationale> + <p>The expected error response in the channel dispatcher is to + log a warning, and otherwise continue as though this method + had succeeded.</p> + </tp:rationale> </tp:docstring> <arg name="Account" type="o" direction="in"> @@ -206,19 +253,41 @@ org.freedesktop.Telepathy.Channel.Requested b=true </tp:docstring> </arg> - <arg name="DispatchOperation" type="o" direction="in"> + <arg name="Dispatch_Operation" type="o" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The path to the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + for these channels, or the special value '/' if there is no + ChannelDispatchOperation (because the channels were requested, not + incoming).</p> + + <p>If the Observer calls <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> + on the dispatch operation, it MUST be careful to avoid deadlock, + since these methods cannot return until the Observer has returned + from <tp:member-ref>ObserveChannels</tp:member-ref>.</p> + + <tp:rationale> + <p>This allows an Observer to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + a set of channels without having to match up calls to this method + with calls to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Requests_Satisfied" type="ao" direction="in"> <tp:docstring> - The path to the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref> - for these channels, or the special value '/' if there is no - ChannelDispatchOperation (because the channels were requested, not incoming). + The requests satisfied by these channels. <tp:rationale> - This allows an Observer to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref> - a set of channels without having to match up calls to this method - with calls to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>. + If the same process is an Observer and a Handler, it can be useful + to be given this information as soon as possible (it will also + be passed to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler.HandleChannels</tp:dbus-ref>). </tp:rationale> </tp:docstring> </arg> diff --git a/qt4/spec/Connection.xml b/qt4/spec/Connection.xml index 97a3c4c70..2b03f964c 100644 --- a/qt4/spec/Connection.xml +++ b/qt4/spec/Connection.xml @@ -22,8 +22,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> <interface name="org.freedesktop.Telepathy.Connection"> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Requests"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> <tp:struct name="Channel_Info" array-name="Channel_Info_List"> + <tp:deprecated version="0.17.23"/> <tp:docstring>A struct representing a channel, as returned by ListChannels on the Connection interface.</tp:docstring> <tp:member type="o" name="Channel"> @@ -45,17 +48,14 @@ USA.</p> </tp:struct> <method name="Connect" tp:name-for-bindings="Connect"> - <tp:docstring> - Request that the connection be established. This will be done - asynchronously and errors will be returned by emitting - <tp:member-ref>StatusChanged</tp:member-ref> signals. - </tp:docstring> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the connection be established. This will be done + asynchronously and errors will be returned by emitting + <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - The connection is already connecting or connected - </tp:error> - </tp:possible-errors> + <p>Calling this method on a Connection that is already connecting + or connected is allowed, and has no effect.</p> + </tp:docstring> </method> <method name="Disconnect" tp:name-for-bindings="Disconnect"> @@ -272,6 +272,12 @@ USA.</p> </method> <method name="ListChannels" tp:name-for-bindings="List_Channels"> + <tp:deprecated version="0.17.23">Use the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.Channels</tp:dbus-ref> + property instead. + </tp:deprecated> + <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]" name="Channel_Info"> <tp:docstring> @@ -289,6 +295,12 @@ USA.</p> </method> <signal name="NewChannel" tp:name-for-bindings="New_Channel"> + <tp:deprecated version="0.17.23">Connection managers MUST still + emit this signal, but clients SHOULD listen for the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.NewChannels</tp:dbus-ref> + signal instead. + </tp:deprecated> + <arg name="Object_Path" type="o"> <tp:docstring> A D-Bus object path for the channel object on this service @@ -381,6 +393,15 @@ USA.</p> </method> <method name="RequestChannel" tp:name-for-bindings="Request_Channel"> + <tp:deprecated version="0.17.23">Use + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.CreateChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> + instead. Connection managers MAY implement RequestChannel by + raising NotImplemented, or implement fewer types of channel via + this API.</tp:deprecated> + <arg direction="in" name="Type" type="s" tp:type="DBus_Interface"> <tp:docstring> A D-Bus interface name representing base channel type @@ -534,27 +555,31 @@ USA.</p> </tp:enumvalue> </tp:enum> - <tp:simple-type name="Handle" type="u"> + <tp:simple-type name="Handle" type="u" array-name="Handle_List"> <tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring> </tp:simple-type> - <tp:simple-type name="Contact_Handle" type="u"> + <tp:simple-type name="Contact_Handle" type="u" + array-name="Contact_Handle_List"> <tp:docstring>An unsigned 32-bit integer representing a handle of type Handle_Type_Contact</tp:docstring> </tp:simple-type> - <tp:simple-type name="Room_Handle" type="u"> + <tp:simple-type name="Room_Handle" type="u" + array-name="Room_Handle_List"> <tp:docstring>An unsigned 32-bit integer representing a handle of type Handle_Type_Room</tp:docstring> </tp:simple-type> - <tp:simple-type name="List_Handle" type="u"> + <tp:simple-type name="List_Handle" type="u" + array-name="List_Handle_List"> <tp:docstring>An unsigned 32-bit integer representing a handle of type Handle_Type_List</tp:docstring> </tp:simple-type> - <tp:simple-type name="Group_Handle" type="u"> + <tp:simple-type name="Group_Handle" type="u" + array-name="Group_Handle_List"> <tp:docstring>An unsigned 32-bit integer representing a handle of type Handle_Type_Group</tp:docstring> </tp:simple-type> @@ -970,7 +995,8 @@ USA.</p> <p>As well as the methods and signatures below, arbitrary interfaces may be provided by the Connection object to represent extra connection-wide - functionality, such as the Connection.Interface.Presence for receiving and + functionality, such as the Connection.Interface.SimplePresence for + receiving and reporting presence information, and Connection.Interface.Aliasing for connections where contacts may set and change an alias for themselves. These interfaces can be discovered using the @@ -1007,6 +1033,11 @@ USA.</p> bus names and object paths with more than 7 components. We now restrict Connection bus names/object paths to have exactly 7 components.</tp:changed> + + <tp:changed version="0.17.23">The Requests and Contacts interfaces + are now mandatory. Their functionality will be merged into the main + Connection interface at some point in future.</tp:changed> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Avatars.xml b/qt4/spec/Connection_Interface_Avatars.xml index 7ef26afd8..e6f7ac59f 100644 --- a/qt4/spec/Connection_Interface_Avatars.xml +++ b/qt4/spec/Connection_Interface_Avatars.xml @@ -21,7 +21,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:simple-type name="Avatar_Token" type="s"> + <tp:simple-type name="Avatar_Token" type="s" + array-name="Avatar_Token_List"> <tp:changed version="0.17.16">strengthened uniqueness requirements so (CM name, protocol, token) is unique; previously only (our Account, remote contact identifier, token) was required to be @@ -124,8 +125,131 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> + <property name="SupportedAvatarMIMETypes" + tp:name-for-bindings="Supported_Avatar_MIME_Types" + type="as" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + An array of supported MIME types (e.g. "image/jpeg"). + Clients MAY assume that the first type in this array is preferred. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarHeight" + tp:name-for-bindings="Minimum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum height in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarWidth" + tp:name-for-bindings="Minimum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum width in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="RecommendedAvatarHeight" + tp:name-for-bindings="Recommended_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended height in pixels of an avatar on this protocol, or 0 if + there is no preferred height. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + In XMPP a recommended width is given by the protocol specification; + in proprietary protocols, using the same avatar size as the + proprietary client is likely to lead to the best display to other + users. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RecommendedAvatarWidth" + tp:name-for-bindings="Recommended_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended width in pixels of an avatar on this protocol, or 0 if + there is no preferred width. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + The rationale is the same as for + <tp:member-ref>RecommendedAvatarHeight</tp:member-ref>. + </tp:rationale> + </tp:docstring> + </property> + + <property name="MaximumAvatarHeight" + tp:name-for-bindings="Maximum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum height in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarWidth" + tp:name-for-bindings="Maximum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum width in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarBytes" + tp:name-for-bindings="Maximum_Avatar_Bytes" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum size in bytes of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + <method name="GetAvatarRequirements" tp:name-for-bindings="Get_Avatar_Requirements"> + <tp:deprecated version="0.17.22">Use GetAll to retrieve the + D-Bus properties on this interface, falling back to this method + on failure.</tp:deprecated> <arg direction="out" type="as" name="MIME_Types"> <tp:docstring> An array of supported MIME types (eg image/jpeg) @@ -179,6 +303,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ same order as the given array of contact handles </tp:docstring> </arg> + <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens + instead.</tp:deprecated> <tp:docstring> Get the unique tokens for all of the given contacts' avatars. @@ -244,6 +370,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ unknown </tp:docstring> </arg> + <tp:deprecated version="0.15.5">Use RequestAvatars + instead.</tp:deprecated> <tp:docstring> Request the avatar for a given contact. Using this method in new Telepathy clients is deprecated; use RequestAvatars instead. diff --git a/qt4/spec/Connection_Interface_Contact_Info.xml b/qt4/spec/Connection_Interface_Contact_Info.xml index e7b033bf1..d08545466 100644 --- a/qt4/spec/Connection_Interface_Contact_Info.xml +++ b/qt4/spec/Connection_Interface_Contact_Info.xml @@ -31,28 +31,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:member> <tp:member type="as" name="Parameters"> - <tp:docstring> - A list of (lowercased) vCard type parameters applicable to this field. - For example, a contact's preferred home address would have parameters - 'home' and 'pref'. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of vCard type parameters applicable to this field, with their + values. The type parameter names, and any values that are + case-insensitive in vCard, MUST be in lower case. For example, a + contact's preferred home address would have parameters + 'type=home' and 'type=pref'.</p> <tp:rationale> - This is a list of strings rather than a bitwise OR of enum members - because vCard type parameters are essentially arbitrary strings. + The type parameter 'type' is likely to be the most common, but + there can be others, such as 'language=en'. + </tp:rationale> + + <p>Characters which are required to be escaped in vCard type + parameters should not be escaped in this list. For instance, + a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become + ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p> + + <tp:rationale> + This avoids Telepathy UIs having to understand the escaping and + unescaping rules for vCards. The type parameter name is not + allowed (by RFC 2425) to contain an '=' character, so no ambiguity + is introduced. </tp:rationale> </tp:docstring> </tp:member> <tp:member type="as" name="Field_Value"> - <tp:docstring> - For unstructured vCard fields (such as 'fn', a formatted name - field), a single-element array containing the field's value; for - structured fields (such as 'adr', an address field), an array - corresponding to the semicolon-separated elements of the field (with - empty strings for empty elements). A vCard field with multiple - comma-separated values should be represented by several - <tp:type>Contact_Info_Field</tp:type>s. Characters which are - required to be escaped in vCard values, such as semi-colons, should - not be escaped in this list. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For unstructured vCard fields (such as 'fn', a formatted name + field), a single-element array containing the field's value.</p> + + <p>For structured fields (such as 'adr', an address field), an array + corresponding to the semicolon-separated elements of the field (with + empty strings for empty elements).</p> + + <p>A vCard field with multiple comma-separated values, such as + 'nickname', should be represented by several + <tp:type>Contact_Info_Field</tp:type>s.</p> + + <p>Characters which are required to be escaped in vCard values, such as + semi-colons and newlines, should not be escaped in this list (e.g. if + a value contains a newline, the data passed over D-Bus should + contain a literal newline character).</p> <tp:rationale> An earlier draft of this interface split structured vCard fields @@ -103,7 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ BEGIN:vCard VERSION:3.0 FN:Wee Ninja - N:Ninja;Wee;;;-san + N;LANGUAGE=ja:Ninja;Wee;;;-san ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire ;CB2 1SJ;UK @@ -111,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk EMAIL;TYPE=INTERNET:wee.ninja@example.com URL:http://www.thinkgeek.com/geektoys/plush/8823/ + NICKNAME:HR Ninja,Enforcement Ninja END:vCard</pre> <p>would be represented by (in Python-like syntax):</p> @@ -118,15 +139,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <pre> [ ('fn', [], ['Wee Ninja']), - ('n', [], ['Ninja', 'Wee', '', '', '-san']), + ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']), ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']), - ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge', - 'Cambridgeshire','CB2 1SJ','UK']), - ('tel', ['voice','work'], ['+44 1223 362967']), - ('tel', ['voice','work'], ['+44 7700 900753']), - ('email', ['internet','pref'], ['wee.ninja@collabora.co.uk']), - ('email', ['internet'], ['wee.ninja@example.com']), + ('adr', ['type=work','type=postal','type=parcel'], + ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']), + ('tel', ['type=voice','type=work'], ['+44 1223 362967']), + ('tel', ['type=voice','type=work'], ['+44 7700 900753']), + ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']), + ('email', ['type=internet'], ['wee.ninja@example.com']), ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']), + ('nickname', [], ['HR Ninja']), + ('nickname', [], ['Enforcement Ninja']) ]</pre> </tp:docstring> </tp:struct> @@ -267,11 +290,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enumvalue> </tp:enum> + <tp:simple-type name="VCard_Field" type="s"> + <tp:docstring> + A string naming a field in a vCard, such as "fn" or "adr". Although + these are case-insensitive in RFC 2425, in Telepathy they MUST be + normalized to lower case. In the terminology of RFC 2425 this is + called a "type name", and corresponds to the "name" production given + in the ABNF. + </tp:docstring> + </tp:simple-type> + + <tp:simple-type name="VCard_Type_Parameter" type="s" + array-name="VCard_Type_Parameter_List"> + <tp:docstring> + A type parameter as defined by RFC 2426, such as "type=cell" or + "language=en". + </tp:docstring> + </tp:simple-type> + <property name="ContactInfoFlags" type="u" access="read" tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags"> <tp:docstring> - An integer representing the bitwise-OR of flags on this channel. This - property should be constant over the lifetime of a connection. + An integer representing the bitwise-OR of flags on this connection. + This property should be constant over the lifetime of a connection. </tp:docstring> </property> @@ -280,11 +321,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this Connection.</tp:docstring> - <tp:member type="s" name="Name"> + <tp:member type="s" name="Name" tp:type="VCard_Field"> <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring> </tp:member> - <tp:member type="as" name="Parameters"> + <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]"> <tp:docstring>The set of vCard type parameters which may be set on this field. If this list is empty and the Contact_Info_Field_Flag_Parameters_Mandatory diff --git a/qt4/spec/Connection_Interface_Presence.xml b/qt4/spec/Connection_Interface_Presence.xml index 6d9b24a18..8a344d416 100644 --- a/qt4/spec/Connection_Interface_Presence.xml +++ b/qt4/spec/Connection_Interface_Presence.xml @@ -26,8 +26,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> - <!-- We hope to simplify these eventually --> <tp:mapping name="Multiple_Status_Map"> <tp:docstring>Mapping used in <tp:type>Last_Activity_And_Statuses</tp:type> and passed to @@ -249,17 +249,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ map optional parameter names to their variant-boxed values </tp:docstring> </arg> - <tp:docstring> - Request that the user's presence be changed to the given statuses and - desired parameters. Changes will be reflected by - <tp:member-ref>PresenceUpdate</tp:member-ref> - signals being emitted. On certain protocols, this method may be - called on a newly-created connection which is still in the - DISCONNECTED state, and will sign on with the requested status. - If the requested status is not available after signing on, - NotAvailable will be returned and the connection will remain - offline, or if the protocol does not support signing on with - a certain status, Disconnected will be returned. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the user's presence be changed to the given statuses + and desired parameters. Changes will be reflected by + <tp:member-ref>PresenceUpdate</tp:member-ref> + signals being emitted.</p> + + <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.</p> + + <tp:rationale> + <p>The same rationale as for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref> + applies.</p> + </tp:rationale> + + <p>On certain protocols, this method may be + called on a newly-created connection which is still in the + DISCONNECTED state, and will sign on with the requested status. + If the requested status is not available after signing on, + NotAvailable will be returned and the connection will remain + offline, or if the protocol does not support signing on with + a certain status, Disconnected will be returned.</p> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -269,12 +281,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> </tp:possible-errors> </method> + + <tp:deprecated version="0.17.21">Client implementations + SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + instead.</tp:deprecated> + <tp:changed version="0.17.23">Connection managers implementing + Presence MUST implement SimplePresence too.</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface will become deprecated in future versions. New - client implementations MAY use <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> - instead; new connection managers SHOULD implement both Presence and - SimplePresence.</p> <p>This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts. @@ -287,28 +302,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ per connection, and a list of them can be obtained with the <tp:member-ref>GetStatuses</tp:member-ref> method.</p> + <p>(The SimplePresence interface which replaces this one restricts + presences to one status per contact, with an optional message, which is + in practice all that was implemented on this interface.)</p> + <p>Each status has an arbitrary string identifier which should have an agreed meaning between the connection manager and any client which is expected to - make use of it. The following well-known values (in common with those in - Galago) should be used where possible to allow clients to identify common - choices:</p> - - <ul> - <li>available (corresponding to Connection_Presence_Type_Available)</li> - <li>away (corresponding to Connection_Presence_Type_Away)</li> - <li>brb (Be Right Back) (corresponding to - Connection_Presence_Type_Away, but more specific)</li> - <li>busy (corresponding to Connection_Presence_Type_Busy)</li> - <li>dnd (Do Not Disturb) (corresponding to - Connection_Presence_Type_Busy, but more specific)</li> - <li>xa (Extended Away) (corresponding to - Connection_Presence_Type_Extended_Away)</li> - <li>hidden (aka Invisible) (corresponding to - Connection_Presence_Type_Hidden)</li> - <li>offline (corresponding to Connection_Presence_Type_Offline)</li> - <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li> - <li>error (corresponding to Connection_Presence_Type_Error)</li> - </ul> + make use of it. The well-known values defined by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + interface SHOULD be used where possible</p> <p>As well as these well-known status identifiers, every status also has a numerical type value chosen from @@ -339,125 +341,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ intermittently to update any display of presence information.</p> </tp:docstring> - <tp:enum name="Connection_Presence_Type" type="u"> - <tp:enumvalue suffix="Unset" value="0"> - <tp:docstring> - An invalid presence type used as a null value. This value MUST NOT - appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>, - or in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref> - property of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> - interface. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Offline" value="1"> - <tp:docstring> - Offline - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Available" value="2"> - <tp:docstring> - Available - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Away" value="3"> - <tp:docstring> - Away - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Extended_Away" value="4"> - <tp:docstring> - Away for an extended time - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Hidden" value="5"> - <tp:docstring> - Hidden (invisible) - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Busy" value="6"> - <tp:added version="0.17.0"/> - <tp:docstring> - Busy, Do Not Disturb. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Unknown" value="7"> - <tp:added version="0.17.8"/> - <tp:docstring> - Unknown, unable to determine presence for this contact, for example - if the protocol only allows presence of subscribed contacts. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Error" value="8"> - <tp:added version="0.17.8"/> - <tp:docstring> - Error, an error occurred while trying to determine presence. The - message, if set, is an error from the server. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Rich_Presence_Access_Control_Type" type="u"> - <tp:docstring> - A type of access control for Rich_Presence_Access_Control. - For most types, the exact access control is given by an associated - variant. - - <tp:rationale> - These are the access control types from XMPP publish/subscribe - (XEP-0060). - </tp:rationale> - </tp:docstring> - - <tp:enumvalue suffix="Whitelist" value="0"> - <tp:docstring> - The associated variant is a list of contacts (signature 'au', - Contact_Handle[]) who can see the extended presence information. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Publish_List" value="1"> - <tp:docstring> - All contacts in the user's 'publish' contact list can see the - extended presence information. The associated variant is ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Group" value="2"> - <tp:docstring> - The associated variant is a handle of type Group (signature 'u', - Group_Handle) representing a group of contacts who can see the - extended presence information. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="3"> - <tp:docstring> - Anyone with access to the service can see the extended presence - information. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Rich_Presence_Access_Control"> - <tp:docstring> - An access control mode for extended presence items like geolocation. - This type isn't actually used by the core Presence interface, but - it's included here so it can be referenced by other specifications. - </tp:docstring> - - <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type"> - <tp:docstring> - The type of access control to apply. - </tp:docstring> - </tp:member> - <tp:member name="Detail" type="v"> - <tp:docstring> - Any additional information required by the Type. The required - type and semantics are defined for each - Rich_Presence_Access_Control_Type. - </tp:docstring> - </tp:member> - </tp:struct> - </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Requests.xml b/qt4/spec/Connection_Interface_Requests.xml index 3e4726219..b63aa5b08 100644 --- a/qt4/spec/Connection_Interface_Requests.xml +++ b/qt4/spec/Connection_Interface_Requests.xml @@ -217,6 +217,12 @@ contact is using a client that lacks a particular feature. </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The requested channel cannot be created, but in @@ -356,6 +362,12 @@ contact is using a client that lacks a particular feature. </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> The requested channel cannot be created, but in diff --git a/qt4/spec/Connection_Interface_Simple_Presence.xml b/qt4/spec/Connection_Interface_Simple_Presence.xml index 16f33865f..84460505f 100644 --- a/qt4/spec/Connection_Interface_Simple_Presence.xml +++ b/qt4/spec/Connection_Interface_Simple_Presence.xml @@ -151,6 +151,16 @@ the choices would be appropriate, and incorrect information about the user would be conveyed.</p> </tp:rationale> + + <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.</p> + + <tp:rationale> + <p>To go offline, call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref> + instead. The "error" and "unknown" statuses make no sense.</p> + </tp:rationale> </tp:docstring> </arg> <arg direction="in" name="Status_Message" type="s"> @@ -232,9 +242,9 @@ <property name="Statuses" tp:name-for-bindings="Statuses" access="read" type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary where the keys are the presence statuses that the user - can set on themselves for this connection, and the values are the - corresponding presence types.</p> + <p>A dictionary where the keys are the presence statuses that are + available on this connection, and the values are the corresponding + presence types.</p> <p>While the connection is in the DISCONNECTED state, it contains the set of presence statuses allowed to be set before connecting. @@ -280,6 +290,128 @@ </tp:docstring> </signal> + <tp:enum name="Connection_Presence_Type" type="u"> + <tp:enumvalue suffix="Unset" value="0"> + <tp:docstring> + An invalid presence type used as a null value. This value MUST NOT + appear in the <tp:member-ref>Statuses</tp:member-ref> property, + or in the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Presence">GetStatuses</tp:dbus-ref> + on the deprecated <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref> + interface. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring> + Offline + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Available" value="2"> + <tp:docstring> + Available + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Away" value="3"> + <tp:docstring> + Away + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Extended_Away" value="4"> + <tp:docstring> + Away for an extended time + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Hidden" value="5"> + <tp:docstring> + Hidden (invisible) + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Busy" value="6"> + <tp:added version="0.17.0"/> + <tp:docstring> + Busy, Do Not Disturb. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Unknown" value="7"> + <tp:added version="0.17.8"/> + <tp:docstring> + Unknown, unable to determine presence for this contact, for example + if the protocol only allows presence of subscribed contacts. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Error" value="8"> + <tp:added version="0.17.8"/> + <tp:docstring> + Error, an error occurred while trying to determine presence. The + message, if set, is an error from the server. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Rich_Presence_Access_Control_Type" type="u" + array-name="Rich_Presence_Access_Control_Type_List"> + <tp:docstring> + A type of access control for Rich_Presence_Access_Control. + For most types, the exact access control is given by an associated + variant. + + <tp:rationale> + These are the access control types from XMPP publish/subscribe + (XEP-0060). + </tp:rationale> + </tp:docstring> + + <tp:enumvalue suffix="Whitelist" value="0"> + <tp:docstring> + The associated variant is a list of contacts (signature 'au', + Contact_Handle[]) who can see the extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Publish_List" value="1"> + <tp:docstring> + All contacts in the user's 'publish' contact list can see the + extended presence information. The associated variant is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Group" value="2"> + <tp:docstring> + The associated variant is a handle of type Group (signature 'u', + Group_Handle) representing a group of contacts who can see the + extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="3"> + <tp:docstring> + Anyone with access to the service can see the extended presence + information. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Rich_Presence_Access_Control"> + <tp:docstring> + An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence interfaces + such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Location.DRAFT</tp:dbus-ref>. + </tp:docstring> + + <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type"> + <tp:docstring> + The type of access control to apply. + </tp:docstring> + </tp:member> + <tp:member name="Detail" type="v"> + <tp:docstring> + Any additional information required by the Type. The required + type and semantics are defined for each + <tp:type>Rich_Presence_Access_Control_Type</tp:type>. + </tp:docstring> + </tp:member> + </tp:struct> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts.</p> diff --git a/qt4/spec/Connection_Manager.xml b/qt4/spec/Connection_Manager.xml index 46b56ac7a..ad8f058ec 100644 --- a/qt4/spec/Connection_Manager.xml +++ b/qt4/spec/Connection_Manager.xml @@ -55,7 +55,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ characters were not specified</tp:changed> </tp:simple-type> - <tp:simple-type name="Protocol" type="s"> + <tp:simple-type name="Protocol" type="s" array-name="Protocol_List"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An instant messaging protocol. It must consist only of ASCII letters, digits and hyphen/minus signs (U+002D "-"), and must start diff --git a/qt4/spec/Media_Session_Handler.xml b/qt4/spec/Media_Session_Handler.xml index a6cf5192f..70aa75073 100644 --- a/qt4/spec/Media_Session_Handler.xml +++ b/qt4/spec/Media_Session_Handler.xml @@ -23,19 +23,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error"/> <arg direction="in" name="Message" type="s"/> + <tp:deprecated version="0.13.4"> + Use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media">StreamHandler.Error</tp:dbus-ref> + on each StreamHandler object instead. + </tp:deprecated> <tp:docstring> - THIS METHOD IS DEPRECATED AND SHOULD NOT BE USED. Instead the Error - function should be used on the relevant MediaStreamHandler objects. Informs the connection manager that an error occured in this session. If used, the connection manager must terminate the session and all of - the streams within it, and may also emit a StreamError signal on the - channel for each stream within the session. + the streams within it, and may also emit a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">StreamError</tp:dbus-ref> + signal on the channel for each stream within the session. </tp:docstring> </method> <signal name="NewStreamHandler" tp:name-for-bindings="New_Stream_Handler"> <arg name="Stream_Handler" type="o"> <tp:docstring> - An object path to a new MediaStreamHandler + The path of a new object implementing the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media">StreamHandler</tp:dbus-ref> + interface. </tp:docstring> </arg> <arg name="ID" type="u"> @@ -45,14 +51,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <arg name="Media_Type" type="u" tp:type="Media_Stream_Type"> <tp:docstring> - Enum for type of media that this stream should handle - (a value from MediaStreamType) + Type of media that this stream should handle </tp:docstring> </arg> <arg name="Direction" type="u" tp:type="Media_Stream_Direction"> <tp:docstring> - Enum for direction of this stream (a value from - MediaStreamDirection) + Direction of this stream </tp:docstring> </arg> <tp:docstring> @@ -64,7 +68,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Inform the connection manager that a client is ready to handle this session handler (i.e. that it has connected to the - NewStreamHandler signal and done any other necessary setup). + <tp:member-ref>NewStreamHandler</tp:member-ref> signal and done any + other necessary setup). </tp:docstring> </method> <tp:docstring> diff --git a/qt4/spec/Media_Stream_Handler.xml b/qt4/spec/Media_Stream_Handler.xml index cb7c79326..d335e3853 100644 --- a/qt4/spec/Media_Stream_Handler.xml +++ b/qt4/spec/Media_Stream_Handler.xml @@ -70,6 +70,150 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:member> </tp:struct> + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" + type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The IP addresses of possible STUN servers to use for NAT traversal, as + dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. + This property cannot change once the stream has been created, so there + is no change notification. The IP addresses MUST NOT be given as DNS + hostnames. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + </tp:rationale> + </tp:docstring> + </property> + + <property name="CreatedLocally" tp:name-for-bindings="Created_Locally" + type="b" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + True if we were the creator of this stream, false otherwise. + <tp:rationale> + This information is needed for some nat traversal mechanisms, such + as ICE-UDP, where the creator gets the role of the controlling agent. + </tp:rationale> + </tp:docstring> + </property> + + <property name="NATTraversal" tp:name-for-bindings="NAT_Traversal" + type="s" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The transport (NAT traversal technique) to be used for this + stream. Well-known values include:</p> + + <dl> + <dt>none</dt> + <dd>Raw UDP, with or without STUN, should be used. If the + <tp:member-ref>STUNServers</tp:member-ref> property is non-empty, + STUN SHOULD be used.</dd> + + <dt>stun</dt> + <dd>A deprecated synonym for 'none'.</dd> + + <dt>gtalk-p2p</dt> + <dd>Google Talk peer-to-peer connectivity establishment should be + used, as implemented in libjingle 0.3.</dd> + + <dt>ice-udp</dt> + <dd>Interactive Connectivity Establishment should be used, + as defined by the IETF MMUSIC working group.</dd> + + <dt>wlm-8.5</dt> + <dd>The transport used by Windows Live Messenger 8.5 or later, + which resembles ICE draft 6, should be used.</dd> + + <dt>wlm-2009</dt> + <dd>The transport used by Windows Live Messenger 2009 or later, + which resembles ICE draft 19, should be used.</dd> + </dl> + + <p>This property cannot change once the stream has been created, so + there is no change notification.</p> + </tp:docstring> + </property> + + <property name="RelayInfo" type="aa{sv}" access="read" + tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:</p> + + <dl> + <dt><code>ip</code> - s</dt> + <dd>The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + </tp:rationale> + </dd> + + <dt><code>type</code> - s</dt> + <dd> + <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this + key is omitted), <code>tcp</code> for TCP, or + <code>tls</code>.</p> + + <p>The precise meaning of this key depends on the + <tp:member-ref>NATTraversal</tp:member-ref> property: if + NATTraversal is <code>ice-udp</code>, <code>tls</code> means + TLS over TCP as referenced by ICE draft 19, and if + NATTraversal is <code>gtalk-p2p</code>, <code>tls</code> means + a fake SSL session over TCP as implemented by libjingle.</p> + </dd> + + <dt><code>port</code> - q</dt> + <dd>The UDP or TCP port of the relay server as an ASCII unsigned + integer</dd> + + <dt><code>username</code> - s</dt> + <dd>The username to use</dd> + + <dt><code>password</code> - s</dt> + <dd>The password to use</dd> + + <dt><code>component</code> - u</dt> + <dd>The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + <tp:rationale> + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + </tp:rationale> + </dd> + </dl> + + <tp:rationale> + <p>An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.</p> + </tp:rationale> + + <p>The type of relay server that this represents depends on + the value of the <tp:member-ref>NATTraversal</tp:member-ref> + property. If NATTraversal is ice-udp, this is a TURN server; + if NATTraversal is gtalk-p2p, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.</p> + + <p>If relaying is not possible for this stream, the list is empty.</p> + + <p>This property cannot change once the stream has been created, so + there is no change notification.</p> + </tp:docstring> + </property> + <signal name="AddRemoteCandidate" tp:name-for-bindings="Add_Remote_Candidate"> <arg name="Candidate_ID" type="s"> @@ -246,7 +390,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ String identifier for remote candidate to drop </tp:docstring> </arg> - <tp:deprecated> + <tp:deprecated version="0.17.18"> There is no case where you want to release candidates (except for an ICE reset, and there you'd want to replace then all, using <tp:member-ref>SetRemoteCandidateList</tp:member-ref>). diff --git a/qt4/spec/Properties_Interface.xml b/qt4/spec/Properties_Interface.xml index 91423c108..aaa46029e 100644 --- a/qt4/spec/Properties_Interface.xml +++ b/qt4/spec/Properties_Interface.xml @@ -39,7 +39,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member type="u" name="New_Flags"/> </tp:struct> - <tp:simple-type name="Property_ID" type="u"> + <tp:simple-type name="Property_ID" type="u" array-name="Property_ID_List"> <tp:docstring> An unsigned integer used to represent a Telepathy property. </tp:docstring> diff --git a/qt4/spec/all.xml b/qt4/spec/all.xml index 7745d549c..93ce92535 100644 --- a/qt4/spec/all.xml +++ b/qt4/spec/all.xml @@ -3,11 +3,11 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.19</tp:version> +<tp:version>0.17.23</tp:version> -<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: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 @@ -25,69 +25,145 @@ 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> -<xi:include href="Connection_Manager.xml"/> -<xi:include href="Connection.xml"/> -<xi:include href="Connection_Interface_Aliasing.xml"/> -<xi:include href="Connection_Interface_Avatars.xml"/> -<xi:include href="Connection_Interface_Capabilities.xml"/> -<xi:include href="Connection_Interface_Contact_Capabilities.xml"/> -<xi:include href="Connection_Interface_Contact_Info.xml"/> -<xi:include href="Connection_Interface_Contacts.xml"/> -<xi:include href="Connection_Interface_Location.xml"/> -<xi:include href="Connection_Interface_Presence.xml"/> -<xi:include href="Connection_Interface_Renaming.xml"/> -<xi:include href="Connection_Interface_Requests.xml"/> -<xi:include href="Connection_Interface_Simple_Presence.xml"/> - -<xi:include href="Channel_Bundle.xml"/> - -<xi:include href="Channel.xml"/> -<xi:include href="Channel_Future.xml"/> -<xi:include href="Channel_Type_Contact_List.xml"/> -<xi:include href="Channel_Type_Streamed_Media.xml"/> -<xi:include href="Channel_Type_Streamed_Media_Future.xml"/> -<xi:include href="Channel_Type_Room_List.xml"/> -<xi:include href="Channel_Type_Text.xml"/> -<xi:include href="Channel_Type_Tubes.xml"/> -<xi:include href="Channel_Type_Stream_Tube.xml"/> -<xi:include href="Channel_Type_DBus_Tube.xml"/> -<xi:include href="Channel_Type_File_Transfer.xml"/> - -<xi:include href="Channel_Interface_Call_Merging.xml"/> -<xi:include href="Channel_Interface_Call_State.xml"/> -<xi:include href="Channel_Interface_Chat_State.xml"/> -<xi:include href="Channel_Interface_Destroyable.xml"/> -<xi:include href="Channel_Interface_DTMF.xml"/> -<xi:include href="Channel_Interface_Group.xml"/> -<xi:include href="Channel_Interface_Hold.xml"/> -<xi:include href="Channel_Interface_HTML.xml"/> -<xi:include href="Channel_Interface_Password.xml"/> -<xi:include href="Channel_Interface_Media_Signalling.xml"/> -<xi:include href="Channel_Interface_Media_Signalling_Future.xml"/> -<xi:include href="Channel_Interface_Messages.xml"/> -<xi:include href="Channel_Interface_Tube.xml"/> - -<xi:include href="Media_Session_Handler.xml"/> -<xi:include href="Media_Stream_Handler.xml"/> +<tp:section name="Connection Managers"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Connection Manager is a factory for connections. + </p> + </tp:docstring> + <xi:include href="Connection_Manager.xml"/> + + <tp:section name="Connection Object"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Connections represent active protocol sessions. + </p> + </tp:docstring> + <xi:include href="Connection.xml"/> + <xi:include href="Connection_Interface_Aliasing.xml"/> + <xi:include href="Connection_Interface_Avatars.xml"/> + <xi:include href="Connection_Interface_Capabilities.xml"/> + <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> + <xi:include href="Connection_Interface_Contact_Info.xml"/> + <xi:include href="Connection_Interface_Contacts.xml"/> + <xi:include href="Connection_Interface_Location.xml"/> + <xi:include href="Connection_Interface_Presence.xml"/> + <xi:include href="Connection_Interface_Renaming.xml"/> + <xi:include href="Connection_Interface_Requests.xml"/> + <xi:include href="Connection_Interface_Simple_Presence.xml"/> + </tp:section> + + <xi:include href="Channel_Bundle.xml"/> + + <tp:section name="Channel Object"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Channel is used by Telepathy to exchange data between local + applications and remote servers. A given connection will have many + channels, each one represented by a D-Bus object. + </p> + <p> + Each Channel has a type, represented by a D-Bus interface, and may + implement one or more additional interfaces from the list of channel + interfaces below. + </p> + </tp:docstring> + <xi:include href="Channel.xml"/> + <xi:include href="Channel_Future.xml"/> + + <tp:section name="Channel Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Each Channel implements one of the following types: + </p> + </tp:docstring> + <xi:include href="Channel_Type_Contact_List.xml"/> + <xi:include href="Channel_Type_Streamed_Media.xml"/> + <xi:include href="Channel_Type_Streamed_Media_Future.xml"/> + <xi:include href="Channel_Type_Room_List.xml"/> + <xi:include href="Channel_Type_Text.xml"/> + <xi:include href="Channel_Type_Tubes.xml"/> + <xi:include href="Channel_Type_Stream_Tube.xml"/> + <xi:include href="Channel_Type_DBus_Tube.xml"/> + <xi:include href="Channel_Type_File_Transfer.xml"/> + <xi:include href="Channel_Type_Contact_Search.xml"/> + </tp:section> + + <tp:section name="Channel Interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Channel may also implement one or more of the following interfaces, + depending on its type: + </p> + </tp:docstring> + <xi:include href="Channel_Interface_Call_Merging.xml"/> + <xi:include href="Channel_Interface_Call_State.xml"/> + <xi:include href="Channel_Interface_Chat_State.xml"/> + <xi:include href="Channel_Interface_Destroyable.xml"/> + <xi:include href="Channel_Interface_DTMF.xml"/> + <xi:include href="Channel_Interface_Group.xml"/> + <xi:include href="Channel_Interface_Hold.xml"/> + <xi:include href="Channel_Interface_HTML.xml"/> + <xi:include href="Channel_Interface_Password.xml"/> + <xi:include href="Channel_Interface_Media_Signalling.xml"/> + <xi:include href="Channel_Interface_Media_Signalling_Future.xml"/> + <xi:include href="Channel_Interface_Messages.xml"/> + <xi:include href="Channel_Interface_Tube.xml"/> + </tp:section> + </tp:section> + + <tp:section name="Media"> + <xi:include href="Media_Session_Handler.xml"/> + <xi:include href="Media_Stream_Handler.xml"/> + </tp:section> +</tp:section> + +<tp:section name="The Account Manager"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The Account Manager is a desktop service that provides account configuration + and can manage the connection managers. In general, clients will use the + account manager to find out about instant messaging accounts and their + associated connections. + </p> + </tp:docstring> + <xi:include href="Account_Manager.xml"/> + <xi:include href="Account.xml"/> + <xi:include href="Account_Interface_Avatar.xml"/> +</tp:section> + +<tp:section name="The Channel Dispatcher"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The Channel Dispatcher is a desktop service whose purpose is to dispatch + incoming Telepathy Channels to the appropriate client (e.g. incoming text + chat, file transfer, tubes, etc.). + </p> + </tp:docstring> + <xi:include href="Channel_Dispatcher.xml"/> + <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> + <xi:include href="Channel_Dispatch_Operation.xml"/> + <xi:include href="Channel_Request.xml"/> +</tp:section> + +<tp:section name="Clients"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Clients should implement one or more of these interfaces to be able to + handle channels coming in from the Channel Dispatcher. + </p> + </tp:docstring> + <xi:include href="Client.xml"/> + <xi:include href="Client_Observer.xml"/> + <xi:include href="Client_Approver.xml"/> + <xi:include href="Client_Handler.xml"/> + <xi:include href="Client_Interface_Requests.xml"/> + + <xi:include href="Channel_Handler.xml"/> +</tp:section> <xi:include href="Properties_Interface.xml"/> -<xi:include href="Account_Manager.xml"/> -<xi:include href="Account.xml"/> -<xi:include href="Account_Interface_Avatar.xml"/> - -<xi:include href="Channel_Dispatcher.xml"/> -<xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> -<xi:include href="Channel_Dispatch_Operation.xml"/> -<xi:include href="Channel_Request.xml"/> - -<xi:include href="Client.xml"/> -<xi:include href="Client_Observer.xml"/> -<xi:include href="Client_Approver.xml"/> -<xi:include href="Client_Handler.xml"/> - -<xi:include href="Channel_Handler.xml"/> - <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> diff --git a/qt4/spec/errors.xml b/qt4/spec/errors.xml index 0a2d7d2d3..f82c532e4 100644 --- a/qt4/spec/errors.xml +++ b/qt4/spec/errors.xml @@ -1,8 +1,5 @@ <?xml version="1.0" ?> <tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> - <!-- Don't re-order these errors until fd.o #17588 is fixed, or you will - break telepathy-glib's ABI. - --> <tp:error name="Network Error"> <tp:docstring> Raised when there is an error reading from or writing to the network. @@ -296,8 +293,22 @@ </tp:docstring> </tp:error> - <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> + <tp:error name="Terminated"> + <tp:docstring> + Raised when a channel is terminated for an unspecified reason. In + particular, this error SHOULD be used whenever normal termination of + a 1-1 StreamedMedia call by the remote user is represented as a D-Bus + error name. + + <tp:rationale> + This corresponds to None in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-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 diff --git a/qt4/spec/generic-types.xml b/qt4/spec/generic-types.xml index fba6a9f44..d4dce1552 100644 --- a/qt4/spec/generic-types.xml +++ b/qt4/spec/generic-types.xml @@ -17,23 +17,27 @@ interfaces.</tp:rationale> </tp:simple-type> - <tp:simple-type name="DBus_Bus_Name" type="s"> + <tp:simple-type name="DBus_Bus_Name" type="s" + array-name="DBus_Bus_Name_List"> <tp:docstring>A string representing a D-Bus bus name - either a well-known name like "org.freedesktop.Telepathy.MissionControl" or a unique name like ":1.123"</tp:docstring> </tp:simple-type> - <tp:simple-type name="DBus_Well_Known_Name" type="s"> + <tp:simple-type name="DBus_Well_Known_Name" type="s" + array-name="DBus_Well_Known_Name_List"> <tp:docstring>A string representing a D-Bus well-known name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring> </tp:simple-type> - <tp:simple-type name="DBus_Unique_Name" type="s"> + <tp:simple-type name="DBus_Unique_Name" type="s" + array-name="DBus_Unique_Name_List"> <tp:docstring>A string representing a D-Bus unique name, such as ":1.123"</tp:docstring> </tp:simple-type> - <tp:simple-type name="DBus_Interface" type="s"> + <tp:simple-type name="DBus_Interface" type="s" + array-name="DBus_Interface_List"> <tp:docstring>An ASCII string representing a D-Bus interface - two or more elements separated by dots, where each element is a non-empty string of ASCII letters, digits and underscores, not starting with @@ -60,7 +64,8 @@ characters. For example, "Ping".</tp:docstring> </tp:simple-type> - <tp:simple-type name="DBus_Qualified_Member" type="s"> + <tp:simple-type name="DBus_Qualified_Member" type="s" + array-name="DBus_Qualified_Member_List"> <tp:docstring>A string representing the full name of a D-Bus method, signal or property, consisting of a DBus_Interface, followed by a dot, followed by a DBus_Member. For example, @@ -90,11 +95,74 @@ <tp:member type="v" name="Value"/> </tp:mapping> - <tp:mapping name="String_String_Map"> + <tp:mapping name="String_String_Map" array-name="String_String_Map_List"> <tp:docstring>A mapping from strings to strings representing extra key-value pairs.</tp:docstring> <tp:member type="s" name="Key"/> <tp:member type="s" name="Value"/> </tp:mapping> + <tp:struct name="Socket_Address_IP" array-name="Socket_Address_IP_List"> + <tp:docstring>An IP address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>Either a dotted-quad IPv4 address literal as for + <tp:type>Socket_Address_IPv4</tp:type>, or an RFC2373 IPv6 address + as for <tp:type>Socket_Address_IPv6</tp:type>. + </tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv4"> + <tp:docstring>An IPv4 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv6"> + <tp:docstring>An IPv6 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv4"> + <tp:docstring>An IPv4 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv6"> + <tp:docstring>An IPv6 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + </tp:generic-types> |