diff options
| author | Jonny Lamb <jonny.lamb@collabora.co.uk> | 2011-11-30 18:11:39 +0000 |
|---|---|---|
| committer | Jonny Lamb <jonny.lamb@collabora.co.uk> | 2011-11-30 18:11:39 +0000 |
| commit | c2b6c3cf9072a9d07430c819aa9bfc25aa0140e2 (patch) | |
| tree | 9df04841265b18883ee97dcb8c1996504c54e08f | |
| parent | 2a5538d245f503cf8e7051736847356c8f11458b (diff) | |
qt4: (semi-)remove the spec directory
Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
132 files changed, 88 insertions, 34575 deletions
diff --git a/qt4/TelepathyQt4/account-manager.xml b/qt4/TelepathyQt4/account-manager.xml index 278f4276f..a05abbfa1 100644 --- a/qt4/TelepathyQt4/account-manager.xml +++ b/qt4/TelepathyQt4/account-manager.xml @@ -4,6 +4,6 @@ <tp:title>Account Manager interfaces</tp:title> -<xi:include href="../spec/Account_Manager.xml"/> +<xi:include href="../../spec/spec/Account_Manager.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/account.xml b/qt4/TelepathyQt4/account.xml index 1cc5b2a15..35eddc601 100644 --- a/qt4/TelepathyQt4/account.xml +++ b/qt4/TelepathyQt4/account.xml @@ -4,10 +4,10 @@ <tp:title>Account interfaces</tp:title> -<xi:include href="../spec/Account.xml"/> +<xi:include href="../../spec/spec/Account.xml"/> -<xi:include href="../spec/Account_Interface_Addressing.xml"/> -<xi:include href="../spec/Account_Interface_Avatar.xml"/> -<xi:include href="../spec/Account_Interface_Storage.xml"/> +<xi:include href="../../spec/spec/Account_Interface_Addressing.xml"/> +<xi:include href="../../spec/spec/Account_Interface_Avatar.xml"/> +<xi:include href="../../spec/spec/Account_Interface_Storage.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/channel-dispatch-operation.xml b/qt4/TelepathyQt4/channel-dispatch-operation.xml index d7a6cdda1..6c3ff075d 100644 --- a/qt4/TelepathyQt4/channel-dispatch-operation.xml +++ b/qt4/TelepathyQt4/channel-dispatch-operation.xml @@ -4,6 +4,6 @@ <tp:title>Channel Dispatch Operation interface</tp:title> -<xi:include href="../spec/Channel_Dispatch_Operation.xml"/> +<xi:include href="../../spec/spec/Channel_Dispatch_Operation.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/channel-dispatcher.xml b/qt4/TelepathyQt4/channel-dispatcher.xml index a1588a426..312951c94 100644 --- a/qt4/TelepathyQt4/channel-dispatcher.xml +++ b/qt4/TelepathyQt4/channel-dispatcher.xml @@ -4,6 +4,6 @@ <tp:title>Channel Dispatcher interface</tp:title> -<xi:include href="../spec/Channel_Dispatcher.xml"/> +<xi:include href="../../spec/spec/Channel_Dispatcher.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/channel-request.xml b/qt4/TelepathyQt4/channel-request.xml index 92fc88172..f4809036a 100644 --- a/qt4/TelepathyQt4/channel-request.xml +++ b/qt4/TelepathyQt4/channel-request.xml @@ -4,6 +4,6 @@ <tp:title>Channel Request interface</tp:title> -<xi:include href="../spec/Channel_Request.xml"/> +<xi:include href="../../spec/spec/Channel_Request.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/channel.xml b/qt4/TelepathyQt4/channel.xml index c850462e2..bfe20bcc4 100644 --- a/qt4/TelepathyQt4/channel.xml +++ b/qt4/TelepathyQt4/channel.xml @@ -4,34 +4,34 @@ <tp:title>Channel interfaces</tp:title> -<xi:include href="../spec/Channel.xml"/> +<xi:include href="../../spec/spec/Channel.xml"/> -<xi:include href="../spec/Channel_Type_Contact_List.xml"/> -<xi:include href="../spec/Channel_Type_Contact_Search.xml"/> -<xi:include href="../spec/Channel_Type_DBus_Tube.xml"/> -<xi:include href="../spec/Channel_Type_File_Transfer.xml"/> -<xi:include href="../spec/Channel_Type_Room_List.xml"/> -<xi:include href="../spec/Channel_Type_Server_Authentication.xml"/> -<xi:include href="../spec/Channel_Type_Server_TLS_Connection.xml"/> -<xi:include href="../spec/Channel_Type_Streamed_Media.xml"/> -<xi:include href="../spec/Channel_Type_Stream_Tube.xml"/> -<xi:include href="../spec/Channel_Type_Text.xml"/> -<xi:include href="../spec/Channel_Type_Tubes.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Contact_List.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Contact_Search.xml"/> +<xi:include href="../../spec/spec/Channel_Type_DBus_Tube.xml"/> +<xi:include href="../../spec/spec/Channel_Type_File_Transfer.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Room_List.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Server_Authentication.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Server_TLS_Connection.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Streamed_Media.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Stream_Tube.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Text.xml"/> +<xi:include href="../../spec/spec/Channel_Type_Tubes.xml"/> -<xi:include href="../spec/Channel_Interface_Anonymity.xml"/> -<xi:include href="../spec/Channel_Interface_Call_State.xml"/> -<xi:include href="../spec/Channel_Interface_Chat_State.xml"/> -<xi:include href="../spec/Channel_Interface_Conference.xml"/> -<xi:include href="../spec/Channel_Interface_Destroyable.xml"/> -<xi:include href="../spec/Channel_Interface_DTMF.xml"/> -<xi:include href="../spec/Channel_Interface_Group.xml"/> -<xi:include href="../spec/Channel_Interface_Hold.xml"/> -<xi:include href="../spec/Channel_Interface_Media_Signalling.xml"/> -<xi:include href="../spec/Channel_Interface_Messages.xml"/> -<xi:include href="../spec/Channel_Interface_Password.xml"/> -<xi:include href="../spec/Channel_Interface_SASL_Authentication.xml"/> -<xi:include href="../spec/Channel_Interface_Securable.xml"/> -<xi:include href="../spec/Channel_Interface_Service_Point.xml"/> -<xi:include href="../spec/Channel_Interface_Tube.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Anonymity.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Call_State.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Chat_State.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Conference.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Destroyable.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_DTMF.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Group.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Hold.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Media_Signalling.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Messages.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Password.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_SASL_Authentication.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Securable.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Service_Point.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Tube.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/client.xml b/qt4/TelepathyQt4/client.xml index d4d0f6de7..e76946543 100644 --- a/qt4/TelepathyQt4/client.xml +++ b/qt4/TelepathyQt4/client.xml @@ -4,11 +4,11 @@ <tp:title>Client interfaces</tp:title> -<xi:include href="../spec/Client.xml"/> -<xi:include href="../spec/Client_Observer.xml"/> -<xi:include href="../spec/Client_Approver.xml"/> -<xi:include href="../spec/Client_Handler.xml"/> +<xi:include href="../../spec/spec/Client.xml"/> +<xi:include href="../../spec/spec/Client_Observer.xml"/> +<xi:include href="../../spec/spec/Client_Approver.xml"/> +<xi:include href="../../spec/spec/Client_Handler.xml"/> -<xi:include href="../spec/Client_Interface_Requests.xml"/> +<xi:include href="../../spec/spec/Client_Interface_Requests.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/connection-manager.xml b/qt4/TelepathyQt4/connection-manager.xml index 597a78dfe..3faf5f361 100644 --- a/qt4/TelepathyQt4/connection-manager.xml +++ b/qt4/TelepathyQt4/connection-manager.xml @@ -4,9 +4,9 @@ <tp:title>Connection Manager interfaces</tp:title> -<xi:include href="../spec/Connection_Manager.xml"/> -<xi:include href="../spec/Protocol.xml"/> -<xi:include href="../spec/Protocol_Interface_Avatars.xml"/> -<xi:include href="../spec/Protocol_Interface_Presence.xml"/> +<xi:include href="../../spec/spec/Connection_Manager.xml"/> +<xi:include href="../../spec/spec/Protocol.xml"/> +<xi:include href="../../spec/spec/Protocol_Interface_Avatars.xml"/> +<xi:include href="../../spec/spec/Protocol_Interface_Presence.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/connection.xml b/qt4/TelepathyQt4/connection.xml index bf726f582..5b6a5080b 100644 --- a/qt4/TelepathyQt4/connection.xml +++ b/qt4/TelepathyQt4/connection.xml @@ -4,27 +4,27 @@ <tp:title>Connection interfaces</tp:title> -<xi:include href="../spec/Connection.xml"/> +<xi:include href="../../spec/spec/Connection.xml"/> -<xi:include href="../spec/Connection_Interface_Aliasing.xml"/> -<xi:include href="../spec/Connection_Interface_Anonymity.xml"/> -<xi:include href="../spec/Connection_Interface_Avatars.xml"/> -<xi:include href="../spec/Connection_Interface_Balance.xml"/> -<xi:include href="../spec/Connection_Interface_Capabilities.xml"/> -<xi:include href="../spec/Connection_Interface_Cellular.xml"/> -<xi:include href="../spec/Connection_Interface_Client_Types.xml"/> -<xi:include href="../spec/Connection_Interface_Contacts.xml"/> -<xi:include href="../spec/Connection_Interface_Contact_Blocking.xml"/> -<xi:include href="../spec/Connection_Interface_Contact_Capabilities.xml"/> -<xi:include href="../spec/Connection_Interface_Contact_Groups.xml"/> -<xi:include href="../spec/Connection_Interface_Contact_Info.xml"/> -<xi:include href="../spec/Connection_Interface_Contact_List.xml"/> -<xi:include href="../spec/Connection_Interface_Location.xml"/> -<xi:include href="../spec/Connection_Interface_Mail_Notification.xml"/> -<xi:include href="../spec/Connection_Interface_Power_Saving.xml"/> -<xi:include href="../spec/Connection_Interface_Presence.xml"/> -<xi:include href="../spec/Connection_Interface_Requests.xml"/> -<xi:include href="../spec/Connection_Interface_Service_Point.xml"/> -<xi:include href="../spec/Connection_Interface_Simple_Presence.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Aliasing.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Anonymity.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Avatars.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Balance.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Capabilities.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Cellular.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Client_Types.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contacts.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contact_Blocking.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contact_Capabilities.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contact_Groups.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contact_Info.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Contact_List.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Location.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Mail_Notification.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Power_Saving.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Presence.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Requests.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Service_Point.xml"/> +<xi:include href="../../spec/spec/Connection_Interface_Simple_Presence.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/future-channel-dispatcher.xml b/qt4/TelepathyQt4/future-channel-dispatcher.xml index 0e7f67c57..9d6ac7743 100644 --- a/qt4/TelepathyQt4/future-channel-dispatcher.xml +++ b/qt4/TelepathyQt4/future-channel-dispatcher.xml @@ -14,7 +14,7 @@ </tp:mapping> </tp:generic-types> -<xi:include href="../spec/generic-types.xml"/> -<xi:include href="../spec/errors.xml"/> +<xi:include href="../../spec/spec/generic-types.xml"/> +<xi:include href="../../spec/spec/errors.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/future-channel.xml b/qt4/TelepathyQt4/future-channel.xml index 6cf1e4948..d418133fb 100644 --- a/qt4/TelepathyQt4/future-channel.xml +++ b/qt4/TelepathyQt4/future-channel.xml @@ -4,10 +4,10 @@ <tp:title>Channel extensions from the future</tp:title> -<xi:include href="../spec/Channel_Interface_Mergeable_Conference.xml"/> -<xi:include href="../spec/Channel_Interface_Splittable.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Mergeable_Conference.xml"/> +<xi:include href="../../spec/spec/Channel_Interface_Splittable.xml"/> -<xi:include href="../spec/generic-types.xml"/> -<xi:include href="../spec/errors.xml"/> +<xi:include href="../../spec/spec/generic-types.xml"/> +<xi:include href="../../spec/spec/errors.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/future-interfaces.xml b/qt4/TelepathyQt4/future-interfaces.xml index 8cc5d753a..9c93aa39e 100644 --- a/qt4/TelepathyQt4/future-interfaces.xml +++ b/qt4/TelepathyQt4/future-interfaces.xml @@ -8,7 +8,7 @@ <xi:include href="future-channel-dispatcher.xml"/> <xi:include href="future-misc.xml"/> -<xi:include href="../spec/generic-types.xml"/> -<xi:include href="../spec/errors.xml"/> +<xi:include href="../../spec/spec/generic-types.xml"/> +<xi:include href="../../spec/spec/errors.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/media-session-handler.xml b/qt4/TelepathyQt4/media-session-handler.xml index 8b051cd26..6341e5cdf 100644 --- a/qt4/TelepathyQt4/media-session-handler.xml +++ b/qt4/TelepathyQt4/media-session-handler.xml @@ -4,6 +4,6 @@ <tp:title>Media session handler</tp:title> -<xi:include href="../spec/Media_Session_Handler.xml"/> +<xi:include href="../../spec/spec/Media_Session_Handler.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/media-stream-handler.xml b/qt4/TelepathyQt4/media-stream-handler.xml index 348d5a686..ebc03186d 100644 --- a/qt4/TelepathyQt4/media-stream-handler.xml +++ b/qt4/TelepathyQt4/media-stream-handler.xml @@ -4,6 +4,6 @@ <tp:title>Media stream handler</tp:title> -<xi:include href="../spec/Media_Stream_Handler.xml"/> +<xi:include href="../../spec/spec/Media_Stream_Handler.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/properties.xml b/qt4/TelepathyQt4/properties.xml index 2f59b89cf..f6822e95e 100644 --- a/qt4/TelepathyQt4/properties.xml +++ b/qt4/TelepathyQt4/properties.xml @@ -4,6 +4,6 @@ <tp:title>The Telepathy properties interface</tp:title> -<xi:include href="../spec/Properties_Interface.xml"/> +<xi:include href="../../spec/spec/Properties_Interface.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/stable-interfaces.xml b/qt4/TelepathyQt4/stable-interfaces.xml index 934f65d9c..85a53faec 100644 --- a/qt4/TelepathyQt4/stable-interfaces.xml +++ b/qt4/TelepathyQt4/stable-interfaces.xml @@ -20,7 +20,7 @@ <xi:include href="client.xml"/> <xi:include href="tls-certificate.xml"/> -<xi:include href="../spec/generic-types.xml"/> -<xi:include href="../spec/errors.xml"/> +<xi:include href="../../spec/spec/generic-types.xml"/> +<xi:include href="../../spec/spec/errors.xml"/> </tp:spec> diff --git a/qt4/TelepathyQt4/tls-certificate.xml b/qt4/TelepathyQt4/tls-certificate.xml index 0ba3d2d06..178ea5a79 100644 --- a/qt4/TelepathyQt4/tls-certificate.xml +++ b/qt4/TelepathyQt4/tls-certificate.xml @@ -4,6 +4,6 @@ <tp:title>TLSCertificate</tp:title> -<xi:include href="../spec/Authentication_TLS_Certificate.xml"/> +<xi:include href="../../spec/spec/Authentication_TLS_Certificate.xml"/> </tp:spec> diff --git a/qt4/spec/Account.xml b/qt4/spec/Account.xml deleted file mode 100644 index b706e279f..000000000 --- a/qt4/spec/Account.xml +++ /dev/null @@ -1,713 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account" - 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.Account"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An Account object encapsulates the necessary details to make a - Telepathy connection.</p> - - <p>Accounts are uniquely identified by object path. The object path - of an Account MUST take the form - <code>/org/freedesktop/Telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p> - - <ul> - <li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type> - that appears in the connection manager's well-known bus name and - object path</li> - <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>, - but with "-" replaced with "_" - (i.e. the same as in the object-path of a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li> - <li><em>acct</em> is an arbitrary string of ASCII letters, digits - and underscores, starting with a letter or underscore, which - uniquely identifies this account</li> - <li>Clients SHOULD parse the object path to discover the - connection manager and protocol</li> - <li>Clients MUST NOT attempt to parse <em>acct</em></li> - <li>Clients MUST NOT assume that <em>acct</em> matches - the connection-specific part of a Connection's object-path and - bus name</li> - <li>The account manager SHOULD choose <em>acct</em> such that if - an account is deleted, its object path will be re-used if and only - if the new account is in some sense "the same" - (incorporating the 'account' parameter in some way is - recommended)</li> - </ul> - - <tp:rationale> - <p>This API avoids specifying the "profiles" used in Mission Control - 4.x or the "presets" that have been proposed to replace them. An - optional interface will be provided for AM implementations - that want to provide presets.</p> - - <p>There is deliberately no functionality here for opening channels; - we intend to provide that in the channel dispatcher.</p> - - <p>Other missing features which would be better in their own - interfaces:</p> - - <ul> - <li>dynamic parameter-providing (aka provisioning)</li> - <li>saved server capabilities</li> - <li>account conditions</li> - <li>account grouping</li> - </ul> - </tp:rationale> - - </tp:docstring> - <tp:added version="0.17.2"/> - <tp:changed version="0.17.6">moved the Avatar property to a separate - interface</tp:changed> - - <!-- Missing functionality compared with NMC 4.x account + profile, - apart from as listed above: - - * vCard field, + default profile for each vCard field - (vCard field is per protocol and should be chosen by the - Telepathy <-> address-book bridge?; default profile is now - meaningless) - - * "normalized name" (normalized handle?) - - * branding icon (what's this and how does it differ from the icon?) - - * configuration UI (not our problem - perhaps the UI could special-case - by cm,protocol,preset tuples?) - - * default account domain (somewhat meaningless in general; specialized - account config UI can hard-code this) - - * SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol, - not the profile, and in any case only the account config UI cares) - - Missing functionality compared with Decibel accounts: - - * we don't really know, they take arbitrary key/value pairs... - but display name, protocol, presence/message, current, autoreconnect - are the ones given special status by the source, and we have all of them - --> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read"> - <tp:docstring> - A list of the extra interfaces provided by this account. - </tp:docstring> - </property> - - <method name="Remove" tp:name-for-bindings="Remove"> - <tp:docstring>Delete the account.</tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <signal name="Removed" tp:name-for-bindings="Removed"> - <tp:docstring> - This account has been removed. - - <tp:rationale> - This is redundant with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>, - but it's still worth having, - to avoid having to bind to AccountManager.AccountRemoved to tell - you whether your Account is valid — ideally, an account-editing UI - should only care about a single Account. - </tp:rationale> - </tp:docstring> - </signal> - - <signal name="AccountPropertyChanged" - tp:name-for-bindings="Account_Property_Changed"> - <tp:docstring> - The values of one or more properties on this interface (that do not - specify that this signal does not apply to them) may have changed. - This does not cover properties of other interfaces, which must - provide their own change notification if appropriate. - </tp:docstring> - - <arg name="Properties" type="a{sv}"> - <tp:docstring> - A map from property names in this namespace (e.g. - <tp:member-ref>Nickname</tp:member-ref>) to - values. Properties whose values have not changed SHOULD be - omitted, but this need not be done. - </tp:docstring> - </arg> - </signal> - - <property name="DisplayName" type="s" access="readwrite" - tp:name-for-bindings="Display_Name"> - <tp:docstring> - The user-visible name of this account. This SHOULD be chosen by the - user at account creation time. The account creation user interface - is responsible for setting a reasonable default value in the user's - locale; something like "Jabber (bob@example.com)" would be sensible. - </tp:docstring> - </property> - - <property name="Icon" tp:name-for-bindings="Icon" - type="s" access="readwrite"> - <tp:docstring> - The name of an icon in the system's icon theme, such as "im-msn", - or the empty string to not specify an icon. If the icon is set to - an empty string, the account manager or any client MAY derive a - default icon, for instance from the protocol. - </tp:docstring> - </property> - - <property name="Valid" tp:name-for-bindings="Valid" - type="b" access="read"> - <tp:docstring> - If true, this account is considered by the account manager to be - complete and usable. If false, user action is required to make it - usable, and it will never attempt to connect (for instance, this - might be caused by the absence of a required parameter). - - <tp:rationale> - For connection managers with a plugin architecture, like - telepathy-haze, we have little or no control over the parameters - offered; for platforms with package management, we have little or - no control over the CMs offered. NMC 4.x would just pretend the - account didn't exist in these circumstances, but silent data loss - is bad, and UIs with CM-specific knowledge (or a user filling in - newly-required parameters) might be able to rescue a broken account. - </tp:rationale> - </tp:docstring> - </property> - - <property name="Enabled" tp:name-for-bindings="Enabled" - type="b" access="readwrite"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This property gives the users the possibility to prevent an account - from being used. This flag does not change the validity of the - account.</p> - - <p>A disabled account can never be put online.</p> - - <tp:rationale> - <p>Use cases:</p> - - <ul> - <li>user has two or more accounts capable of calling contact X, but - he doesn't want the UI to prompt him everytime about which one he - wants to use for the call. He can then disable all the equivalent - accounts but one.</li> - - <li>There is some temporary server error and the user doesn't want - to be be bother by error messages, or change the account - configuration: temporarily disabling the account is quicker.</li> - </ul> - </tp:rationale> - - <p>The AccountManager SHOULD allow this property to be set on invalid - accounts, but MUST NOT attempt to put invalid accounts online - even if they become Enabled.</p> - - <tp:rationale> - <p>There doesn't seem to be any good reason not to allow this.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="Nickname" tp:name-for-bindings="Nickname" - type="s" access="readwrite"> - <tp:docstring> - The nickname to set on this account for display to other contacts, - as set by the user. When the account becomes connected, the - account manager SHOULD set this as the user's alias using <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> - if appropriate. - - <tp:rationale> - In a later specification revision, we plan to separate the concepts - of a contact's nickname as set by themselves, and the local - name for them in our contact list (a "handle" or "pet name" as - described in XEP-0165 and its references). The terminology change - from alias to nickname here is a step in that direction. - </tp:rationale> - </tp:docstring> - </property> - - <property name="Service" tp:name-for-bindings="Service" type="s" - access="readwrite"> - <tp:added version="0.19.8"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Some protocols, like XMPP and SIP, are used by various different - user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by - Nokia</i>. On accounts for such services, this property SHOULD be - set to a string describing the service, which MUST consist only of - ASCII letters, numbers and hyphen/minus signs, and start with a - letter (matching the requirements for <tp:type>Protocol</tp:type>). - For the <tt>jabber</tt> protocol, one of the following service names - should be used if possible:</p> - - <ul> - <li><tt>google-talk</tt> (for <a - href="http://www.google.com/talk/">Google's IM service</a>)</li> - <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM - service)</li> - <li><tt>facebook</tt> (for <a - href="http://www.facebook.com/sitetour/chat.php">Facebook's IM - service</a>)</li> - <li><tt>lj-talk</tt> (for <a - href="http://www.livejournal.com/chat/">LiveJournal's IM - service</a>)</li> - - </ul> - - <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a - corresponding brand-specific icon name, if possible. In the future, - this property may be used as an index into additional - service-specific customizations. If this property is the empty string - (or missing), the service is determined by the protocol name (either - because this is a single-service protocol like <tt>msn</tt>, or - because this is just a generic <tt>jabber</tt> or <tt>sip</tt> - account without specific branding).</p> - - <p>This property MAY be set, if appropriate, when calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.AccountManager" - >CreateAccount</tp:dbus-ref>. Updating this property will fail on - externally-stored accounts whose <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account.Interface.Storage" - >StorageRestrictions</tp:dbus-ref> include - <code>Cannot_Set_Service</code>.</p> - </tp:docstring> - </property> - - <property name="Parameters" tp:name-for-bindings="Parameters" - type="a{sv}" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from connection manager parameter names (as in the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref> - interface) to their values. This property includes - only those parameters that are stored for this account, and SHOULD - only include those parameters that the user has explicitly set. - </p> - <p>This property cannot be altered using - <code>org.freedesktop.DBus.Properties.Set()</code>; use - <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p> - </tp:docstring> - </property> - - <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref> - property.</p> - - <p>If any of the <var>Set</var> parameters’ - <tp:type>Conn_Mgr_Param_Flags</tp:type> include - <code>DBus_Property</code>, the change will be applied immediately to - the corresponding D-Bus Property on the active - <tp:member-ref>Connection</tp:member-ref>, if there is one. If any of - the <var>Unset</var> parameters’ - <tp:type>Conn_Mgr_Param_Flags</tp:type> include both - <code>DBus_Property</code> and <code>Has_Default</code>, the - corresponding D-Bus Property on the connection will be set to the - default value. Changes to other parameters will not take effect - until the next time the account is disconnected and reconnected. (If - parameters are explicitly set to their default value, or are unset - when previously set to their default value, the account manager MAY - decide that no reconnection is necessary to make the change take - effect.)</p> - - <tp:rationale> - <p>In general, reconnecting is a destructive operation that shouldn't - happen as a side-effect. In particular, migration tools that - twiddle the settings of all accounts shouldn't cause an automatic - disconnect and reconnect.</p> - </tp:rationale> - </tp:docstring> - - <tp:changed version="0.17.16"> - parameters which are also D-Bus properties can and should be updated on - existing Connections - </tp:changed> - - <tp:changed version="0.17.24"> - return an array of the parameters that won't change until the account - is reconnected - </tp:changed> - - <arg name="Set" type="a{sv}" direction="in"> - <tp:docstring> - A mapping from parameter names to their values. These parameters - should be stored for future use. - </tp:docstring> - </arg> - - <arg name="Unset" type="as" direction="in"> - <tp:docstring> - A list of the names of parameters to be removed from the set of - stored values, allowing the default values to be used. - If the given parameters were not, in fact, stored, or even if they - do not exist at all, the account manager MUST accept this without - error. - </tp:docstring> - </arg> - - <arg name="Reconnect_Required" type="as" direction="out"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If all of the updates could be applied to the active - <tp:member-ref>Connection</tp:member-ref> (if any), - the empty list, signifying that no reconnection is required for the - new parameters to take effect. For example, if the only parameter - updated is <tt>...Cellular.<tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>, - the new value can be applied immediately to the connection.</p> - - <p>Otherwise, a list of the names of parameters with changes that - will not take effect until the account is reconnected. User - interfaces that require "instant apply" semantics MAY call - <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a - non-empty list. For example, if the caller updates both - <tt>...Anonymity.<tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt> - and <tt>require-encryption</tt>, the former can be applied to the - current connection, but the latter needs a reconnect to take - effect, so this method should return - <code>["require-encryption"]</code>.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - </tp:possible-errors> - </method> - - <property name="AutomaticPresence" type="(uss)" access="readwrite" - tp:type="Simple_Presence" tp:name-for-bindings="Automatic_Presence"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The presence status that this account should have if it is brought - online.</p> - - <tp:rationale> - In ITOS2007 and ITOS2008 this is a global preference, not visible - on D-Bus (the "default presence"). "Automatic presence" better - describes when it is used. - </tp:rationale> - - <p>Setting this property MUST NOT actually change the account's - status until the next time it is (re)connected for some reason.</p> - - <p>The value of this property MUST be one that would be acceptable - for <tp:member-ref>RequestedPresence</tp:member-ref>, - with the additional restriction that the - <tp:type>Connection_Presence_Type</tp:type> MUST NOT be Offline.</p> - - <tp:rationale> - <p>Otherwise, it would not be possible to use this presence to bring - the account online for a channel request.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="ConnectAutomatically" type="b" access="readwrite" - tp:name-for-bindings="Connect_Automatically"> - <tp:docstring> - If true, the account manager SHOULD attempt to put this account - online with the <tp:member-ref>AutomaticPresence</tp:member-ref> - whenever possible (in the base - Account interface this is deliberately left vague). If false, - it MUST NOT put the account online automatically in response to, - for instance, connectivity changes, but SHOULD still put the account - online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if - requested by the user (for - instance, if the user tries to start a conversation using this - account). - </tp:docstring> - </property> - - <property name="Connection" tp:name-for-bindings="Connection" - type="o" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Either the object path of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to - this account, or the special value <code>'/'</code> if there is no - connection.</p> - - <p>If this object path is not '/', the Connection's well-known bus - name can be derived from this object path by removing the first '/' - and replacing subsequent '/' characters with '.'.</p> - - <tp:rationale> - Object paths aren't nullable, so we can't use an empty string. - </tp:rationale> - </tp:docstring> - </property> - - <property name="ConnectionStatus" type="u" tp:type="Connection_Status" - access="read" tp:name-for-bindings="Connection_Status"> - <tp:docstring> - If the <tp:member-ref>Connection</tp:member-ref> property is non-empty, - the status of that connection. - If the Connection property is the empty string, this property may - either be Disconnected (indicating that the account manager is not - attempting to bring it online), or Connecting (indicating that the - account manager is attempting to connect). - The account manager is expected to set this by observing signals - from the Connection. - - <tp:rationale> - If the AM is doing some sort of backoff/delay on reconnection - attempts, the account's status is conceptually "Connecting" even - though there is no Connection. - </tp:rationale> - </tp:docstring> - </property> - - <property name="ConnectionStatusReason" type="u" - tp:type="Connection_Status_Reason" access="read" - tp:name-for-bindings="Connection_Status_Reason"> - <tp:docstring> - The reason for the last change to - <tp:member-ref>ConnectionStatus</tp:member-ref>. - The account manager is expected to set this by observing signals - from the Connection. - - <tp:rationale> - If you weren't watching the Connection at the time it failed, - you can't tell why - unless the AM can tell you. - </tp:rationale> - </tp:docstring> - </property> - - <property name="ConnectionError" tp:name-for-bindings="Connection_Error" - access="read" type="s" tp:type="DBus_Error_Name"> - <tp:added version="0.19.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If the last connection to this account failed with an error, - the D-Bus error name of that error; otherwise, the empty string. - The account manager is expected to set this by observing the - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.ConnectionError</tp:dbus-ref> and - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.StatusChanged</tp:dbus-ref> - signals.</p> - - <p>If ConnectionError is received before the connection disconnects, - its first argument should be used to set this property; - otherwise, the Reason argument of StatusChanged should be converted - to a suitable D-Bus error name.</p> - - <p>Whenever the Connection connects successfully, this property should - be reset to the empty string.</p> - - <tp:rationale> - <p>This combines the state-recoverability of - <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the - extensibility of Connection.ConnectionError.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="ConnectionErrorDetails" - tp:name-for-bindings="Connection_Error_Details" - access="read" type="a{sv}" tp:type="String_Variant_Map"> - <tp:added version="0.19.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If the last connection to this account failed with an error, - a mapping representing any additional information about the last - disconnection; otherwise, the empty map. The keys and values are - the same as for the second argument of - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.ConnectionError</tp:dbus-ref>.</p> - - <p>Whenever the Connection connects successfully, this property should - be reset to the empty map.</p> - - <tp:rationale> - <p>This combines the state-recoverability of - <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the - extensibility of Connection.ConnectionError.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="CurrentPresence" type="(uss)" access="read" - tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence"> - <tp:docstring> - The actual presence. If the connection is not online, the - <tp:type>Connection_Presence_Type</tp:type> 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">SimplePresence</tp:dbus-ref> - interface, the type SHOULD be Connection_Presence_Type_Unset. - The account manager is expected to set this by observing signals - from the Connection. - </tp:docstring> - </property> - - <property name="RequestedPresence" type="(uss)" access="readwrite" - tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The requested presence for this account. When this is changed, the - account manager should attempt to manipulate the connection manager to - make <tp:member-ref>CurrentPresence</tp:member-ref> match - <tp:member-ref>RequestedPresence</tp:member-ref> as closely as - possible. It should not be saved to any sort of persistent - storage.</p> - - <p>When the account manager automatically connects an account, - it must signal this by setting the RequestedPresence to the same - thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p> - - <p>The <tp:type>Connection_Presence_Type</tp:type> in this property - MUST NOT be Unset, Unknown or Error.</p> - - <tp:rationale> - <p>Requesting those presence types doesn't make sense.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, a change to the presence of this account is - in progress.</p> - - <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on - an account that could go online, or whenever an account with a - non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes - able to go online (for instance because - <tp:member-ref>Enabled</tp:member-ref> or - <tp:member-ref>Valid</tp:member-ref> changes to True), - ChangingPresence MUST change to True, and the two property changes MUST - be emitted in the same - <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the - Set method returns.</p> - - <p>When the account manager succeeds or fails in changing the presence, - or the connection disconnects due to an error, ChangingPresence MUST - change to False as part of the same - <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p> - - <tp:rationale> - <p>This allows UIs to indicate that a presence change is in progress - or has finished, even if the change was initiated by a different - UI.</p> - - <p>For instance, Maemo 5 and Empathy indicate a presence change by - having the presence indicator alternate between the - <tp:member-ref>RequestedPresence</tp:member-ref> - and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should - start blinking when ChangingPresence becomes true, and stop when it - becomes false.</p> - </tp:rationale> - - </tp:docstring> - </property> - - <method name="Reconnect" tp:name-for-bindings="Reconnect"> - <tp:added version="0.17.24"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Re-connect this account. If the account is currently disconnected - and the requested presence is offline, or if the account - is not <tp:member-ref>Enabled</tp:member-ref> or not - <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p> - - <p>If the account is disconnected and the requested presence is not - offline, this forces an attempt to connect with the requested - presence immediately.</p> - - <p>If the account is connecting or connected, this is equivalent to - remembering the current value of - <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value - to (OFFLINE, "offline", ""), waiting for the change to take effect, - then setting its value to the value that was previously - remembered.</p> - - <tp:rationale> - <p>Clients desiring "instant apply" semantics for CM parameters MAY - call this method to achieve that.</p> - </tp:rationale> - - <p>In particular, if the account's - <tp:member-ref>Connection</tp:member-ref> is in the Connecting - state, calling this method causes the attempt to connect to be - aborted and re-tried.</p> - - <tp:rationale> - <p>This is necessary to ensure that the new parameters are - picked up.</p> - </tp:rationale> - </tp:docstring> - </method> - - <property name="NormalizedName" type="s" access="read" - tp:name-for-bindings="Normalized_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The normalized user ID of the local user on this account (i.e. the - string returned when the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> - method is called on the - result of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref> - for an active connection).</p> - - <p>It is unspecified whether this user ID is globally unique.</p> - - <tp:rationale> - <p>As currently implemented, IRC user IDs are only unique within - the same IRCnet. On some saner protocols, the user ID includes a - DNS name which provides global uniqueness.</p> - </tp:rationale> - - <p>If this value is not known yet (which will always be the case for - accounts that have never been online), it will be an empty - string.</p> - - <p>It is possible that this value will change if the connection - manager's normalization algorithm changes, although this SHOULD - be avoided.</p> - - <tp:rationale> - <p>It's not always completely clear what normalization algorithm - should be used; for instance, in Gabble, we currently use JIDs, - but it would also have been reasonable to use xmpp URIs.</p> - </tp:rationale> - </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_Interface_Addressing.xml b/qt4/spec/Account_Interface_Addressing.xml deleted file mode 100644 index 4b2846b68..000000000 --- a/qt4/spec/Account_Interface_Addressing.xml +++ /dev/null @@ -1,76 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Ltd</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.Account.Interface.Addressing"> - <tp:requires interface="org.freedesktop.Telepathy.Account"/> - <tp:added version="0.21.5">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Some accounts can be used for multiple protocols; for instance, SIP - and Skype accounts can often be used to contact the PSTN, MSN and - Yahoo accounts can contact each other, and XMPP accounts can - potentially contact many protocols via a transport.</p> - <p>However, if the user does not intend to make use of this functionality, - user interfaces can improve clarity by not displaying it: for instance, - if a user prefers to call phone numbers via a particular SIP account, - when an address book displays a contact with a phone number, it is - desirable to display a "call with SIP" button for that account, but - avoid displaying similar buttons for any other configured SIP or - Skype accounts.</p> - <p>The purpose of this interface is to allow this "for use with" information - to be recorded and retrieved.</p> - </tp:docstring> - - <property name="URISchemes" type="as" access="read" - tp:name-for-bindings="URI_Schemes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of fields indicating the type of URI addressing scheme - the the account should be used for (eg 'tel') indicating the - account is intended for use by applications offering a telephony - UI, or 'sip' or 'xmpp' for those protocols</p> - <p>Note that these fields signify intent, not ability: It is - entirely possible that an account which can be used for a - given URI scheme is not wanted for it by the user, and - therefore not flagged as such in this field.</p> - </tp:docstring> - </property> - - <method name="SetURISchemeAssociation" - tp:name-for-bindings="Set_URI_Scheme_Association"> - <tp:docstring> - <p>Associate (or disassociate) an account with a particular - URI addressing scheme, (such as 'tel' for telephony)</p> - </tp:docstring> - - <arg name="URI_Scheme" direction="in" type="s"> - <tp:docstring> - <p>URI scheme to associate/disassociate the account with/from</p> - </tp:docstring> - </arg> - - <arg name="Association" direction="in" type="b"> - <tp:docstring> - <p>True to associate this account with a given addressing scheme</p> - <p>False if the account should not be associated with said scheme</p> - </tp:docstring> - </arg> - - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Account_Interface_Avatar.xml b/qt4/spec/Account_Interface_Avatar.xml deleted file mode 100644 index a8b78c8a2..000000000 --- a/qt4/spec/Account_Interface_Avatar.xml +++ /dev/null @@ -1,72 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Avatar" - 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: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.Account.Interface.Avatar"> - <tp:requires interface="org.freedesktop.Telepathy.Account"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface extends the core Account interface to provide a - user-settable avatar image.</p> - - <tp:rationale> - <p>The avatar could have been a property on the core Account interface, - but was moved to a separate interface because it is likely to be - large. This means that clients can safely use GetAll to get - properties on the core Account interface without flooding the - session bus with large images.</p> - </tp:rationale> - - </tp:docstring> - <tp:added version="0.17.6"/> - - <tp:struct name="Avatar"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A struct containing avatar data marked with its MIME type.</p> - </tp:docstring> - <tp:member type="ay" name="Avatar_Data"/> - <tp:member type="s" name="MIME_Type"/> - </tp:struct> - - <property name="Avatar" tp:name-for-bindings="Avatar" - type="(ays)" tp:type="Avatar" access="readwrite"> - <tp:docstring> - The avatar to set on this account for display to other contacts, - represented as a structure containing the bytes of the avatar, - and the MIME type as a string; may be set to an empty byte-array and - an empty string to indicate no avatar. When the account becomes - connected, the account manager SHOULD set this avatar using SetAvatar - if appropriate. - </tp:docstring> - </property> - - <signal name="AvatarChanged" tp:name-for-bindings="Avatar_Changed"> - <tp:docstring> - Emitted when the Avatar property changes. - - <tp:rationale>The avatar itself is deliberately not included in this - signal, to reduce bus traffic in the (likely common) case where no - running application cares about the user's own avatar.</tp:rationale> - </tp:docstring> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Account_Interface_External_Password_Storage.xml b/qt4/spec/Account_Interface_External_Password_Storage.xml deleted file mode 100644 index 5bd1bfce0..000000000 --- a/qt4/spec/Account_Interface_External_Password_Storage.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_External_Password_Storage" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2011 Collabora Ltd.</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.Account.Interface.ExternalPasswordStorage.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.10">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Account"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for Accounts whose passwords are stored externally and - SHOULD NOT be stored by either the - <tp:dbus-ref namespace="ofdT">AccountManager</tp:dbus-ref> nor any - <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - handler.</p> - - <p>This interface SHOULD only appear on accounts for which the - related Connection Manager implements - <tp:dbus-ref namespace="ofdT">ConnectionManager.Interface.AccountStorage.DRAFT</tp:dbus-ref>.</p> - </tp:docstring> - - <method name="ForgetPassword" tp:name-for-bindings="Forget_Password"> - <tp:docstring> - Clears any saved password associated with this account. - </tp:docstring> - </method> - - <property name="PasswordSaved" - tp:name-for-bindings="Password_Saved" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Indicates whether the account has a saved password or not.</p> - - <p>Change notification for this property is provided by the - standard D-Bus <code>PropertiesChanged</code> signal.</p> - </tp:docstring> - </property> - - </interface> -</node> diff --git a/qt4/spec/Account_Interface_Hidden.xml b/qt4/spec/Account_Interface_Hidden.xml deleted file mode 100644 index cb0019178..000000000 --- a/qt4/spec/Account_Interface_Hidden.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Hidden" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Account.Interface.Hidden.DRAFT1" - tp:causes-havoc="outrageous"> - <tp:added version="0.21.10">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for flagging certain accounts as hidden, so that they do - not appear in the account manager's standard lists of accounts. - Accounts whose <tp:member-ref>Hidden</tp:member-ref> property is - <code>True</code> are intended for non-interactive use (by - non-user-visible services), and appear on the <tp:dbus-ref - namespace='ofdT'>AccountManager.Interface.Hidden.DRAFT1</tp:dbus-ref> - interface; in all other respects, they behave like any other - account.</p> - - <tp:rationale> - <p>XMPP, in particular, is increasingly used for purposes other than - instant messaging and VoIP. For instance, extensions exist for - inter-device bookmark synchronization.</p> - - <p>While obviously these services could re-use connections intended for - instant messaging, in some cases you might want to use a different - account. (Perhaps your bookmark sync provider is not your IM - provider.) This API allows such auxiliary accounts to exist in - Telepathy, while not being displayed in standard user interfaces for - IM, VoIP, and friends.</p> - </tp:rationale> - </tp:docstring> - - <property name="Hidden" tp:name-for-bindings="Hidden" - type="b" access="read" tp:immutable='aye'> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <code>True</code>, this account is intended for non-interactive - use, and thus should not be presented to the user. It will not appear - in properties and signals on the main <tp:dbus-ref - namespace='ofdT'>AccountManager</tp:dbus-ref> interface; instead, it - will show up on <tp:dbus-ref - namespace='ofdT'>AccountManager.Interface.Hidden.DRAFT1</tp:dbus-ref>.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Account_Interface_Minimum_Presence.xml b/qt4/spec/Account_Interface_Minimum_Presence.xml deleted file mode 100644 index eb829b824..000000000 --- a/qt4/spec/Account_Interface_Minimum_Presence.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Minimum_Presence" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2010 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.Account.Interface.MinimumPresence.DRAFT2" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Account"/> - <tp:added version="0.19.12">(draft 2)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface extends the core Account interface to provide a way - for applications to request minimum presence on the account.</p> - - <tp:rationale> - <p>Some applications, for example mail notifiers or address book - synchronisation, can make use of account's connection even while - the user is nominally offline.</p> - </tp:rationale> - - <p>Each client's unique name may set a minimum desired presence on the - account. The combined presence is the most available presence - of the minimum presences set and of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref> - set by the user. The account manager should attempt to manipulate - the connection to set the combined presence.</p> - </tp:docstring> - - <property name="MinimumPresenceRequests" - tp:name-for-bindings="MinimumPresenceRequests" access="read" - type="a{s(uss)}" tp:type="Minimum_Presence_Request_Map"> - <tp:docstring> - Active requests for minimum presence status, a map of client unique - name to the (non-offline) minimum presence they set. - </tp:docstring> - </property> - - <method name="SetMinimumPresence" tp:name-for-bindings="Set_Minimum_Presence"> - <tp:docstring> - <p>Set a minimum presence needed by the client for this account. Setting - (Offline, "offline", "") removes the minimum presence requirement for - the client's unique name.</p> - </tp:docstring> - - <arg direction="in" name="status" type="(uss)" tp:type="Simple_Presence"> - <tp:docstring> - Requested presence status. - </tp:docstring> - </arg> - </method> - - <signal name="MinimumPresenceRequestsChanged" - tp:name-for-bindings="Minimum_Presence_Requests_Changed"> - <tp:docstring> - Emitted when the - <tp:member-ref>MinimumPresenceRequests</tp:member-ref> property - changes. - </tp:docstring> - - <arg name="MinimumPresenceRequests" type="a{s(uss)}" - tp:type="Minimum_Presence_Request_Map"> - <tp:docstring> - A new value of MinimumPresenceRequests property. - </tp:docstring> - </arg> - </signal> - - <tp:mapping name="Minimum_Presence_Request_Map"> - <tp:docstring> - <p>A map of active minimum presence requests.</p> - </tp:docstring> - <tp:member type="s" name="Key" tp:type="DBus_Unique_Name"> - <tp:docstring> - <p>Client unique name.</p> - </tp:docstring> - </tp:member> - <tp:member type="(uss)" name="Value" tp:type="Simple_Presence"> - <tp:docstring> - <p>Requested minimum presence.</p> - - <tp:rationale> - <p>Some applications may want to monitor the currently active - minimum presences required. An example is an tool allowing - the user to inspect applications maintaining open connections and - close those applications.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:mapping> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Account_Interface_Storage.xml b/qt4/spec/Account_Interface_Storage.xml deleted file mode 100644 index 4e3ba5dca..000000000 --- a/qt4/spec/Account_Interface_Storage.xml +++ /dev/null @@ -1,169 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Storage" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2010 Collabora Ltd.</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.Account.Interface.Storage"> - <tp:requires interface="org.freedesktop.Telepathy.Account"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - This interface extends the core Account interface to specify details - regarding the storage of this account. - </p> - - <tp:rationale> - <p> - Single-sign-on systems do not generally have directly user-editable - properties for Accounts, and require the user to visit a specific UI - to alter their account properties. User interfaces should know not to - expose these account properties as user-editable, and instead - redirect the user to the appropriate interface. - </p> - </tp:rationale> - - </tp:docstring> - <tp:added version="0.19.8"/> - - <property name="StorageProvider" tp:name-for-bindings="Storage_Provider" - type="s" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - The name of the account storage implementation, which SHOULD start - with a reversed domain name in the same way as D-Bus interface names. - When this is the empty string the account is internally stored. - </p> - <p> - This property cannot change once an Account has been created. - </p> - </tp:docstring> - </property> - - <property name="StorageIdentifier" - tp:name-for-bindings="Storage_Identifier" type="v" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - Unique identification of the account within the storage backend. - The contents of the variant are defined by the - <tp:member-ref>StorageProvider</tp:member-ref>. - </p> - <p> - This property cannot change once an Account has been created. - </p> - <tp:rationale> - <p> - Different storage systems will have their own way of uniquely - identifying an account, typically an integer or a string. - Given that all users of this property should have direct knowledge - of the backend they should know what types to expect and how to - handle it. - </p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="StorageSpecificInformation" - tp:name-for-bindings="Storage_Specific_Information" type="a{sv}" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - Map containing information specific to the storage backend. The keys - and the types of their values are defined by the - <tp:member-ref>StorageProvider</tp:member-ref>, and are not - interpreted by the AccountManager implementation. - </p> - <p> - As the values in this map may change at any time (due to an external - application manipulating the storage provider directly), this - property should not be cached; it should instead be retrieved each - time it is needed. - </p> - - <tp:rationale> - <p> - This can be used to provide additional hints to user interfaces - aware of a specific storage provider, without requiring those user - interfaces to use the - <tp:member-ref>StorageIdentifier</tp:member-ref> to query the - storage provider directly. - </p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="StorageRestrictions" - tp:name-for-bindings="Storage_Restrictions" type="u" - tp:type="Storage_Restriction_Flags" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - Bitfield which defines what restrictions this Storage method has. - </p> - <p> - This property cannot change once an Account has been created. - </p> - </tp:docstring> - </property> - - <tp:flags name="Storage_Restriction_Flags" - value-prefix="Storage_Restriction_Flag" type="u"> - <tp:docstring> - Flags indicating restrictions imposed on an Account by its storage - method. - </tp:docstring> - - <tp:flag suffix="Cannot_Set_Parameters" value="1"> - <tp:docstring> - The account's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account" - >Parameters</tp:dbus-ref> property can't be changed by calling - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Cannot_Set_Enabled" value="2"> - <tp:docstring> - The account can't be enabled/disabled by setting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account" - >Enabled</tp:dbus-ref> property. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Cannot_Set_Presence" value="4"> - <tp:docstring> - The account's presence can't be changed by setting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account" - >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account" - >AutomaticPresence</tp:dbus-ref> properties. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Cannot_Set_Service" value="8"> - <tp:docstring> - The account's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref> - property cannot be changed. - </tp:docstring> - </tp:flag> - </tp:flags> - - </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 deleted file mode 100644 index cd82e7f53..000000000 --- a/qt4/spec/Account_Manager.xml +++ /dev/null @@ -1,296 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Manager" - 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.AccountManager"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The account manager is a central service used to store account - details.</p> - - <p>The current account manager is defined to be the process that owns - the well-known bus name org.freedesktop.Telepathy.AccountManager on - the session bus. This process must export an - /org/freedesktop/Telepathy/AccountManager object with the - AccountManager interface.</p> - - <p>Until a mechanism exists for making a reasonable automatic choice - of AccountManager implementation, implementations SHOULD NOT - register as an activatable service for the AccountManager's - well-known bus name. Instead, it is RECOMMENDED that some component - of the user's session will select and activate a particular - implementation, and that other Telepathy-enabled programs can - detect whether Telepathy is in use by checking whether the - AccountManager's well-known name is in use at runtime.</p> - </tp:docstring> - <tp:added version="0.17.2"/> - - <!-- Missing functionality compared with NMC 4.x: - * look up accounts by conditions (can be done client-side, less - efficiently, so not a blocker) - * global presence/... changes (can be done client-side, less efficiently - - we should add this) - * count used channels (what's this for?) - * get "average" status (not well-defined, UIs can do this) - * request channels (out of scope: Channel Dispatcher will do this) - * register filters (completely out of scope: Channel Dispatcher again) - --> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read"> - <tp:docstring> - A list of the interfaces provided by the account manager object. - </tp:docstring> - </property> - - <property name="ValidAccounts" type="ao" access="read" - tp:name-for-bindings="Valid_Accounts"> - <tp:docstring> - A list of the valid (complete, usable) <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change - notification is via - <tp:member-ref>AccountValidityChanged</tp:member-ref>. - - <tp:rationale> - This split between valid and invalid accounts makes it easy to - ignore the invalid ones. The only things that should be manipulating - invalid accounts are account-editing UIs, which might be able to - rescue them. - </tp:rationale> - </tp:docstring> - </property> - - <property name="InvalidAccounts" type="ao" access="read" - tp:name-for-bindings="Invalid_Accounts"> - <tp:docstring> - A list of incomplete or otherwise unusable <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change - notification is via - <tp:member-ref>AccountValidityChanged</tp:member-ref>. - </tp:docstring> - </property> - - <signal name="AccountRemoved" tp:name-for-bindings="Account_Removed"> - <tp:docstring> - The given account has been removed. - - <tp:rationale> - This is effectively change notification for the valid and invalid - accounts lists. On emission of this signal, the Account indicated - will no longer be present in either of the lists. - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An Account, which must not be used any more. - </tp:docstring> - </arg> - </signal> - - <signal name="AccountValidityChanged" - tp:name-for-bindings="Account_Validity_Changed"> - <tp:docstring> - The validity of the given account has changed. New accounts are - also indicated by this signal, as an account validity change - (usually to True) on an account that did not previously exist. - - <tp:rationale> - This is effectively change notification for the valid and invalid - accounts lists. - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Valid" type="b"> - <tp:docstring> - True if the account is now valid. - </tp:docstring> - </arg> - </signal> - - <property name="SupportedAccountProperties" - tp:name-for-bindings="Supported_Account_Properties" - type="as" tp:type="DBus_Qualified_Member[]" access="read"> - <tp:added version="0.17.24"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the fully qualified names of properties that can be set - via the Properties argument to - <tp:member-ref>CreateAccount</tp:member-ref> when an account is - created.</p> - - <tp:rationale> - <p>Examples of good properties to support here include - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref> - and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>. - </p> - - <p>Examples of properties that would make no sense here include - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref> - and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>. - </p> - </tp:rationale> - - <p>This property MUST NOT include include the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> - properties, which are set using separate arguments.</p> - - <p>This property MAY include the names of properties that, after - account creation, will be read-only: this indicates that the property - can be set at account creation but not changed later.</p> - - <tp:rationale> - <p>For example, an account manager might support migration tools that - use this to preserve the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref> - property, even though that property is usually read-only.</p> - </tp:rationale> - </tp:docstring> - </property> - - <method name="CreateAccount" tp:name-for-bindings="Create_Account"> - <tp:docstring> - Request the creation of a new <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The - account manager SHOULD NOT allow invalid accounts to be created. - </tp:docstring> - <tp:changed version="0.17.24">added the Properties argument</tp:changed> - - <arg name="Connection_Manager" direction="in" type="s" - tp:type="Connection_Manager_Name"> - <tp:docstring> - The name of the connection manager, e.g. "salut". - </tp:docstring> - </arg> - - <arg name="Protocol" direction="in" type="s" - tp:type="Protocol"> - <tp:docstring>The protocol, e.g. "local-xmpp".</tp:docstring> - </arg> - - <arg name="Display_Name" direction="in" type="s"> - <tp:docstring>The initial value of the new account's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> - property. The account manager SHOULD modify this to make it unique if - an Account already exists with the same display name, for instance by - appending a number or the 'account' parameter. Account manager - implementations SHOULD accept an empty string, but account editing - user interfaces should avoid passing an empty string for this - parameter. - - <tp:rationale> - <p>The account creation UI may ask the user for a name for the new - account. If the author of the UI chooses not to do this, the - account creation UI is better able to suggest a default display - name because it has protocol-specific knowledge which the account - manager does not.</p> - - <p>The account manager always knows the complete list of accounts so - it can easily tell whether it should append something to the - display name to avoid presenting two identically-named accounts to - the user.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="Parameters" direction="in" type="a{sv}"> - <tp:docstring>Initial parameter values, as would be passed to - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring> - </arg> - - <arg name="Properties" direction="in" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The values of any other properties to be set immediately on the - new Account.</p> - - <p>Only the properties mentioned in - <tp:member-ref>SupportedAccountProperties</tp:member-ref> are - acceptable here. In particular, the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> - properties are never allowed here, since they are set using the other - arguments to this method.</p> - - <p>Account manager implementations SHOULD support creating accounts - with an empty value for this argument.</p> - </tp:docstring> - </arg> - - <arg name="Account" direction="out" type="o"> - <tp:docstring>The new <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The Connection_Manager is not installed or does not - implement the given Protocol, or one of the properties in the - Properties argument is unsupported.</p> - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The Parameters provided omit a required parameter - or provide unsupported parameter, or the type of one - of the Parameters or Properties is inappropriate.</p> - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> - diff --git a/qt4/spec/Account_Manager_Interface_Hidden.xml b/qt4/spec/Account_Manager_Interface_Hidden.xml deleted file mode 100644 index 284eb6428..000000000 --- a/qt4/spec/Account_Manager_Interface_Hidden.xml +++ /dev/null @@ -1,100 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Manager_Interface_Hidden" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2010 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.AccountManager.Interface.Hidden.DRAFT1" - tp:causes-havoc='kind of sketchy'> - <tp:requires interface='org.freedesktop.Telepathy.AccountManager'/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface lists accounts whose <tp:dbus-ref - namespace='ofdT.Account.Interface.Hidden.DRAFT1'>Hidden</tp:dbus-ref> - property is <code>True</code>.</p> - </tp:docstring> - <tp:added version="0.21.10">first draft</tp:added> - - <property name="ValidHiddenAccounts" type="ao" access="read" - tp:name-for-bindings="Valid_Hidden_Accounts"> - <tp:docstring> - A list of valid (complete, usable) <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s intended - exclusively for noninteractive applications. These accounts are not - included in <tp:dbus-ref - namespace='ofdT'>AccountManager.ValidAccounts</tp:dbus-ref>. Change - notification is via - <tp:member-ref>HiddenAccountValidityChanged</tp:member-ref>. - </tp:docstring> - </property> - - <property name="InvalidHiddenAccounts" type="ao" access="read" - tp:name-for-bindings="Invalid_Hidden_Accounts"> - <tp:docstring> - A list of incomplete or otherwise unusable <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s intended - exclusively for noninteractive applications. Change notification is via - <tp:member-ref>HiddenAccountValidityChanged</tp:member-ref>. - </tp:docstring> - </property> - - <signal name="HiddenAccountRemoved" - tp:name-for-bindings="Hidden_Account_Removed"> - <tp:docstring> - The given account has been removed from - <tp:member-ref>ValidHiddenAccounts</tp:member-ref> or - <tp:member-ref>InvalidHiddenAccounts</tp:member-ref>. - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An Account, which must not be used any more. - </tp:docstring> - </arg> - </signal> - - <signal name="HiddenAccountValidityChanged" - tp:name-for-bindings="Hidden_Account_Validity_Changed"> - <tp:docstring> - The validity of the given account has changed. New magic - accounts are also indicated by this signal, as an account validity - change (usually to True) on an account that did not previously exist. - - <tp:rationale> - This is effectively change notification for the valid and invalid - accounts lists. - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Valid" type="b"> - <tp:docstring> - True if the account is now valid. - </tp:docstring> - </arg> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Authentication_TLS_Certificate.xml b/qt4/spec/Authentication_TLS_Certificate.xml deleted file mode 100644 index db1d76fd7..000000000 --- a/qt4/spec/Authentication_TLS_Certificate.xml +++ /dev/null @@ -1,305 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Limited</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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - - <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate"> - <tp:added version="0.19.13">(as stable API)</tp:added> - - <tp:docstring> - This object represents a TLS certificate. - </tp:docstring> - - <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List" - type="ay"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The raw data contained in a TLS certificate.</p> - - <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref> - = "x509"), this MUST be in DER format, as defined by the - <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a> - ITU standard.</p> - - <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref> - = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 - of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p> - </tp:docstring> - </tp:simple-type> - - <tp:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Struct representing one reason why a TLS certificate was rejected.</p> - <p>Since there can be multiple things wrong with a TLS certificate, - arrays of this type are used to represent lists of reasons for - rejection. In that case, the most important reason SHOULD be placed - first in the list.</p> - </tp:docstring> - - <tp:member name="Reason" type="u" - tp:type="TLS_Certificate_Reject_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The value of the TLS_Certificate_Reject_Reason enumeration for - this certificate rejection. - <tp:rationale> - Clients that do not understand the <code>Error</code> member, - which may be implementation-specific, can use this property to - classify rejection reasons into common categories. - </tp:rationale> - </p> - </tp:docstring> - </tp:member> - - <tp:member name="Error" type="s" - tp:type="DBus_Error_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The DBus error name for this certificate rejection.</p> - <p>This MAY correspond to the value of the <code>Reason</code> member, - or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p> - </tp:docstring> - </tp:member> - - <tp:member name="Details" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about why the certificate was rejected. - This MAY also include one or more of the following well-known keys:</p> - <p> - <dl> - <dt>user-requested (b)</dt> - <dd>True if the error was due to an user-requested rejection of - the certificate; False if there was an unrecoverable error in the - verification process.</dd> - <dt>expected-hostname (s)</dt> - <dd>If the rejection reason is Hostname_Mismatch, the hostname that - the server certificate was expected to have.</dd> - <dt>certificate-hostname (s)</dt> - <dd>If the rejection reason is Hostname_Mismatch, the hostname of - the certificate that was presented. - <tp:rationale> - <p>For instance, if you try to connect to gmail.com but are presented - with a TLS certificate issued to evil.example.org, the error details - for Hostname_Mismatch MAY include:</p> - <pre> - { - 'expected-hostname': 'gmail.com', - 'certificate-hostname': 'evil.example.org', - } - </pre> - </tp:rationale> - </dd> - <dt>debug-message (s)</dt> - <dd>Debugging information on the error, corresponding to the - message part of a D-Bus error message, which SHOULD NOT be - displayed to users under normal circumstances</dd> - </dl> - </p> - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:enum type="u" name="TLS_Certificate_State"> - <tp:docstring> - The possible states for a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref> - object. - </tp:docstring> - - <tp:enumvalue suffix="Pending" value="0"> - <tp:docstring> - The certificate is currently waiting to be accepted or rejected. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Accepted" value="1"> - <tp:docstring> - The certificate has been verified. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Rejected" value="2"> - <tp:docstring> - The certificate has been rejected. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum type="u" name="TLS_Certificate_Reject_Reason"> - <tp:docstring> - Possible reasons to reject a TLS certificate. - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - The certificate has been rejected for another reason - not listed in this enumeration. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Untrusted" value="1"> - <tp:docstring> - The certificate is not trusted. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Expired" value="2"> - <tp:docstring> - The certificate is expired. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Not_Activated" value="3"> - <tp:docstring> - The certificate is not active yet. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Fingerprint_Mismatch" value="4"> - <tp:docstring> - The certificate provided does not have the expected - fingerprint. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Hostname_Mismatch" value="5"> - <tp:docstring> - The hostname certified does not match the provided one. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Self_Signed" value="6"> - <tp:docstring> - The certificate is self-signed. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Revoked" value="7"> - <tp:docstring> - The certificate has been revoked. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Insecure" value="8"> - <tp:docstring> - The certificate uses an insecure cipher algorithm, or is - cryptographically weak. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Limit_Exceeded" value="9"> - <tp:docstring> - The length in bytes of the certificate, or the depth of the - certificate chain exceed the limits imposed by the crypto - library. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="State" type="u" access="read" - tp:type="TLS_Certificate_State" - tp:name-for-bindings="State"> - <tp:docstring> - The current state of this certificate. - State change notifications happen by means of the - <tp:member-ref>Accepted</tp:member-ref> and - <tp:member-ref>Rejected</tp:member-ref> signals. - </tp:docstring> - </property> - - <property name="Rejections" type="a(usa{sv})" access="read" - tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If the <tp:member-ref>State</tp:member-ref> is Rejected, - an array of <tp:type>TLS_Certificate_Rejection</tp:type> - structures containing the reason why the certificate is rejected.</p> - <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected, - this property is not meaningful, and SHOULD be set to an empty - array.</p> - <p>The first rejection in the list MAY be assumed to be - the most important; if the array contains more than one - element, the CM MAY either use the values after the first, - or ignore them.</p> - </tp:docstring> - </property> - - <property name="CertificateType" type="s" access="read" - tp:name-for-bindings="Certificate_Type"> - <tp:docstring> - The type of this TLS certificate (e.g. 'x509' or 'pgp'). - <p>This property is immutable</p> - </tp:docstring> - </property> - - <property name="CertificateChainData" type="aay" access="read" - tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more TLS certificates forming a trust chain, each encoded as - specified by <tp:type>Certificate_Data</tp:type>.</p> - <p>The first certificate in the chain MUST be the server certificate, - followed by the issuer's certificate, followed by the issuer's issuer - and so on.</p> - </tp:docstring> - </property> - - <signal name="Accepted" - tp:name-for-bindings="Accepted"> - <tp:docstring> - The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted. - </tp:docstring> - </signal> - - <signal name="Rejected" - tp:name-for-bindings="Rejected"> - <tp:docstring> - The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected. - </tp:docstring> - <arg name="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]"> - <tp:docstring> - The new value of the <tp:member-ref>Rejections</tp:member-ref> property. - </tp:docstring> - </arg> - </signal> - - <method name="Accept" tp:name-for-bindings="Accept"> - <tp:docstring> - Accepts this certificate, i.e. marks it as verified. - </tp:docstring> - </method> - - <method name="Reject" tp:name-for-bindings="Reject"> - <tp:docstring> - Rejects this certificate. - </tp:docstring> - <arg direction="in" type="a(usa{sv})" name="Rejections" - tp:type="TLS_Certificate_Rejection[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p> - <p>This MUST NOT be an empty array.</p> - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref> - is not <code>Pending</code>, or when the provided rejection list is empty. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Content.xml b/qt4/spec/Call_Content.xml deleted file mode 100644 index 270d99b08..000000000 --- a/qt4/spec/Call_Content.xml +++ /dev/null @@ -1,255 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Content.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This object represents one Content inside a <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For - example, in an audio/video call there would be one audio content - and one video content. Each content has one or more <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which - represent the actual transport to one or more remote contacts. - </tp:docstring> - - <tp:enum name="Content_Removal_Reason" type="u"> - <tp:added version="0.21.2"/> - <tp:docstring> - A representation of the reason for a content to be removed, - which may be used by simple clients, or used as a fallback - when the DBus_Reason is not understood. This enum will be - extended with future reasons as and when appropriate, so - clients SHOULD keep up to date with its values, but also be - happy to fallback to the Unknown value when an unknown value - is encountered. - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - We just don't know. Unknown values of this enum SHOULD also be - treated like this. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="User_Requested" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The local user requests that this content is removed - from the call.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Error" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There is an error with the content which means that it - has to be removed from the call.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Unsupported" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Some aspect of the content is unsupported so has to be - removed from the call.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <method name="Remove" tp:name-for-bindings="Remove"> - <tp:changed version="0.21.2">previously there were no - arguments</tp:changed> - <tp:docstring> - Remove the content from the call. - </tp:docstring> - - <arg direction="in" name="Reason" type="u" - tp:type="Content_Removal_Reason"> - <tp:docstring> - A generic hangup reason. - </tp:docstring> - </arg> - - <arg direction="in" name="Detailed_Removal_Reason" type="s" - tp:type="DBus_Error_Name"> - <tp:docstring> - A more specific reason for the content removal, if one is - available, or an empty string. - </tp:docstring> - </arg> - - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A human-readable message for the reason of removing the - content, such as "Fatal streaming failure" or "no codec - intersection". This property can be left empty if no reason - is to be given. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Raised when a Call doesn't support removing contents - (e.g. a Google Talk video call). - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="Removed" tp:name-for-bindings="Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the content is removed from the call. This - is the same as the <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT.ContentRemoved</tp:dbus-ref> - signal.</p> - </tp:docstring> - </signal> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> - <tp:added version="0.19.11"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra interfaces provided by this content, such as <tp:dbus-ref - namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or - <tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>. - This SHOULD NOT include the Content interface itself, and cannot - change once the content has been created.</p> - </tp:docstring> - </property> - - <property name="Name" tp:name-for-bindings="Name" type="s" access="read" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of the content.</p> - - <tp:rationale> - The content name property should be meaningful, so should be - given a name which is significant to the user. The name - could be the "audio" or "video" string localized, or perhaps - include some string identifying the source, such as a webcam - identifier. - </tp:rationale> - </tp:docstring> - </property> - - <property name="Type" tp:name-for-bindings="Type" - type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The media type of this content.</p> - </tp:docstring> - </property> - - <tp:enum name="Call_Content_Disposition" type="u"> - <tp:docstring> - The disposition of this content, which defines whether to - automatically start sending data on the streams when - <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is - called on the channel. - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The content has no specific disposition - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Initial" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The content was initially part of the call. When - <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - is called on the channel, all streams of this content with - <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> - set to <tp:type>Sending_State</tp:type>_Pending_Send will be - moved to <tp:type>Sending_State</tp:type>_Sending as if - <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> - (True) had been called.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="Disposition" tp:name-for-bindings="Disposition" - type="u" tp:type="Call_Content_Disposition" access="read" - tp:immutable="yes"> - <tp:docstring> - The disposition of this content. - </tp:docstring> - </property> - - <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added"> - <tp:changed version="0.21.2">plural version, renamed from - StreamAdded</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when streams are added to a call.</p> - </tp:docstring> - <arg name="Streams" type="ao"> - <tp:docstring> - The <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were - added. - </tp:docstring> - </arg> - </signal> - - <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed"> - <tp:changed version="0.21.2">plural version, renamed from - StreamRemoved</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when streams are removed from a call</p> - </tp:docstring> - <arg name="Streams" type="ao"> - <tp:docstring> - The <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were - removed. - </tp:docstring> - </arg> - </signal> - - <property name="Streams" tp:name-for-bindings="Streams" - type="ao" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The list of <tp:dbus-ref namespace="ofdT.Call" - >Stream.DRAFT</tp:dbus-ref> objects that exist in this - content.</p> - - <tp:rationale> - In a conference call multiple parties can share one media - content (say, audio), but the streaming of that media can - either be shared or separate. For example, in a multicast - conference all contacts would share one stream, while in a - Muji conference there would be a stream for each - participant. - </tp:rationale> - - <p>Change notification is through the - <tp:member-ref>StreamsAdded</tp:member-ref> and - <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p> - </tp:docstring> - </property> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Content_Codec_Offer.xml b/qt4/spec/Call_Content_Codec_Offer.xml deleted file mode 100644 index f88143f69..000000000 --- a/qt4/spec/Call_Content_Codec_Offer.xml +++ /dev/null @@ -1,87 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content_Codec_Offer" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Content.CodecOffer.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This object represents an offer of a Codec payload mapping. - </tp:docstring> - - <method name="Accept" tp:name-for-bindings="Accept"> - <arg name="Codecs" direction="in" - type="a(usuua{ss})" tp:type="Codec[]"> - <tp:docstring> - The local codec mapping to send to the remote contacts and - to use in the <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. - </tp:docstring> - </arg> - <tp:docstring> - Accept the updated Codec mapping and update the local mapping. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The codecs given as the argument are invalid in some way. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Reject" tp:name-for-bindings="Reject"> - <tp:docstring> - Reject the proposed update to the codecs - FIXME add error codes and strings here - </tp:docstring> - </method> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra interfaces provided by this codec offer. This SHOULD - NOT include the CodecOffer interface itself, and cannot change - once the content has been created.</p> - </tp:docstring> - </property> - - <property name="RemoteContactCodecs" - tp:name-for-bindings="Remote_Contact_Codecs" - type="a(usuua{ss})" tp:type="Codec[]" access="read" - tp:immutable="yes"> - <tp:docstring> - A list of codecs the remote contact supports. - </tp:docstring> - </property> - - <property name="RemoteContact" tp:name-for-bindings="Remote_Contact" - type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes"> - <tp:docstring> - The contact handle that this codec offer applies to. - </tp:docstring> - </property> - - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Content_Interface_Media.xml b/qt4/spec/Call_Content_Interface_Media.xml deleted file mode 100644 index 038ce8c7a..000000000 --- a/qt4/spec/Call_Content_Interface_Media.xml +++ /dev/null @@ -1,367 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content_Interface_Media" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Content.Interface.Media.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface to use by a software implementation of media - streaming. The reason behind splitting the members of this - interface out from the main <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is - that the software is not necessarily what controls the - media. An example of this is in GSM phones, where the CM just - tells the phone to dial a number and it does the audio routing - in a device specific hardware way and the CM does not need - to concern itself with codecs.</p> - - <h4>Codec negotiation</h4> - - <p>When a new <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel - appears, whether it was requested or not, a <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - will either be waiting in the - <tp:member-ref>CodecOffer</tp:member-ref> property, or will - appear at some point via the - <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p> - - <p>The <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - property on the codec offer lists the codecs which are - supported by the remote contact, and so will determine the - codecs that should be proposed by the local user's streaming - implementation. An empty list means all codecs can be proposed.</p> - - <p>For incoming calls on protocols where codecs are proposed when - starting the call (for example, <a - href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>), - the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - will contain information on the codecs that have already been - proposed by the remote contact, otherwise the codec map will - be the empty list.</p> - - <p>The streaming implementation should look at the remote codec - map and the codecs known by the local user and call - <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> - on the intersection of these two codec lists.</p> - - <p>This means that in practice, outgoing calls will have a codec - offer pop up with no information in the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, - so the local user will call <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> - with the list of all codecs supported. If this codec offer is - accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> - will fire with the details of the codecs passed into - <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If - the call is incoming, then the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - will contain details of the remote contact's codecs and the - local user will call <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> - with the codecs that both sides understand. After the codec - set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref> - will fire to signal this change.</p> - - <h4>Protocols without codec negotiation</h4> - - <p>For protocols where the codecs are not negotiable, instead of - popping up the initial content's <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object with an empty <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, - the CM should set the supported codec values to known codec - values in the said object's codec map.</p> - - <h4>Changing codecs mid-call</h4> - - <p>To update the codec list used mid-call, the - <tp:member-ref>UpdateCodecs</tp:member-ref> method should be - called with details of the new codec list. If this is - accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> - will be emitted with the new codec set.</p> - - <p>If the other side decides to update his or her codec list - during a call, a new <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object will appear through - <tp:member-ref>NewCodecOffer</tp:member-ref> which should be - acted on as documented above.</p> - - </tp:docstring> - - <tp:struct name="Codec" array-name="Codec_List"> - <tp:docstring> - A description of a codec. - </tp:docstring> - <tp:member name="Identifier" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Numeric identifier for the codec. This will be used as the PT in the - SDP or content description. - </tp:docstring> - </tp:member> - <tp:member name="Name" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The name of the codec. - </tp:docstring> - </tp:member> - <tp:member name="Clockrate" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The clockrate of the codec. - </tp:docstring> - </tp:member> - <tp:member name="Channels" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Number of channels of the codec if applicable, otherwise 0. - </tp:docstring> - </tp:member> - <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Extra parameters for this codec. - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Contact_Codec_Map"> - <tp:docstring> - A map from contact to the list of codecs he or she supports. - </tp:docstring> - <tp:member name="Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - A contact handle. - </tp:docstring> - </tp:member> - <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> - <tp:docstring> - The codecs that the contact supports. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:struct name="Codec_Offering"> - <tp:docstring> - A codec offer and its corresponding remote contact codec map. - </tp:docstring> - <tp:member name="Codec_Offer" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> - </tp:docstring> - </tp:member> - <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The contact handle that this codec offer applies to. - </tp:docstring> - </tp:member> - <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})" - tp:type="Codec[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property - of the codec offer. - </tp:docstring> - </tp:member> - </tp:struct> - - <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the codecs in use change.</p> - - <p>As well as acting as change notification for the - <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this - signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> - property has changed to <code>('/', {})</code>.</p> - </tp:docstring> - <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" - tp:type="Contact_Codec_Map"> - <tp:docstring> - A map from contact to his or her codecs. Each pair in this - map is added to the - <tp:member-ref>ContactCodecMap</tp:member-ref> property, - replacing any previous pair with that key. - </tp:docstring> - </arg> - <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of keys which were removed from the - <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because - those contacts left the call. - </tp:docstring> - </arg> - </signal> - - <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> - <tp:docstring> - Update the local codec mapping. This method should only be - used during an existing call to update the codec mapping. - </tp:docstring> - <arg name="Codecs" direction="in" - type="a(usuua{ss})" tp:type="Codec[]"> - <tp:docstring> - The codecs now supported by the local user. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Raised when a <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object exists and is referred to in the - <tp:member-ref>CodecOffer</tp:member-ref> property which - should be used instead of calling this method, or before - the content's initial <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object has appeared. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" - type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> - <tp:docstring> - <p>A map from contact handles (including the local user's own handle) - to the codecs supported by that contact.</p> - - <p>Change notification is via the - <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming - implementation MUST respond by calling the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >Accept</tp:dbus-ref> or <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >Reject</tp:dbus-ref> method on the codec offer object.</p> - - <p>Emission of this signal indicates that the - <tp:member-ref>CodecOffer</tp:member-ref> property has changed to - <code>(Contact, Offer, Codecs)</code>.</p> - </tp:docstring> - <arg name="Contact" type="u"> - <tp:docstring> - The contact the codec offer belongs to. - </tp:docstring> - </arg> - <arg name="Offer" type="o"> - <tp:docstring> - The object path of the new codec offer. This replaces any previous - codec offer. - </tp:docstring> - </arg> - <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property - of the codec offer.</p> - - <tp:rationale> - Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - property here saves a D-Bus round-trip - it shouldn't be - necessary to get the property from the CodecOffer object, in - practice. - </tp:rationale> - </tp:docstring> - </arg> - </signal> - - <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" - type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The object path to the current - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> object, its - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties. - If the object path is "/" then there isn't an outstanding - codec offer, and the mapping MUST be empty.</p> - - <tp:rationale> - Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >RemoteContact</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >RemoteContactCodecs</tp:dbus-ref> - properties here saves a D-Bus round-trip - it shouldn't be - necessary to get these properties from the CodecOffer object, in - practice. - </tp:rationale> - - <p>Change notification is via the - <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the - value of this property with a new codec offer), and - <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that - there is no longer any active codec offer) signals.</p> - </tp:docstring> - </property> - - <tp:enum name="Call_Content_Packetization_Type" type="u"> - <tp:added version="0.21.2"/> - <tp:docstring> - A packetization method that can be used for a content. - </tp:docstring> - - <tp:enumvalue suffix="RTP" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Real-time Transport Protocol, as documented by RFC 3550. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Raw" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Raw media. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="MSN_Webcam" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - MSN webcam. This is the video-only one-way type which was - used in earlier versions of WLM. Although no longer used, - modern WLM clients still support the MSN webcam protocol. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="Packetization" tp:name-for-bindings="Packetization" - type="u" tp:type="Call_Content_Packetization_Type" access="read" - tp:immutable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The packetization method in use for this content.</p> - </tp:docstring> - </property> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Content_Interface_Mute.xml b/qt4/spec/Call_Content_Interface_Mute.xml deleted file mode 100644 index f926e03cd..000000000 --- a/qt4/spec/Call_Content_Interface_Mute.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> -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. - -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. - -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. - </tp:license> - - <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental"> - <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for calls which may be muted. This only makes sense - for channels where audio or video is streaming between members.</p> - - <p>Muting a call content indicates that the user does not wish to send - outgoing audio or video.</p> - - <p>Although it's client's responsibility to actually mute the microphone - or turn off the camera, using this interface the client can also - inform the CM and other clients of that fact.</p> - - <tp:rationale> - For some protocols, the fact that the content is muted needs - to be transmitted to the peer; for others, the notification - to the peer is only informational (eg. XMPP), and some - protocols may have no notion of muting at all. - </tp:rationale> - </tp:docstring> - - <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> - <tp:docstring> - Emitted to indicate that the mute state has changed for this call content. - This may occur as a consequence of the client calling - <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another - client has (un)muted the content. - </tp:docstring> - <arg name="MuteState" type="b"> - <tp:docstring> - True if the content is now muted. - </tp:docstring> - </arg> - </signal> - - <property name="MuteState" type="b" - access="read" tp:name-for-bindings="Mute_State"> - <tp:docstring> - True if the content is muted. - </tp:docstring> - </property> - - <method name="SetMuted" tp:name-for-bindings="Set_Muted"> - <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed> - <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed> - <arg direction="in" name="Muted" type="b"> - <tp:docstring> - True if the client has muted the content. - </tp:docstring> - </arg> - <tp:docstring> - <p>Inform the CM that the call content has been muted or unmuted by - the client.</p> - - <p>It is the client's responsibility to actually mute or unmute the - microphone or camera used for the content. However, the client - MUST call this whenever it mutes or unmutes the content.</p> - </tp:docstring> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Content_Interface_Video_Control.xml b/qt4/spec/Call_Content_Interface_Video_Control.xml deleted file mode 100644 index b066de42b..000000000 --- a/qt4/spec/Call_Content_Interface_Video_Control.xml +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> -<node name="/Call_Content_Interface_Video_Control" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Content.Interface.VideoControl.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.10">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface that allows the connection manager to control the video - stream.</p> - <p>This interface is generally not needed. In cases where the connection - manager handles the network communication and the media is transferred - from the client to the connection manager via shared memory, it can - sometimes be beneficial for the connection manager to be able to - control certain aspects of the video stream.</p> - </tp:docstring> - - <signal name="KeyFrameRequested" tp:name-for-bindings="Key_Frame_Requested"> - <tp:docstring> - Request that the video encoder produce a new key frame as soon as - possible. - </tp:docstring> - </signal> - - <tp:struct name="Video_Resolution" - array-name="Video_Resolution_Struct"> - <tp:member type="u" name="Width"> - <tp:docstring> - With of the video stream. - </tp:docstring> - </tp:member> - <tp:member type="u" name="Height"> - <tp:docstring> - Height of the video stream. - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="VideoResolution" type="(uu)" tp:type="Video_Resolution" - access="read" tp:name-for-bindings="Video_Resolution"> - <tp:docstring> - The resolution at which the streaming engine should be sending. - - <p>Change notification is via the - <tp:member-ref>VideoResolutionChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="VideoResolutionChanged" - tp:name-for-bindings="Video_Resolution_Changed"> - <tp:docstring> - The desired video resolution has changed. - </tp:docstring> - <arg type="(uu)" tp:type="Video_Resolution" name="NewResolution" /> - </signal> - - <property name="Bitrate" type="u" access="read" - tp:name-for-bindings="Bitrate"> - <tp:docstring> - The bitrate the streaming engine should be sending at. - - <p>Change notification is via the - <tp:member-ref>BitrateChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="BitrateChanged" - tp:name-for-bindings="Bitrate_Changed"> - <tp:docstring> - The desired bitrate has changed - </tp:docstring> - <arg type="u" name="NewBitrate" /> - </signal> - - <property name="Framerate" type="u" access="read" - tp:name-for-bindings="Framerate"> - <tp:docstring> - The framerate the streaming engine should be sending at. - - <p>Change notification is via the - <tp:member-ref>FramerateChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="FramerateChanged" - tp:name-for-bindings="Framerate_Changed"> - <tp:docstring> - The desired framerate has changed - </tp:docstring> - <arg type="u" name="NewFramerate" /> - </signal> - - <property name="MTU" type="u" access="read" - tp:name-for-bindings="MTU"> - <tp:docstring> - The Maximum Transmission Unit - - <p>Change notification is via the - <tp:member-ref>MTUChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="MTUChanged" tp:name-for-bindings="MTU_Changed"> - <tp:docstring> - The Maximum Transmission Unit has changed - </tp:docstring> - <arg type="u" name="NewMTU" /> - </signal> - - <property name="ManualKeyFrames" type="b" access="read" - tp:name-for-bindings="Manual_Key_Frames"> - <tp:docstring> - Only send key frames when manually requested - </tp:docstring> - </property> - </interface> -</node> diff --git a/qt4/spec/Call_Stream.xml b/qt4/spec/Call_Stream.xml deleted file mode 100644 index 1d7b28147..000000000 --- a/qt4/spec/Call_Stream.xml +++ /dev/null @@ -1,261 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Stream" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Stream.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - One stream inside a <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. - </tp:docstring> - - <method name="SetSending" tp:name-for-bindings="Set_Sending"> - <tp:docstring> - Set the stream to start or stop sending media from the local - user to other contacts. - </tp:docstring> - - <arg name="Send" type="b" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If True, the - <tp:member-ref>LocalSendingState</tp:member-ref> should - change to <tp:type>Sending_State</tp:type>_Sending, if it isn't - already.</p> - - <p>If False, the - <tp:member-ref>LocalSendingState</tp:member-ref> should - change to <tp:type>Sending_State</tp:type>_None, if it isn't - already.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" /> - </tp:possible-errors> - </method> - - <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving"> - <tp:docstring> - <p>Request that a remote contact stops or starts sending on - this stream.</p> - - <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref> - property defines whether the protocol allows the local user to - request the other side start sending on this stream.</p> - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Contact from which sending is requested</p> - </tp:docstring> - </arg> - - <arg name="Receive" type="b" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, request that the given contact starts to send media. - If false, request that the given contact stops sending media.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The request contact is valid but is not involved in this - stream. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The protocol does not allow the local user to request the - other side starts sending on this stream. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="RemoteMembersChanged" - tp:name-for-bindings="Remote_Members_Changed"> - <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed> - <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes. - </tp:docstring> - - <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map"> - <tp:docstring> - A mapping from channel-specific handles to their updated sending - state, whose keys include at least the members who were added, - and the members whose states changed. - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The channel-specific handles that were removed from the keys - of the <tp:member-ref>RemoteMembers</tp:member-ref> - property, as a result of the contact leaving this stream - </tp:docstring> - </arg> - </signal> - - <signal name="LocalSendingStateChanged" - tp:name-for-bindings="Local_Sending_State_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes. - </tp:docstring> - - <arg name="State" type="u" tp:type="Sending_State"> - <tp:docstring> - The new value of - <tp:member-ref>LocalSendingState</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <tp:enum name="Sending_State" type="u"> - <tp:docstring> - Enum indicating whether a contact is sending media. - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - The contact is not sending media and has not been asked to - do so. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Pending_Send" value="1"> - <tp:docstring> - The contact has been asked to start sending media. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Sending" value="2"> - <tp:docstring> - The contact is sending media. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Pending_Stop_Sending" value="3"> - <tp:docstring> - The contact has been asked to stop sending media. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:mapping name="Contact_Sending_State_Map"> - <tp:docstring> - A map from a contact to his or her sending state. - </tp:docstring> - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact handle. - </tp:docstring> - </tp:member> - <tp:member name="Sending" type="u" tp:type="Sending_State"> - <tp:docstring> - The sending state of the contact. - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> - <tp:added version="0.19.11"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra interfaces provided by this stream, such as <tp:dbus-ref - namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>. - This SHOULD NOT include the Stream interface itself, and cannot - change once the stream has been created.</p> - </tp:docstring> - </property> - - <property name="RemoteMembers" tp:name-for-bindings="Remote_Members" - type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> - <tp:changed version="0.21.2">renamed from Senders</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from remote contacts to their sending state. The - local user's sending state is shown in - <tp:member-ref>LocalSendingState</tp:member-ref>.</p> - - <p><tp:type>Sending_State</tp:type>_Pending_Send indicates - that another contact has asked the local user to send - media.</p> - - <p>Other contacts' handles in this map indicate whether they are - sending media to the contacts in this stream. - Sending_State_Pending_Send indicates contacts who are not sending but - have been asked to do so.</p> - </tp:docstring> - </property> - - <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State" - type="u" access="read" tp:type="Sending_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The local user's sending state. Media sent on this stream - should be assumed to be received, directly or indirectly, by - every other contact in the - <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change - notification is given via the - <tp:member-ref>LocalSendingStateChanged</tp:member-ref> - signal.</p> - - <tp:rationale> - Implementations of the first Call draft had the self handle - in the <tp:member-ref>RemoteMembers</tp:member-ref> (then - called Members) map and this showed that it's annoying - having to keep track of the self handle so that it can be - special-cased. - </tp:rationale> - - <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for - this property indicates that the other side requested the - local user start sending media, which can be done by calling - <tp:member-ref>SetSending</tp:member-ref>. When a call is - accepted, all initial contents with streams that have a - local sending state of - <tp:type>Sending_State</tp:type>_Pending_Send are - automatically set to sending. For example, on an incoming - call it means you need to <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - to start the actual call, on an outgoing call it might mean - you need to call <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - before actually starting the call.</p> - </tp:docstring> - </property> - - <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving" - type="b" access="read" tp:immutable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, the user can request that a remote contact starts - sending on this stream.</p> - - <tp:rationale>Not all protocols allow the user to ask the - other side to start sending media.</tp:rationale> - </tp:docstring> - </property> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Stream_Endpoint.xml b/qt4/spec/Call_Stream_Endpoint.xml deleted file mode 100644 index cf1783d1e..000000000 --- a/qt4/spec/Call_Stream_Endpoint.xml +++ /dev/null @@ -1,182 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Stream_Endpoint" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Stream.Endpoint.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This object represents an endpoint for a stream. In a one-to-one - call, there will be one (bidirectional) stream per content and - one endpoint per stream (as there is only one remote - contact). In a multi-user call there is a stream for each remote - contact and each stream has one endpoint as it refers to the one - physical machine on the other end of the stream.</p> - - <p>The multiple endpoint use case appears when SIP call forking - is used. Unlike jingle call forking (which is just making - multiple jingle calls to different resources appear as one - call), SIP call forking is actually done at the server so you - have one stream to the remote contact and then and endpoint for - each SIP client to be called.</p> - </tp:docstring> - - <property name="RemoteCredentials" - tp:name-for-bindings="Remote_Credentials" - type="(ss)" tp:type="Stream_Credentials" access="read"> - <tp:docstring> - The ICE credentials used for all candidates. If each candidate - has different credentials, then this property SHOULD be ("", - ""). Per-candidate credentials are set in the - <tp:type>Candidate</tp:type>'s - <tp:type>Candidate_Info</tp:type> a{sv}. - </tp:docstring> - </property> - - <signal name="RemoteCredentialsSet" - tp:name-for-bindings="Remote_Credentials_Set"> - <arg name="Username" type="s"> - <tp:docstring> - The username set. - </tp:docstring> - </arg> - <arg name="Password" type="s"> - <tp:docstring> - The password set. - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the remote ICE credentials for the endpoint are - set. If each candidate has different credentials, then this - signal will never be fired. - </tp:docstring> - </signal> - - <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates" - type="a(usua{sv})" tp:type="Candidate[]" access="read"> - <tp:docstring> - A list of candidates for this endpoint. - </tp:docstring> - </property> - - <signal name="RemoteCandidatesAdded" - tp:name-for-bindings="Remote_Candidates_Added"> - <tp:docstring> - Emitted when remote candidates are added to the - <tp:member-ref>RemoteCandidates</tp:member-ref> property. - </tp:docstring> - <arg name="Candidates" - type="a(usua{sv})" tp:type="Candidate[]"> - <tp:docstring> - The candidates that were added. - </tp:docstring> - </arg> - </signal> - - <signal name="CandidateSelected" - tp:name-for-bindings="Candidate_Selected"> - <tp:docstring> - Emitted when a candidate is selected for use in the stream. - </tp:docstring> - <arg name="Candidate" - type="(usua{sv})" tp:type="Candidate"> - <tp:docstring> - The candidate that has been selected. - </tp:docstring> - </arg> - </signal> - - <property name="SelectedCandidate" - tp:name-for-bindings="Selected_Candidate" - type="(usua{sv})" tp:type="Candidate" access="read"> - <tp:docstring> - The candidate that has been selected for use to stream packets - to the remote contact. Change notification is given via the - the <tp:member-ref>CandidateSelected</tp:member-ref> signal. - </tp:docstring> - </property> - - <method name="SetSelectedCandidate" - tp:name-for-bindings="Set_Selected_Candidate"> - <tp:docstring> - Set the value of - <tp:member-ref>CandidateSelected</tp:member-ref>. - </tp:docstring> - <arg name="Candidate" - type="(usua{sv})" tp:type="Candidate" direction="in"> - <tp:docstring> - The candidate that has been selected. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - </tp:possible-errors> - </method> - - <property name="StreamState" tp:name-for-bindings="Stream_State" - type="u" tp:type="Media_Stream_State" - access="read"> - <tp:docstring> - The stream state of the endpoint. - </tp:docstring> - </property> - - <signal name="StreamStateChanged" - tp:name-for-bindings="Stream_State_Changed"> - <tp:docstring> - Emitted when the <tp:member-ref>StreamState</tp:member-ref> - property changes. - </tp:docstring> - <arg name="state" type="u" tp:type="Media_Stream_State"> - <tp:docstring> - The new <tp:member-ref>StreamState</tp:member-ref> value. - </tp:docstring> - </arg> - </signal> - - <method name="SetStreamState" - tp:name-for-bindings="Set_Stream_State"> - <tp:docstring> - Change the <tp:member-ref>StreamState</tp:member-ref> of the - endpoint. - </tp:docstring> - <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"> - <tp:docstring> - The requested stream state. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <property name="Transport" tp:name-for-bindings="Transport" - type="u" tp:type="Stream_Transport_Type" access="read"> - <tp:docstring> - The transport type for the stream endpoint. - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Call_Stream_Interface_Media.xml b/qt4/spec/Call_Stream_Interface_Media.xml deleted file mode 100644 index 54476f0fa..000000000 --- a/qt4/spec/Call_Stream_Interface_Media.xml +++ /dev/null @@ -1,473 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Stream_Interface_Media" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Stream.Interface.Media.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - [FIXME] - - <h4>ICE restarts</h4> - - <p>If the <tp:dbus-ref - namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref> - signal is fired during a call once it has been called before - whilst setting up the call for initial use, and the - credentials have changed, then there has been an ICE - restart. In such a case, the CM SHOULD also empty the remote - candidate list in the <tp:dbus-ref - namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p> - - <p>If the CM does an ICE restart, then the - <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is - emitted and the streaming implementation should then call - <tp:member-ref>SetCredentials</tp:member-ref> again.</p> - - <p>For more information on ICE restarts see - <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245 - section 9.1.1.1</a></p> - </tp:docstring> - - <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Used to set the username fragment and password for streams that have - global credentials.</p> - </tp:docstring> - <arg name="Username" type="s" direction="in"> - <tp:docstring> - The username to use when authenticating on the stream. - </tp:docstring> - </arg> - <arg name="Password" type="s" direction="in"> - <tp:docstring> - The password to use when authenticating on the stream. - </tp:docstring> - </arg> - </method> - - <tp:mapping name="Candidate_Info"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra information about the candidate. Allowed and mandatory keys - depend on the transport protocol used. The following keys are commenly - used:</p> - - <dl> - <dt>Type (u)</dt> - <dd>type of candidate (host, srflx, prflx, relay)</dd> - - <dt>Foundation (s)</dt> - <dd>the foundation of this candiate</dd> - - <dt>Protocol (u) </dt> - <dd>Underlying protocol of the candidate (udp, tcp) </dd> - - <dt>Priority (u) </dt> - <dd>Priority of the candidate </dd> - - <dt>BaseIP (u) </dt> - <dd>Base IP of this candidate </dd> - - <dt>Username (s) </dt> - <dd>Username of this candidate - (only if credentials are per candidate)</dd> - - <dt>Password (s) </dt> - <dd>Password of this candidate - (only if credentials are per candidate)</dd> - - <dt>RawUDPFallback (b) </dt> - <dd>Indicate whether this candidate may be used to provide a UDP - fallback</dd> - </dl> - </tp:docstring> - <tp:member name="Key" type="s"> - <tp:docstring>One of the well-known keys documented here, or an - implementation-specific key.</tp:docstring> - </tp:member> - <tp:member name="Value" type="v"> - <tp:docstring>The value corresponding to that key.</tp:docstring> - </tp:member> - </tp:mapping> - - <tp:enum type="u" name="Stream_Component"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Media streams can use more than one UDP socket: one for RTP (data) - and one for RTCP (control). Most of the time, they are adjacent - to each other, but some protocols (xmpp) signal each port separately. - </tp:docstring> - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - The stream transport type is unknown or not applicable - (should not appear over dbus). - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Data" value="1"> - <tp:docstring> - This is the high-traffic data socket, containing the audio/video - data for the stream. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Control" value="2"> - <tp:docstring> - This is the low-traffic control socket, usually containing feedback - about packet loss etc. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Candidate" array-name="Candidate_List"> - <tp:docstring>A Stream Candidate.</tp:docstring> - <tp:member name="Component" type="u" tp:type="Stream_Component"> - <tp:docstring>The component number.</tp:docstring> - </tp:member> - <tp:member name="IP" type="s"> - <tp:docstring>The IP address to use.</tp:docstring> - </tp:member> - <tp:member name="Port" type="u"> - <tp:docstring>The port number to use.</tp:docstring> - </tp:member> - <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info"> - <tp:docstring>Additional information about the candidate.</tp:docstring> - </tp:member> - </tp:struct> - - <method name="AddCandidates" tp:name-for-bindings="Add_Candidates"> - <tp:docstring> - Add candidates to the - <tp:member-ref>LocalCandidates</tp:member-ref> property and - signal them to the remote contact(s). - </tp:docstring> - <arg name="Candidates" direction="in" - type="a(usua{sv})" tp:type="Candidate[]"> - <tp:docstring> - The candidates to be added. - </tp:docstring> - </arg> - </method> - - <method name="CandidatesPrepared" - tp:name-for-bindings="Candidates_Prepared"> - <tp:docstring> - This indicates to the CM that the initial batch of candidates - has been added. - </tp:docstring> - </method> - - <tp:enum type="u" name="Stream_Transport_Type"> - <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A transport that can be used for streaming. - </tp:docstring> - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - The stream transport type is unknown or not applicable - (for streams that do not have a configurable transport). - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Raw_UDP" value="1"> - <tp:docstring> - Raw UDP, with or without STUN. All streaming clients are assumed to - support this transport, so there is no handler capability token for - it in the <tp:dbus-ref namespace="ofdT.Channel.Type" - >Call.DRAFT</tp:dbus-ref> interface. - [This corresponds to "none" or "stun" in the old Media.StreamHandler - interface.] - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="ICE" value="2"> - <tp:docstring> - Interactive Connectivity Establishment, as defined by RFC - 5245. Note that this value covers ICE-UDP only. - [This corresponds to "ice-udp" in the old - Media.StreamHandler interface.] - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="GTalk_P2P" value="3"> - <tp:docstring> - Google Talk peer-to-peer connectivity establishment, as implemented - by libjingle 0.3. - [This corresponds to "gtalk-p2p" in the old Media.StreamHandler - interface.] - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="WLM_2009" value="4"> - <tp:docstring> - The transport used by Windows Live Messenger 2009 or later, which - resembles ICE draft 19. - [This corresponds to "wlm-2009" in the old Media.StreamHandler - interface.] - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="SHM" value="5"> - <tp:added version="0.21.2"/> - <tp:docstring> - Shared memory transport, as implemented by the GStreamer - shmsrc and shmsink plugins. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Multicast" value="6"> - <tp:added version="0.21.5"/> - <tp:docstring> - Multicast transport. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="Transport" tp:name-for-bindings="Transport" - type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes"> - <tp:docstring> - The transport for this stream. - </tp:docstring> - </property> - - <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates" - type="a(usua{sv})" tp:type="Candidate[]" access="read"> - <tp:docstring> - [FIXME]. Change notification is via the - <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal. - </tp:docstring> - </property> - - <signal name="LocalCandidatesAdded" - tp:name-for-bindings="Local_Candidates_Added"> - <tp:docstring> - Emitted when local candidates are added to the - <tp:member-ref>LocalCandidates</tp:member-ref> property. - </tp:docstring> - <arg name="Candidates" type="a(usua{sv})" tp:type="Candidate[]"> - <tp:docstring> - Candidates that have been added. - </tp:docstring> - </arg> - </signal> - - <tp:struct name="Stream_Credentials"> - <tp:docstring>A username and password pair.</tp:docstring> - - <tp:member name="Username" type="s"> - <tp:docstring>The username.</tp:docstring> - </tp:member> - - <tp:member name="Password" type="s"> - <tp:docstring>The password.</tp:docstring> - </tp:member> - </tp:struct> - - <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" - type="(ss)" tp:type="Stream_Credentials" access="read"> - <tp:docstring> - [FIXME]. Change notification is via the - <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal. - </tp:docstring> - </property> - - <signal name="LocalCredentialsChanged" - tp:name-for-bindings="Local_Credentials_Changed"> - <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed> - <tp:docstring> - Emitted when the value of - <tp:member-ref>LocalCredentials</tp:member-ref> changes. - </tp:docstring> - <arg name="Username" type="s" /> - <arg name="Password" type="s" /> - </signal> - - <signal name="RelayInfoChanged" - tp:name-for-bindings="Relay_Info_Changed"> - <tp:docstring> - Emitted when the value of - <tp:member-ref>RelayInfo</tp:member-ref> changes. - </tp:docstring> - <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" /> - </signal> - - <signal name="STUNServersChanged" - tp:name-for-bindings="STUN_Servers_Changed"> - <tp:docstring> - Emitted when the value of - <tp:member-ref>STUNServers</tp:member-ref> changes. - </tp:docstring> - <arg name="Servers" type="a(sq)" tp:type="Socket_Address_IP[]" /> - </signal> - - <property name="STUNServers" tp:name-for-bindings="STUN_Servers" - type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The IP addresses of possible STUN servers to use for NAT - traversal, as dotted-quad IPv4 address literals or RFC2373 - IPv6 address literals. Change notification is via the - <tp:member-ref>STUNServersChanged</tp:member-ref> - signal. The IP addresses MUST NOT be given as DNS hostnames.</p> - - <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="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>Transport</tp:member-ref> property: if - Transport is ICE, <code>tls</code> means - TLS over TCP as referenced by ICE draft 19, and if - Transport is GTalk_P2P, <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>Transport</tp:member-ref> - property. If Transport is ICE, this is a TURN server; - if Transport 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>Change notification is given via the - <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="ServerInfoRetrieved" - tp:name-for-bindings="Server_Info_Retrieved"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Signals that the initial information about STUN and Relay servers - has been retrieved, i.e. the - <tp:member-ref>HasServerInfo</tp:member-ref> property is - now true.</p> - </tp:docstring> - </signal> - - <property name="HasServerInfo" type="b" - tp:name-for-bindings="Has_Server_Info" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if all the initial information about STUN servers and Relay - servers has been retrieved. Change notification is via the - <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p> - - <tp:rationale> - Streaming implementations that can't cope with STUN and - relay servers being added later SHOULD wait for this - property to become true before proceeding. - </tp:rationale> - </tp:docstring> - </property> - - <signal name="EndpointsChanged" - tp:name-for-bindings="Endpoints_Changed"> - <tp:docstring> - Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property - changes. - </tp:docstring> - <arg name="Endpoints_Added" type="ao"> - <tp:docstring> - Endpoints that were added. - </tp:docstring> - </arg> - <arg name="Endpoints_Removed" type="ao"> - <tp:docstring> - Endpoints that no longer exist. - </tp:docstring> - </arg> - </signal> - - <property name="Endpoints" tp:name-for-bindings="Endpoints" - type="ao" access="read"> - <tp:docstring> - <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream" - >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this - stream.</p> - - <p>Change notification is via the - <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="PleaseRestartICE" - tp:name-for-bindings="Please_Restart_ICE"> - <tp:docstring> - Emitted when the CM does an ICE restart to notify the - streaming implementation that it should call - <tp:member-ref>SetCredentials</tp:member-ref> again. - </tp:docstring> - </signal> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel.xml b/qt4/spec/Channel.xml deleted file mode 100644 index 11d3e509c..000000000 --- a/qt4/spec/Channel.xml +++ /dev/null @@ -1,557 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2006 INdT</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel"> - - <property name="ChannelType" type="s" tp:type="DBus_Interface" - access="read" tp:name-for-bindings="Channel_Type"> - <tp:added version="0.17.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel's type. This cannot change once the channel has - been created.</p> - - <p>For compatibility between older connection managers and newer - clients, if this is unavailable or is an empty string, - clients MUST use the result of calling - <tp:member-ref>GetChannelType</tp:member-ref>.</p> - - <tp:rationale> - The GetAll method lets clients retrieve all properties in one - round-trip, which is desirable. - </tp:rationale> - - <p>When requesting a channel, the request MUST specify a channel - type, and the request MUST fail if the specified channel type - cannot be supplied.</p> - - <tp:rationale> - Common sense. - </tp:rationale> - </tp:docstring> - </property> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read"> - <tp:added version="0.17.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra interfaces provided by this channel. This SHOULD NOT include - the channel type and the Channel interface itself, and cannot - change once the channel has been created.</p> - - <p>For compatibility between older connection managers and newer - clients, if this is unavailable, or if this is an empty list and - <tp:member-ref>ChannelType</tp:member-ref> is an empty string, - clients MUST use the result of calling - <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an - empty list but ChannelType is non-empty, clients SHOULD NOT call - GetInterfaces; this implies that connection managers that implement - the ChannelType property MUST also implement the Interfaces property - correctly.</p> - - <tp:rationale> - The GetAll method lets clients retrieve all properties in one - round-trip, which is desirable. - </tp:rationale> - - <p>When requesting a channel with a particular value for this - property, the request must fail without side-effects unless the - connection manager expects to be able to provide a channel whose - interfaces include at least the interfaces requested.</p> - </tp:docstring> - </property> - - <property name="TargetHandle" type="u" access="read" tp:type="Handle" - tp:name-for-bindings="Target_Handle"> - <tp:added version="0.17.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The handle (a representation for the identifier) of the contact, - chatroom, etc. with which this handle communicates. Its type - is given by the <tp:member-ref>TargetHandleType</tp:member-ref> - property.</p> - - <p>This is fixed for the lifetime of the channel, so channels which - could potentially be used to communicate with multiple contacts, - and do not have an identity of their own (such as a Handle_Type_Room - handle), must have TargetHandleType set to Handle_Type_None and - TargetHandle set to 0.</p> - - <p>Unlike in the telepathy-spec 0.16 API, there is no particular - uniqueness guarantee - there can be many channels with the same - (channel type, handle type, handle) tuple. This is necessary - to support conversation threads in XMPP and SIP, for example.</p> - - <p>If this is present in a channel request, it must be nonzero, - <tp:member-ref>TargetHandleType</tp:member-ref> - MUST be present and not Handle_Type_None, and - <tp:member-ref>TargetID</tp:member-ref> MUST NOT be - present. Properties from - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> - MUST NOT be present.</p> - - <p>The channel that satisfies the request MUST either:</p> - - <ul> - <li>have the specified TargetHandle property; or</li> - <li>have <tp:member-ref>TargetHandleType</tp:member-ref> = - Handle_Type_None, TargetHandle = 0, and be configured such that - it could communicate with the specified handle in some other way - (e.g. have the requested contact handle in its Group - interface)</li> - </ul> - </tp:docstring> - </property> - - <property name="TargetID" tp:name-for-bindings="Target_ID" - type="s" access="read"> - <tp:added version="0.17.9"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The string that would result from inspecting the - <tp:member-ref>TargetHandle</tp:member-ref> - property (i.e. the identifier in the IM protocol of the contact, - room, etc. with which this channel communicates), or the empty - string if the TargetHandle is 0.</p> - - <tp:rationale> - <p>The presence of this property avoids the following race - condition:</p> - - <ul> - <li>New channel C is signalled with target handle T</li> - <li>Client calls <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, - [T])</li> - <li>Channel C closes, removing the last reference to handle T</li> - <li><tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, - [T]) returns an error</li> - </ul> - </tp:rationale> - - <p>If this is present in a channel request, - <tp:member-ref>TargetHandleType</tp:member-ref> - MUST be present and not Handle_Type_None, and - <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be - present. Properties from - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> - MUST NOT be present.The request MUST fail with error InvalidHandle, - without side-effects, if the requested TargetID would not be - accepted by - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p> - - <p>The returned channel must be related to the handle corresponding - to the given identifier, in the same way as if TargetHandle - had been part of the request instead.</p> - - <tp:rationale> - <p>Requesting channels with a string identifier saves a round-trip - (the call to RequestHandles). It also allows the channel - dispatcher to accept a channel request for an account that is not - yet connected (and thus has no valid handles), bring the account - online, and pass on the same parameters to the new connection's - CreateChannel method.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="TargetHandleType" type="u" access="read" - tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type"> - <tp:added version="0.17.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p> - - <p>If this is omitted from a channel request, connection managers - SHOULD treat this as equivalent to Handle_Type_None.</p> - - <p>If this is omitted or is Handle_Type_None, - <tp:member-ref>TargetHandle</tp:member-ref> and - <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the - request.</p> - </tp:docstring> - </property> - - <method name="Close" tp:name-for-bindings="Close"> - <tp:docstring> - Request that the channel be closed. This is not the case until - the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and - depending on the connection - manager this may simply remove you from the channel on the server, - rather than causing it to stop existing entirely. Some channels - such as contact list channels may not be closed. - </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.NotImplemented"> - <tp:docstring> - This channel may never be closed, e.g. a contact list - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This channel is not currently in a state where it can be closed, - e.g. a non-empty user-defined contact group - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="Closed" tp:name-for-bindings="Closed"> - <tp:docstring> - Emitted when the channel has been closed. Method calls on the - channel are no longer valid after this signal has been emitted, - and the connection manager may then remove the object from the bus - at any point. - </tp:docstring> - </signal> - - <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type"> - <tp:deprecated version="0.17.7">Use the ChannelType - property if possible.</tp:deprecated> - <arg direction="out" type="s" tp:type="DBus_Interface" - name="Channel_Type"> - <tp:docstring>The interface name</tp:docstring> - </arg> - <tp:docstring> - Returns the interface name for the type of this channel. Clients - SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property - instead, falling back to this method only if necessary. - - <tp:rationale> - The GetAll method lets clients retrieve all properties in one - round-trip. - </tp:rationale> - </tp:docstring> - </method> - - <method name="GetHandle" tp:name-for-bindings="Get_Handle"> - <tp:deprecated version="0.17.7">Use the TargetHandleType - and TargetHandle properties if possible.</tp:deprecated> - <arg direction="out" type="u" tp:type="Handle_Type" - name="Target_Handle_Type"> - <tp:docstring> - The same as TargetHandleType. - </tp:docstring> - </arg> - <arg direction="out" type="u" tp:type="Handle" name="Target_Handle"> - <tp:docstring> - The same as TargetHandle. - </tp:docstring> - </arg> - <tp:docstring> - Returns the handle type and number if this channel represents a - communication with a particular contact, room or server-stored list, or - zero if it is transient and defined only by its contents. Clients - SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and - <tp:member-ref>TargetHandleType</tp:member-ref> properties instead, - falling back to this method only if necessary. - - <tp:rationale> - The GetAll method lets clients retrieve all properties in one - round-trip. - </tp:rationale> - </tp:docstring> - </method> - - <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> - <tp:deprecated version="0.17.7">Use the Interfaces - property if possible.</tp:deprecated> - <arg direction="out" type="as" tp:type="DBus_Interface[]" - name="Interfaces"> - <tp:docstring> - An array of the D-Bus interface names - </tp:docstring> - </arg> - <tp:docstring> - Get the optional interfaces implemented by the channel. - Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref> - property instead, falling back to this method only if necessary. - - <tp:rationale> - The GetAll method lets clients retrieve all properties in one - round-trip. - </tp:rationale> - </tp:docstring> - </method> - - <property name="Requested" tp:name-for-bindings="Requested" - type="b" access="read"> - <tp:added version="0.17.13">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if this channel was created in response to a local request, - such as a call to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> - or - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p> - - <tp:rationale> - <p>The idea of this property is to distinguish between "incoming" - and "outgoing" channels, in a way that doesn't break down when - considering special cases like contact lists that are automatically - created on connection to the server, or chatrooms that an - IRC proxy/bouncer like irssi-proxy or bip was already in.</p> - - <p>The reason we want to make that distinction is that UIs for - things that the user explicitly requested should start up - automatically, whereas for incoming messages and VoIP calls we - should first ask the user whether they want to open the messaging - UI or accept the call.</p> - </tp:rationale> - - <p>If the channel was not explicitly requested (even if it was - created as a side-effect of a call to one of those functions, - e.g. because joining a Tube in a MUC context on XMPP implies - joining that MUC), then this property is false.</p> - - <p>For compatibility with older connection managers, clients SHOULD - assume that this property is true if they see a channel announced - by the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> - signal with the suppress_handler parameter set to true.</p> - - <tp:rationale> - <p>In a correct connection manager, the only way to get such a - channel is to request it.</p> - </tp:rationale> - - <p>Clients MAY additionally assume that this property is false - if they see a channel announced by the NewChannel signal with the - suppress_handler parameter set to false.</p> - - <tp:rationale> - <p>This is more controversial, since it's possible to get that - parameter set to false by requesting a channel. However, there's - no good reason to do so, and we've deprecated this practice.</p> - - <p>In the particular case of the channel dispatcher, the only - side-effect of wrongly thinking a channel is unrequested - is likely to be that the user has to confirm that they want to - use it, so it seems fairly harmless to assume in the channel - dispatcher that channels with suppress_handler false are - indeed unrequested.</p> - </tp:rationale> - - <p>It does not make sense for this property to be in channel - requests—it will always be true for channels returned by - CreateChannel, and callers of EnsureChannel cannot control whether an - existing channel was originally requested locally—so it MUST NOT - be accepted.</p> - </tp:docstring> - </property> - - <property name="InitiatorHandle" type="u" tp:type="Contact_Handle" - access="read" tp:name-for-bindings="Initiator_Handle"> - <tp:added version="0.17.13">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contact who initiated the channel; for instance, the contact - who invited the local user to a chatroom, or the contact who - initiated a call.</p> - - <p>This does <em>not</em> necessarily represent the contact who - created the underlying protocol-level construct. For instance, if - Rob creates a chatroom, Will joins that chatroom, and Will invites Simon - to join it, then Simon will see Will as the InitiatorHandle of the - channel representing the chatroom.</p> - - <tp:rationale> - <p>The room creator is generally a less useful piece of information - than the inviter, is less likely to be available at invitation - time (i.e. can't necessarily be an immutable property), and is - less likely to be available at all. The creator of a chatroom - is not currently available via Telepathy; if added in future, it - is likely to be made available as a property on the Chatroom - interface (<a - href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p> - </tp:rationale> - - <p>For channels requested by the - local user, this MUST be the value of - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref> - at the time the channel was created (i.e. not a channel-specific - handle).</p> - - <tp:rationale> - <p>On some protocols, the SelfHandle may change (as signalled by - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>), - but this property is immutable. Hence, locally-requested channels' - InitiatorHandle and InitiatorID may not match the current - SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to - determine whether the channel was created locally.</p> - </tp:rationale> - - <p>For channels requested by a remote user, this MUST be their handle. - If unavailable or not applicable, this MUST be 0 (for instance, - contact lists are not really initiated by anyone in particular, and - it's easy to imagine a protocol where chatroom invitations can be - anonymous).</p> - - <p>For channels with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> - interface, this SHOULD be the same - contact who is signalled as the "Actor" causing the self-handle - to be placed in the local-pending set.</p> - - <p>This SHOULD NOT be a channel-specific handle, if possible.</p> - - <p>It does not make sense for this property to be in channel - requests - the initiator will always be the local user - so it - MUST NOT be accepted.</p> - </tp:docstring> - </property> - - <property name="InitiatorID" type="s" access="read" - tp:name-for-bindings="Initiator_ID"> - <tp:added version="0.17.13">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The string that would result from inspecting the - <tp:member-ref>InitiatorHandle</tp:member-ref> - property (i.e. the initiator's identifier in the IM protocol).</p> - - <tp:rationale> - <p>The presence of this property avoids the following race - condition:</p> - - <ul> - <li>New StreamedMedia channel C is signalled with initiator - handle I</li> - <li>Client calls <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, - [I])</li> - <li>Channel C closes, removing the last reference to handle I</li> - <li><tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, - [I]) returns an error</li> - <li>Client can indicate that a call was missed, but not who - called!</li> - </ul> - </tp:rationale> - - <p>It does not make sense for this property to be in channel - requests - the initiator will always be the local user - so it - MUST NOT be accepted.</p> - </tp:docstring> - </property> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>All communication in the Telepathy framework is carried out via channel - objects which are created and managed by connections. This interface must - be implemented by all channel objects, along with one single channel type, - such as <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref> - which represents a list of people (such as a buddy list) or <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which - represents a channel over which textual messages are sent and received.</p> - - <p>Each Channel's object path MUST start with the object path of - its associated <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed - by '/'. There MAY be any number of additional object-path components, - which clients MUST NOT attempt to parse.</p> - - <tp:rationale> - <p>This ensures that Channel object paths are unique, even between - Connections and CMs, because Connection object paths are - guaranteed-unique via their link to the well-known bus name.</p> - - <p>If all connection managers in use are known to comply with at least - spec version 0.17.10, then the Connection's object path can - even be determined from the Channel's without any additional - information, by taking the first 7 components.</p> - </tp:rationale> - - <p>Each channel has a number of immutable properties (which cannot vary - after the channel has been announced with <tp:dbus-ref - namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>), - provided to clients in the - <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>, - <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and - <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref> - methods to permit immediate identification of the channel. This interface - contains immutable properties common to all channels. In brief:</p> - - <ul> - <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of - communication carried out on this channel;</li> - <li><tp:member-ref>TargetHandleType</tp:member-ref>, - <tp:member-ref>TargetHandle</tp:member-ref> and - <tp:member-ref>TargetID</tp:member-ref> specify the entity with which - this channel communicates, such as the other party in a 1-1 call, or - the name of a multi-user chat room;</li> - <li><tp:member-ref>InitiatorHandle</tp:member-ref> and - <tp:member-ref>InitiatorID</tp:member-ref> specify who created this - channel;</li> - <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local - user requested this channel, or whether it is an incoming call, a text - conversation started by a remote contact, a chatroom invitation, - etc.</li> - </ul> - - <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be - implemented to indicate other available - functionality, such as <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> - if the channel contains a number of contacts, <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref> - to indicate that a channel may have a password set to require entry, and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref> - for typing notifications. The interfaces implemented may not vary after - the channel has been created. These other interfaces (along with the - interface named by <tp:member-ref>ChannelType</tp:member-ref>) may - themselves specify immutable properties to be announced up-front along - with the properties on this interface.</p> - - <p>Some channels are “anonymous”, with - <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>, - which indicates that the channel is defined by some other properties. For - instance, transient ad-hoc chat rooms may be defined only by their members (as visible - through the <tp:dbus-ref - namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> - interface), and <tp:dbus-ref - namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref> - channels represent a single search attempt for a particular <tp:dbus-ref - namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p> - - <p>Specific connection manager implementations may implement channel types and - interfaces which are not contained within this specification in order to - support further functionality. To aid interoperability between client and - connection manager implementations, the interfaces specified here should be - used wherever applicable, and new interfaces made protocol-independent - wherever possible. Because of the potential for 3rd party interfaces adding - methods or signals with conflicting names, the D-Bus interface names should - always be used to invoke methods and bind signals.</p> - </tp:docstring> - - <tp:changed version="0.17.7">Previously we guaranteed that, for - any handle type other than Handle_Type_None, and for any channel type - and any handle, there would be no more than one channel with that - combination of channel type, handle type and handle. This guarantee - has now been removed in order to accommodate features like message - threads. - </tp:changed> - - <tp:changed version="0.17.10">Previously we did not explicitly - guarantee that Channels' object paths had the Connection's object path - as a prefix. - </tp:changed> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Bundle.xml b/qt4/spec/Channel_Bundle.xml deleted file mode 100644 index d211525a4..000000000 --- a/qt4/spec/Channel_Bundle.xml +++ /dev/null @@ -1,48 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Bundle" - 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: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.ChannelBundle.DRAFT" - tp:causes-havoc="experimental"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A group of related channels, which should all be dispatched to the - same handler if possible.</p> - - <p>Bundles currently have no functionality of their own, so clients - SHOULD NOT examine this interface, but should instead treat the - bundle object-path as an opaque identifier. If more functionality is - added to bundles in future, this interface will be used for capability - discovery.</p> - - <p>The lifetime of a bundle is defined by its component channels - - as long as one or more channels whose Bundle property is <em>B</em> - exist, the bundle <em>B</em> will also exist.</p> - </tp:docstring> - - <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 bundle. - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatch_Operation.xml b/qt4/spec/Channel_Dispatch_Operation.xml deleted file mode 100644 index 6ec69a67b..000000000 --- a/qt4/spec/Channel_Dispatch_Operation.xml +++ /dev/null @@ -1,483 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Dispatch_Operation" - 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.ChannelDispatchOperation"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel dispatch operation is an object in the ChannelDispatcher - representing a batch of unrequested channels being announced to - client - <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 - which are automatically created for some reason, but cannot result - from outgoing requests for channels.</p> - - <p>More specifically, whenever the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> - signal contains channels whose - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> - property is false, or whenever the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> - signal contains a channel with suppress_handler false, - one or more ChannelDispatchOperation objects are created for those - channels.</p> - - <p>(If some channels in a NewChannels signal are in different bundles, - this is an error. The channel dispatcher SHOULD recover by treating - the NewChannels signal as if it had been several NewChannels signals - each containing one channel.)</p> - - <p>First, the channel dispatcher SHOULD construct a list of all the - <tp:dbus-ref - 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">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 - SHOULD be created for all the channels. If there are not, one channel - 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">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">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> - - <tp:rationale> - <p>Some channel types can be picked up "quietly" by an existing - channel handler. If a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - channel is added to an existing bundle containing a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - channel, there shouldn't be - any approvers, flashing icons or notification bubbles, if the - the UI for the StreamedMedia channel can just add a text box - and display the message.</p> - </tp:rationale> - - <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch - operation to all relevant approvers (in parallel) and wait for an - approver to claim the channels or request that they are handled. - See - <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 - send the channels to a handler.</p> - </tp:docstring> - - <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 dispatch - operation. This property cannot change. - </tp:docstring> - </property> - - <property name="Connection" tp:name-for-bindings="Connection" - type="o" access="read"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - with which the <tp:member-ref>Channels</tp:member-ref> are - associated. The well-known bus name to use can be derived from - this object path by removing the leading '/' and replacing all - subsequent '/' by '.'. This property cannot change. - </tp:docstring> - </property> - - <property name="Account" tp:name-for-bindings="Account" - type="o" access="read"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - with which the <tp:member-ref>Connection</tp:member-ref> - and <tp:member-ref>Channels</tp:member-ref> are - associated. This property cannot change. - </tp:docstring> - </property> - - <property name="Channels" tp:name-for-bindings="Channels" - type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s - to be dispatched, and their properties. Change notification is via - the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels - cannot be added to this property, only removed). - </tp:docstring> - </property> - - <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> - <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"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> - that closed. - </tp:docstring> - </arg> - - <arg name="Error" type="s" tp:type="DBus_Error_Name"> - <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.Error.NotAvailable</code> MAY - be used as a fallback; this means that this error SHOULD NOT be - given any more specific meaning.</p> - </tp:docstring> - </arg> - - <arg name="Message" type="s"> - <tp:docstring> - A string associated with the D-Bus error. - </tp:docstring> - </arg> - </signal> - - <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" - type="as" access="read" tp:type="DBus_Well_Known_Name[]"> - <tp:docstring> - <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> - - <method name="HandleWith" tp:name-for-bindings="Handle_With"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by an approver to accept a channel bundle and request that - the given handler be used to handle it.</p> - - <p>If successful, this method will cause the ChannelDispatchOperation - object to disappear, emitting - <tp:member-ref>Finished</tp:member-ref>.</p> - - <p>However, this method may fail because the dispatch has already been - completed and the object has already gone. If this occurs, it - indicates that another approver has asked for the bundle to be - handled by a particular handler. The approver MUST NOT attempt - to interact with the channels further in this case, unless it is - separately invoked as the handler.</p> - - <p>Approvers which are also channel handlers SHOULD use - <tp:member-ref>Claim</tp:member-ref> instead - of HandleWith to request that they can handle a channel bundle - themselves.</p> - - <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">HandleChannels</tp:dbus-ref>, - this method - MAY respond by raising that same error, even if it is not - specifically documented here.</p> - </tp:docstring> - - <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> - <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, 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 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> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The selected handler is temporarily unable to handle these - channels. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The selected handler is syntactically correct, but will never - be able to handle these channels (for instance because the channels - do not match its HandlerChannelFilter, or because HandleChannels - raised NotImplemented). - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> - <tp:docstring> - At the time that HandleWith was called, this dispatch operation was - processing an earlier call to HandleWith. The earlier call has - now succeeded, so some Handler nominated by another approver is - now responsible for the channels. In this situation, the second - call to HandleWith MUST NOT return until the first one has - returned successfully or unsuccessfully, and if the first call - to HandleChannels fails, the channel dispatcher SHOULD try to obey - the choice of Handler made by the second call to HandleWith. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Claim" tp:name-for-bindings="Claim"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <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 <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 - <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 - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - on the channels unless/until this method returns successfully.</p> - - <tp:rationale> - <p>The channel dispatcher can't know how best to close arbitrary - channel types, so it leaves it up to the approver to do so. - 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 - 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 - object to disappear, emitting - <tp:member-ref>Finished</tp:member-ref>, in the same way as for - <tp:member-ref>HandleWith</tp:member-ref>.</p> - - <p>This method may fail because the dispatch operation has already - been completed. Again, see HandleWith for more details. The approver - MUST NOT attempt to interact with the channels further in this - case.</p> - - <p>(FIXME: list some other possible errors)</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> - <tp:docstring> - At the time that Claim was called, this dispatch operation was - processing a call to HandleWith which has now succeeded, so - some Handler nominated by another approver is now responsible for - the channel. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time"> - <tp:added version="0.19.6"> - At the time of writing, no released implementation of the - Channel Dispatcher implements this method; clients should fall - back to calling <tp:member-ref>HandleWith</tp:member-ref>. - </tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the - approver to pass an user action time. This timestamp will be passed - to the Handler when <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> - is called.</p> - </tp:docstring> - - <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> - <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, or the empty string - if the client has no preferred channel handler.</p> - </tp:docstring> - </arg> - - <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The time at which user action occurred.</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 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> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The selected handler is temporarily unable to handle these - channels. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The selected handler is syntactically correct, but will never - be able to handle these channels (for instance because the channels - do not match its HandlerChannelFilter, or because HandleChannels - raised NotImplemented). - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> - <tp:docstring> - At the time that HandleWith was called, this dispatch operation was - processing an earlier call to HandleWith. The earlier call has - now succeeded, so some Handler nominated by another approver is - now responsible for the channels. In this situation, the second - call to HandleWith MUST NOT return until the first one has - returned successfully or unsuccessfully, and if the first call - to HandleChannels fails, the channel dispatcher SHOULD try to obey - the choice of Handler made by the second call to HandleWith. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="Finished" tp:name-for-bindings="Finished"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when this dispatch operation finishes. The dispatch - 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> - - <tp:rationale> - <p>Otherwise, clients might accidentally call - <tp:member-ref>HandleWith</tp:member-ref> or - <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> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatcher.xml b/qt4/spec/Channel_Dispatcher.xml deleted file mode 100644 index 2dd000b40..000000000 --- a/qt4/spec/Channel_Dispatcher.xml +++ /dev/null @@ -1,595 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Dispatcher" - 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.ChannelDispatcher"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel dispatcher is responsible for responding to new - channels and launching client processes to handle them. It also - provides functionality for client processes to request that new - channels are created.</p> - - <p>If a channel dispatcher is running, it is responsible for dispatching - new channels on all - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s - created by the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. - Connections not created by the AccountManager are outside the scope - of the channel dispatcher.</p> - - <tp:rationale> - <p>Connections created by standalone Telepathy clients - that do not intend to interact with the channel dispatcher - should be ignored - otherwise, the channel dispatcher would try - to launch handlers for channels that the standalone client - was already handling internally.</p> - </tp:rationale> - - <p>The current channel dispatcher is defined to be the process that - owns the well-known bus name - <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on - the session bus. This process MUST export an object with this - interface at the object path - <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p> - - <p>Until a mechanism exists for making a reasonable automatic choice - of ChannelDispatcher implementation, implementations SHOULD NOT - register as an activatable service for the ChannelDispatcher's - well-known bus name. Instead, it is RECOMMENDED that some component - of the user's session will select and activate a particular - implementation, and that other Telepathy-enabled programs - can detect whether channel request/dispatch functionality is available - by checking whether the ChannelDispatcher's well-known name is in use - at runtime.</p> - - <p>There are three categories of client process defined by this - specification:</p> - - <dl> - <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><tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt> - <dd> - <p>Approvers notify the user that new channels have been created, - and also select which channel handler will be used for the channel, - either by asking the user or by choosing the most appropriate - channel handler.</p> - </dd> - - <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 - user interface process handling channels of a particular type.</p> - </dd> - </dl> - </tp:docstring> - - <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 dispatcher. - </tp:docstring> - </property> - - <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Equivalent to calling - <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty - <var>Hints</var> parameter.</p> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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 parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - <tp:changed version="0.19.0"> - Previously, the spec didn't say that this should disregard the - handler's filter. This has been implemented since - telepathy-mission-control 5.3.2. - </tp:changed> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Equivalent to calling - <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty - <var>Hints</var> parameter.</p> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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. The behaviour and rationale are the same as for the - corresponding parameter to - <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <method name="CreateChannelWithHints" - tp:name-for-bindings="Create_Channel_With_Hints"> - <tp:added version="0.21.5"> - Support for this method is indicated by the - <tp:member-ref>SupportsRequestHints</tp:member-ref> property. - Clients MUST recover from this method being unsupported by falling back - to <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>. - </tp:added> - <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</tp:dbus-ref> - object, which can be used to continue the request and track its - success or failure.</p> - - <tp:rationale> - <p>The request can take a long time - in the worst case, the - channel dispatcher has to ask the account manager to put the - account online, the account manager has to ask the operating - system to obtain an Internet connection, and the operating - system has to ask the user whether to activate an Internet - connection using an on-demand mechanism like dialup.</p> - - <p>This means that using a single D-Bus method call and response - to represent the whole request will tend to lead to that call - timing out, which is not the behaviour we want.</p> - </tp:rationale> - - <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.Proceed</tp:dbus-ref> - is called, at which point - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> - is emitted with an appropriate error.</p> - - <tp:rationale> - <p>This means there's only one code path for errors, apart from - InvalidArgument for "that request makes no sense".</p> - - <p>It also means that the request will proceed if the account is - enabled after calling CreateChannel, but before calling - Proceed.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. - </p> - - <p>Certain properties will not necessarily make sense in this - dictionary: for instance, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - can only be given if the requester is able to interact with a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - to the desired account.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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">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">HandleChannels</tp:dbus-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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. The channel dispatcher SHOULD dispatch as many as - possible of the resulting channels (ideally, all of them) - to that handler—irrespective of whether that handler's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - matches the channel—and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler.</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">HandleChannels</tp:dbus-ref> - on it, and partly so the channel dispatcher - can recover state if it crashes and is restarted.</p> - - <p>The filter should be disregarded for ease of use of this - interface: clients will usually use this argument to request - channels be sent to themself, and this should trump the filter - not matching. This also allows a client to become the handler - for a channel produced by one of its own requests, while not - being a candidate to handle other channels of that type.</p> - </tp:rationale> - - <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.Interface.Requests">AddRequest</tp:dbus-ref> - on that Handler after this method has returned.</p> - - <tp:rationale> - <p>This ordering allows a Handler which calls CreateChannel with - 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> - - <tp:changed version="0.19.0"> - Previously, the spec didn't say that this should disregard the - handler's filter. This has been implemented since - telepathy-mission-control 5.3.2. - </tp:changed> - </arg> - - <arg direction="in" name="Hints" type="a{sv}"> - <tp:docstring> - <p>Additional information about the channel request, which will be - used as the value for the resulting request's <tp:dbus-ref - namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> - property.</p> - - <tp:rationale> - <p>See the Hints property's documentation for rationale.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <method name="EnsureChannelWithHints" - tp:name-for-bindings="Ensure_Channel_With_Hints"> - <tp:added version="0.21.5"> - Support for this method is indicated by the - <tp:member-ref>SupportsRequestHints</tp:member-ref> property. - Clients MUST recover from this method being unsupported by falling back - to <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. - </tp:added> - <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</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.Proceed</tp:dbus-ref> - is called, at which point - <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'>CreateChannelWithHints</tp:dbus-ref>.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. - </p> - - <p>Certain properties will not necessarily make sense in this - dictionary: for instance, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - can only be given if the requester is able to interact with a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - to the desired account.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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. The behaviour and rationale are the same as for the - corresponding parameter to - <tp:member-ref>CreateChannelWithHints</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 - possible of the resulting channels (ideally, all of them) - to that handler, and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler. If the requested channel already exists (that - is, <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> - returns <code>Yours=False</code>) then the channel dispatcher - SHOULD re-dispatch the channel to its existing handler, and MUST - NOT dispatch it to this client (unless it is the existing handler); - the request is still deemed to have succeeded in this case.</p> - - <tp:rationale> - <p>An address book application, for example, might call <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'>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 - application, they would expect the existing window to be - presented, rather than their double-click leading to an error - message. So the request should succeed, even if its - <code>Preferred_Handler</code> is not used.</p> - </tp:rationale> - - </tp:docstring> - </arg> - - <arg direction="in" name="Hints" type="a{sv}"> - <tp:docstring> - Additional information about the channel request, which will be used - as the value for the resulting request's <tp:dbus-ref - namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> - property.</tp:docstring> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <property name="SupportsRequestHints" - tp:name-for-bindings="Supports_Request_Hints" - type="b" access="read"> - <tp:added version="0.21.5"/> - <tp:docstring> - If <code>True</code>, the channel dispatcher is new enough to support - <tp:member-ref>CreateChannelWithHints</tp:member-ref> and - <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition - to the older <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref> - and <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref> - methods, and also new enough to emit <tp:dbus-ref - namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref> - before the older <tp:dbus-ref - namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal. - If <code>False</code> or missing, only the metadata-less - variants are supported. - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatcher_Future.xml b/qt4/spec/Channel_Dispatcher_Future.xml deleted file mode 100644 index 701b42470..000000000 --- a/qt4/spec/Channel_Dispatcher_Future.xml +++ /dev/null @@ -1,377 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Dispatcher_Future" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2008-2010 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.ChannelDispatcher.FUTURE" - tp:causes-havoc="a staging area for future functionality"> - - <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains functionality which we intend to incorporate - into the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> - interface in future. It should be considered to - be conceptually part of the core ChannelDispatcher interface, but without - API or ABI guarantees.</p> - </tp:docstring> - - <method name="CreateChannelWithHints" - tp:name-for-bindings="Create_Channel_With_Hints"> - <tp:added version="0.19.12"> - Support for this method is indicated by the - <tp:member-ref>SupportsRequestHints</tp:member-ref> property. - Clients MUST recover from this method being unsupported by falling back - to <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>. - </tp:added> - <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</tp:dbus-ref> - object, which can be used to continue the request and track its - success or failure.</p> - - <tp:rationale> - <p>The request can take a long time - in the worst case, the - channel dispatcher has to ask the account manager to put the - account online, the account manager has to ask the operating - system to obtain an Internet connection, and the operating - system has to ask the user whether to activate an Internet - connection using an on-demand mechanism like dialup.</p> - - <p>This means that using a single D-Bus method call and response - to represent the whole request will tend to lead to that call - timing out, which is not the behaviour we want.</p> - </tp:rationale> - - <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.Proceed</tp:dbus-ref> - is called, at which point - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> - is emitted with an appropriate error.</p> - - <tp:rationale> - <p>This means there's only one code path for errors, apart from - InvalidArgument for "that request makes no sense".</p> - - <p>It also means that the request will proceed if the account is - enabled after calling CreateChannel, but before calling - Proceed.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. - </p> - - <p>Certain properties will not necessarily make sense in this - dictionary: for instance, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - can only be given if the requester is able to interact with a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - to the desired account.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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">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">HandleChannels</tp:dbus-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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. The channel dispatcher SHOULD dispatch as many as - possible of the resulting channels (ideally, all of them) - to that handler—irrespective of whether that handler's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - matches the channel—and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler.</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">HandleChannels</tp:dbus-ref> - on it, and partly so the channel dispatcher - can recover state if it crashes and is restarted.</p> - - <p>The filter should be disregarded for ease of use of this - interface: clients will usually use this argument to request - channels be sent to themself, and this should trump the filter - not matching. This also allows a client to become the handler - for a channel produced by one of its own requests, while not - being a candidate to handle other channels of that type.</p> - </tp:rationale> - - <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.Interface.Requests">AddRequest</tp:dbus-ref> - on that Handler after this method has returned.</p> - - <tp:rationale> - <p>This ordering allows a Handler which calls CreateChannel with - 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> - - <tp:changed version="0.19.0"> - Previously, the spec didn't say that this should disregard the - handler's filter. This has been implemented since - telepathy-mission-control 5.3.2. - </tp:changed> - </arg> - - <arg direction="in" name="Hints" type="a{sv}"> - <tp:docstring> - <p>Additional information about the channel request, which will be - used as the value for the resulting request's <tp:dbus-ref - namespace="ofdT.ChannelRequest.FUTURE">Hints</tp:dbus-ref> - property, but will not otherwise be interpreted by the Channel - Dispatcher.</p> - - <tp:rationale> - <p>See the Hints property's documentation for rationale.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <method name="EnsureChannelWithHints" - tp:name-for-bindings="Ensure_Channel_With_Hints"> - <tp:added version="0.19.12"> - Support for this method is indicated by the - <tp:member-ref>SupportsRequestHints</tp:member-ref> property. - Clients MUST recover from this method being unsupported by falling back - to <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. - </tp:added> - <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</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.Proceed</tp:dbus-ref> - is called, at which point - <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'>CreateChannel</tp:dbus-ref>.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Account" type="o"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - for which the new channel is to be created. - </tp:docstring> - </arg> - - <arg direction="in" name="Requested_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. - </p> - - <p>Certain properties will not necessarily make sense in this - dictionary: for instance, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - can only be given if the requester is able to interact with a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - to the desired account.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="User_Action_Time" type="x" - tp:type="User_Action_Timestamp"> - <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.</p> - - <p>This parameter is used in the same way as the corresponding - parameter to - <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Preferred_Handler" type="s" - tp:type="DBus_Well_Known_Name"> - <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. The behaviour and rationale are the same as for the - corresponding parameter to - <tp:member-ref>CreateChannelWithHints</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 - possible of the resulting channels (ideally, all of them) - to that handler, and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler. If the requested channel already exists (that - is, <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> - returns <code>Yours=False</code>) then the channel dispatcher - SHOULD re-dispatch the channel to its existing handler, and MUST - NOT dispatch it to this client (unless it is the existing handler); - the request is still deemed to have succeeded in this case.</p> - - <tp:rationale> - <p>An address book application, for example, might call <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'>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 - application, they would expect the existing window to be - presented, rather than their double-click leading to an error - message. So the request should succeed, even if its - <code>Preferred_Handler</code> is not used.</p> - </tp:rationale> - - </tp:docstring> - </arg> - - <arg direction="in" name="Hints" type="a{sv}"> - <tp:docstring> - Additional information about the channel request, which will be used - as the value for the resulting request's <tp:dbus-ref - namespace="ofdT.ChannelRequest.FUTURE">Hints</tp:dbus-ref> - property.</tp:docstring> - </arg> - - <arg direction="out" name="Request" type="o"> - <tp:docstring> - A - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The Preferred_Handler is syntactically invalid or does - not start with <code>org.freedesktop.Telepathy.Client.</code>, - the Account does not exist, or one of the Requested_Properties - is invalid - </tp:docstring> - </tp:error> - </tp:possible-errors> - - </method> - - <property name="SupportsRequestHints" - tp:name-for-bindings="Supports_Request_Hints" - type="b" access="read"> - <tp:added version="0.19.12"/> - <tp:docstring> - If <code>True</code>, the channel dispatcher is new enough to support - <tp:member-ref>CreateChannelWithHints</tp:member-ref> and - <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition - to the older <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref> - and <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. - methods. If <code>False</code> or missing, only the metadata-less - variants are supported. - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml b/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml deleted file mode 100644 index be06f5caa..000000000 --- a/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml +++ /dev/null @@ -1,140 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Dispatcher_Interface_Operation_List" - 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.ChannelDispatcher.Interface.OperationList"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <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 - all the pending dispatch operations, with change notification.</p> - - <tp:rationale> - <p>The existence of the - <tp:member-ref>DispatchOperations</tp:member-ref> property allows a - newly started approver to pick up existing dispatch operations.</p> - - <p>This is on a separate interface so clients that aren't interested - in doing this aren't woken up by its signals.</p> - </tp:rationale> - </tp:docstring> - - <tp:struct name="Dispatch_Operation_Details" - array-name="Dispatch_Operation_Details_List"> - - <tp:docstring> - Details of a channel dispatch operation. - </tp:docstring> - - <tp:member name="Channel_Dispatch_Operation" type="o"> - <tp:docstring> - The object path of the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>. - </tp:docstring> - </tp:member> - - <tp:member name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties of the channel dispatch operation.</p> - - <p>Connection managers MUST NOT include properties in this mapping - if their values can change. Clients MUST ignore properties - that appear in this mapping if their values can change.</p> - - <tp:rationale> - <p>The rationale is the same as for - <tp:type>Channel_Details</tp:type>.</p> - </tp:rationale> - - <p>Each dictionary MUST contain at least the following keys:</p> - <ul> - <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> - </tp:struct> - - <property - name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations" - type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The list of ChannelDispatchOperation objects currently being - processed. Change notification is via the - <tp:member-ref>NewDispatchOperation</tp:member-ref> and - <tp:member-ref>DispatchOperationFinished</tp:member-ref> signals.</p> - </tp:docstring> - </property> - - <signal name="NewDispatchOperation" - tp:name-for-bindings="New_Dispatch_Operation"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a dispatch operation is added to - <tp:member-ref>DispatchOperations</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Dispatch_Operation" type="o"> - <tp:docstring> - The dispatch operation that was created. - </tp:docstring> - </arg> - - <arg name="Properties" - type="a{sv}" tp:type="Qualified_Property_Value_Map"> - <tp:docstring> - The same properties that would appear in the Properties member of - <tp:type>Dispatch_Operation_Details</tp:type>. - </tp:docstring> - </arg> - </signal> - - <signal name="DispatchOperationFinished" - tp:name-for-bindings="Dispatch_Operation_Finished"> - <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.Finished</tp:dbus-ref>). - - <tp:rationale> - Strictly speaking this is redundant with - ChannelDispatchOperation.Finished, but it provides full - change-notification for the - <tp:member-ref>DispatchOperations</tp:member-ref> property. - </tp:rationale> - </tp:docstring> - - <arg name="Dispatch_Operation" type="o"> - <tp:docstring> - The dispatch operation that was closed. - </tp:docstring> - </arg> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Future.xml b/qt4/spec/Channel_Future.xml deleted file mode 100644 index 5bbca17b1..000000000 --- a/qt4/spec/Channel_Future.xml +++ /dev/null @@ -1,68 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Future" - 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:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.FUTURE" - tp:causes-havoc="a staging area for future Channel functionality"> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains functionality which we intend to incorporate - into the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> interface - in future. It should be considered to - be conceptually part of the core Channel interface, but without - API or ABI guarantees.</p> - - <tp:rationale> - <p>If we add new functionality to the Channel interface, libraries - that use generated code (notably telepathy-glib) will have it as - part of their ABI forever, meaning we can't make incompatible - changes. By using this interface as a staging area for future - Channel functionality, we can try out new properties, signals - and methods as application-specific extensions, then merge them - into the core Channel interface when we have enough implementation - experience to declare them to be stable.</p> - - <p>The name is by analogy to Python's <code>__future__</code> - pseudo-module.</p> - </tp:rationale> - </tp:docstring> - - <property name="Bundle" tp:name-for-bindings="Bundle" - type="o" access="read"> - <tp:added version="0.17.9">(in Channel.FUTURE - pseudo-interface)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The - <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> - - <p>Older connection managers might not have this property. Clients - (particularly the channel dispatcher) SHOULD recover by considering - each channel to be in a bundle containing only that channel, - distinct from all other bundles, which has no additional - interfaces.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Handler.xml b/qt4/spec/Channel_Handler.xml deleted file mode 100644 index edf975e4d..000000000 --- a/qt4/spec/Channel_Handler.xml +++ /dev/null @@ -1,78 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2007-2008 Collabora Limited</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.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 Mission Control 4 client applications which - are able to handle incoming channels.</p> - </tp:docstring> - <tp:added version="0.17.0"/> - - <method name="HandleChannel" tp:name-for-bindings="Handle_Channel"> - <tp:docstring> - Called when a channel handler should handle a new channel. - </tp:docstring> - <tp:added version="0.17.0"/> - - <arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name"> - <tp:docstring> - The bus name of the connection and channel - </tp:docstring> - </arg> - - <arg direction="in" type="o" name="Connection"> - <tp:docstring> - The object-path of the connection that owns the channel - </tp:docstring> - </arg> - - <arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type"> - <tp:docstring> - The channel type - </tp:docstring> - </arg> - - <arg direction="in" type="o" name="Channel"> - <tp:docstring> - The object-path of the channel - </tp:docstring> - </arg> - - <arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type"> - <tp:docstring>The type of the handle that the channel communicates - with, or 0 if there is no associated handle</tp:docstring> - </arg> - - <arg direction="in" type="u" tp:type="Handle" name="Handle"> - <tp:docstring>The handle that the channel communicates with, - or 0 if there is no associated handle</tp:docstring> - </arg> - - <!-- FIXME: possible errors? --> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> - diff --git a/qt4/spec/Channel_Interface_Addressing.xml b/qt4/spec/Channel_Interface_Addressing.xml deleted file mode 100644 index 494fd7bf0..000000000 --- a/qt4/spec/Channel_Interface_Addressing.xml +++ /dev/null @@ -1,107 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Addressing.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface provides properties that can be used for - requesting channels through different contact addressing - schemes like vCard addresses or URIs. - </p> - </tp:docstring> - - <property name="TargetVCardField" type="s" access="read" - tp:name-for-bindings="Target_VCard_Field"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The vCard field, normalized to lower case, - <tp:member-ref>TargetVCardAddress</tp:member-ref> refers to.</p> - - <p>The <code>url</code> vCard field MUST NOT appear here; see - <tp:member-ref>TargetURI</tp:member-ref> instead.</p> - - <tp:rationale> - <p>In practice, protocols have a limited set of URI - schemes that make sense to resolve as a contact.</p> - </tp:rationale> - - <p>If this is omitted from a request, - <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST be - omitted as well.</p> - </tp:docstring> - </property> - - <property name="TargetURIScheme" type="s" access="read" - tp:name-for-bindings="Target_URI_Scheme"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The URI scheme used in <tp:member-ref>TargetURI</tp:member-ref></p> - - <tp:rationale> - <p>While this seems redundant, since the scheme is included in - <tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> - that support a limited set of URI schemes.</p> - </tp:rationale> - - <p>If this is omitted from a request, - <tp:member-ref>TargetURI</tp:member-ref> MUST be - omitted as well.</p> - </tp:docstring> - </property> - - <property name="TargetVCardAddress" type="s" access="read" - tp:name-for-bindings="Target_VCard_Address"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The vCard address of the Channel's target.</p> - - <p>If this is present in a channel request, - <tp:member-ref>TargetVCardField</tp:member-ref> - MUST be present, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>, - and <tp:member-ref>TargetURI</tp:member-ref> MUST NOT be present. - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - must either not be present or set to Handle_Type_Contact. - The request MUST fail with error InvalidHandle, without - side-effects, if the requested vCard address cannot be found.</p> - </tp:docstring> - </property> - - <property name="TargetURI" type="s" access="read" - tp:name-for-bindings="Target_URI"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The URI of the Channel's target. The URI's scheme (i.e. the - part before the first colon) MUST be identical to - <tp:member-ref>TargetURIScheme</tp:member-ref>.</p> - - <p>If this is present in a channel request, - <tp:member-ref>TargetVCardField</tp:member-ref> - MUST be present, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>, - and <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST NOT be - present. - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - must either not be present or set to Handle_Type_Contact. - The request MUST fail with error InvalidHandle, without - side-effects, if the requested vCard address cannot be found.</p> - </tp:docstring> - </property> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Anonymity.xml b/qt4/spec/Channel_Interface_Anonymity.xml deleted file mode 100644 index ef3a3b85d..000000000 --- a/qt4/spec/Channel_Interface_Anonymity.xml +++ /dev/null @@ -1,68 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Anonymity" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - - <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity"> - <tp:added version="0.19.7">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for requesting the anonymity modes of a channel - (as defined in <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.Interface.Anonymity</tp:dbus-ref>).</p> - </tp:docstring> - - <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" - access="read" tp:name-for-bindings="Anonymity_Modes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The list of initially requested anonymity modes on the channel. This - MUST NOT change, and is Requestable. - </tp:docstring> - </property> - - <property name="AnonymityMandatory" type="b" access="read" - tp:name-for-bindings="Anonymity_Mandatory"> - <tp:docstring> - Whether or not the anonymity settings are required for this channel. - This MUST NOT change, and is Requestable. - </tp:docstring> - </property> - - <property name="AnonymousID" type="s" access="read" - tp:name-for-bindings="Anonymous_ID"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This is the ID that the remote user of the channel MAY see - (assuming there's a single ID). For example, for SIP connections - where the From address has been scrambled by the CM, the scrambled - address would be available here for the client to see. This is - completely optional, and MAY be an empty string ("") in - cases where anonymity modes are not set, or the CM doesn't know - what the remote contact will see, or any other case where this - doesn't make sense.</p> - - <p>This MAY change over the lifetime of the channel, and SHOULD NOT - be used with the Request interface.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Call_State.xml b/qt4/spec/Channel_Interface_Call_State.xml deleted file mode 100644 index b0aea5915..000000000 --- a/qt4/spec/Channel_Interface_Call_State.xml +++ /dev/null @@ -1,147 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Call_State" 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:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.CallState"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - - <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; - similarly, Jingle implementations are not guaranteed to send - <code><ringing/></code>).</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"/> - - <method name="GetCallStates" tp:name-for-bindings="Get_Call_States"> - <tp:docstring> - Get the current call states for all contacts involved in this call. - </tp:docstring> - - <arg tp:type="Channel_Call_State_Map" name="States" direction="out" - type="a{uu}"> - <tp:docstring> - The current call states. Participants where the call state flags - would be 0 (all unset) may be omitted from this mapping. - </tp:docstring> - </arg> - </method> - - <signal name="CallStateChanged" tp:name-for-bindings="Call_State_Changed"> - <tp:docstring> - Emitted when the state of a member of the channel has changed. - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact. - </tp:docstring> - </arg> - - <arg name="State" type="u" tp:type="Channel_Call_State_Flags"> - <tp:docstring> - The new state for this contact. - </tp:docstring> - </arg> - </signal> - - <tp:mapping name="Channel_Call_State_Map"> - <tp:docstring> - A map from contacts to call states. - </tp:docstring> - - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring>A contact involved in this call.</tp:docstring> - </tp:member> - - <tp:member name="State" type="u" tp:type="Channel_Call_State_Flags"> - <tp:docstring>State flags for the given contact.</tp:docstring> - </tp:member> - </tp:mapping> - - <tp:flags name="Channel_Call_State_Flags" value-prefix="Channel_Call_State" type="u"> - <tp:docstring> - A set of flags representing call states. - </tp:docstring> - - <tp:flag suffix="Ringing" value="1"> - <tp:docstring> - The contact has been alerted about the call but has not responded - (e.g. 180 Ringing in SIP). - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Queued" value="2"> - <tp:docstring> - The contact is temporarily unavailable, and the call has been placed - in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Held" value="4"> - <tp:docstring> - The contact has placed the call on hold, and will not receive - media from the local user or any other participants until they - unhold the call again. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Forwarded" value="8"> - <tp:docstring> - The initiator of the call originally called a contact other than the - current recipient of the call, but the call was then forwarded or - diverted. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="In_Progress" value="16"> - <tp:docstring> - Progress has been made in placing the outgoing call, but the - destination contact may not have been made aware of the call yet - (so the Ringing state is not appropriate). This corresponds to SIP's - status code 183 Session Progress, and could be used when the - outgoing call has reached a gateway, for instance. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Conference_Host" value="32"> - <tp:added version='0.19.11'/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This contact has merged this call into a conference. Note that GSM - provides a notification when the remote party merges a call into a - conference, but not when it is split out again; thus, this flag can - only indicate that the call has been part of a conference at some - point. If a GSM connection manager receives a notification that a - call has been merged into a conference a second time, it SHOULD - represent this by clearing and immediately re-setting this flag on - the remote contact. - </tp:docstring> - </tp:flag> - </tp:flags> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Chat_State.xml b/qt4/spec/Channel_Interface_Chat_State.xml deleted file mode 100644 index 27515d2e8..000000000 --- a/qt4/spec/Channel_Interface_Chat_State.xml +++ /dev/null @@ -1,144 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Chat_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.ChatState"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> - - <tp:mapping name="Chat_State_Map"> - <tp:added version="0.19.7"/> - <tp:docstring>A map from contacts to their chat states.</tp:docstring> - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring>A contact</tp:docstring> - </tp:member> - <tp:member name="State" type="u" tp:type="Channel_Chat_State"> - <tp:docstring>The contact's chat state</tp:docstring> - </tp:member> - </tp:mapping> - - <property name="ChatStates" tp:name-for-bindings="Chat_States" - access="read" type="a{uu}" tp:type="Chat_State_Map"> - <tp:added version="0.19.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map containing the chat states of all contacts in this - channel whose chat state is not Inactive.</p> - - <p>Contacts in this channel, but who are not listed in this map, - may be assumed to be in the Inactive state.</p> - - <p>In implementations that do not have this property, its value may be - assumed to be empty until a - <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates - otherwise.</p> - - <tp:rationale> - <p>This property was not present in older versions of telepathy-spec, - because chat states in XMPP are not state-recoverable (if you - miss the change notification signal, there's no way to know the - state). However, this property still allows clients to recover - state changes that were seen by the CM before the client started - to deal with the channel.</p> - - <p>In CMs that follow older spec versions, assuming Inactive will - mean that initial chat states will always be assumed to be - Inactive, which is the best we can do. XEP 0085 specifies - Inactive as the "neutral" state to be assumed unless told - otherwise.</p> - </tp:rationale> - </tp:docstring> - </property> - - <method name="SetChatState" tp:name-for-bindings="Set_Chat_State"> - <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State"> - <tp:docstring> - The new state. - </tp:docstring> - </arg> - <tp:docstring> - Set the local state and notify other members of the channel that it - has changed. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - </tp:possible-errors> - </method> - <signal name="ChatStateChanged" tp:name-for-bindings="Chat_State_Changed"> - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact. - </tp:docstring> - </arg> - <arg name="State" type="u" tp:type="Channel_Chat_State"> - <tp:docstring> - The new state of this contact. - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the state of a member of the channel has changed. - This includes local state. - </tp:docstring> - </signal> - <tp:enum name="Channel_Chat_State" type="u"> - <tp:enumvalue suffix="Gone" value="0"> - <tp:docstring> - The contact has effectively ceased participating in the chat. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Inactive" value="1"> - <tp:docstring> - The contact has not been active for some time. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Active" value="2"> - <tp:docstring> - The contact is actively participating in the chat. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Paused" value="3"> - <tp:docstring> - The contact has paused composing a message. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Composing" value="4"> - <tp:docstring> - The contact is composing a message to be sent to the chat. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for channels for receiving notifications of remote contacts' - state, and for notifying remote contacts of the local state.</p> - - <p>Clients should assume that a contact's state is Channel_Chat_State_Inactive - unless they receive a notification otherwise.</p> - - <p>The Channel_Chat_State_Gone state is treated differently to other states:</p> - <ul> - <li>It may not be used for multi-user chats</li> - <li>It may not be explicitly sent</li> - <li>It should be automatically sent when the channel is closed</li> - <li>It must not be sent to the peer if a channel is closed without being used</li> - <li>Receiving it must not cause a new channel to be opened</li> - </ul> - - <p>The different states are defined by XEP-0085, but may be applied to any suitable protocol.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Conference.xml b/qt4/spec/Channel_Interface_Conference.xml deleted file mode 100644 index abda59eef..000000000 --- a/qt4/spec/Channel_Interface_Conference.xml +++ /dev/null @@ -1,628 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Conference" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Channel.Interface.Conference"> - <tp:added version="0.19.13">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires - interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for multi-user conference channels that can "continue - from" one or more individual channels. This could be used to invite - other contacts to an existing 1-1 text conversation, combine two phone - calls into one conference call, and so on, with roughly the same API in - each case.</p> - - <tp:rationale> - <p>This interface addresses freedesktop.org <a - href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug - #24906</a> (GSM-compatible conference calls) and <a - href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug - #24939</a> (upgrading calls and chats to multi-user). - See those bugs for more rationale and use cases.</p> - </tp:rationale> - - <p>Existing channels are upgraded by requesting a new channel of the same - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>, - listing the channels to be merged into the new conference in the - <tp:member-ref>InitialChannels</tp:member-ref> property of the request. - If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and - <tp:member-ref>InitialInviteeIDs</tp:member-ref> are - <var>Allowed_Properties</var> in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>, - ad-hoc conferences to a set of contacts may be created by requesting a - channel, specifying - <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or - <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in - question. A request may specify these alongside - <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously - upgrade a channel to a conference and invite others to join it.</p> - - <p>Channels with this interface MAY also implement <tp:dbus-ref - namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref> - to support merging more 1-1 channels into an ongoing conference. - Similarly, 1-1 channels MAY implement <tp:dbus-ref - namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to - support being broken out of a Conference channel.</p> - - <p>The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface" - >Group</tp:dbus-ref> interface on Conference channels MAY use - channel-specific handles for participants; clients SHOULD support - both Conferences that have channel-specific handles, and those that - do not.</p> - - <tp:rationale> - <p>In the GSM case, the Conference's Group interface MAY have - channel-specific handles, to represent the fact that the same - phone number may be in a conference twice (for instance, it could be - the number of a corporate switchboard).</p> - - <p>In the XMPP case, the Conference's Group interface SHOULD have - channel-specific handles, to reflect the fact that the participants - have MUC-specific identities, and the user might also be able to see - their global identities, or not.</p> - - <p>In most other cases, including MSN and link-local XMPP, the - Conference's Group interface SHOULD NOT have channel-specific - handles, since users' identities are always visible.</p> - </tp:rationale> - - <p>Connection managers implementing channels with this interface - MUST NOT allow the object paths of channels that could be merged - into a Conference to be re-used, unless the channel re-using the - object path is equivalent to the channel that previously used it.</p> - - <tp:rationale> - <p>If you upgrade some channels into a conference, and then close - the original channels, <tp:member-ref>InitialChannels</tp:member-ref> - (which is immutable) will contain paths to channels which no longer - exist. This implies that you should not re-use channel object paths, - unless future incarnations of the path are equivalent.</p> - - <p>For instance, on protocols where you can only have - zero or one 1-1 text channels with Emily at one time, it would - be OK to re-use the same object path for every 1-1 text channel - with Emily; but on protocols where this is not true, it would - be misleading.</p> - </tp:rationale> - - <h4>Examples of usage</h4> - - <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged - into a single conference call by calling:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call, - ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2] - })</code> - </blockquote> - - <p>which returns a new channel <var>Cn</var> implementing the conference - interface. (As a quirk of GSM, both 1-1 will cease to function normally - until they are <tp:dbus-ref - namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref> - from the conference, or the conference ends.)</p> - - <p>An XMPP 1-1 conversation <var>C3</var> (with - <tt>chris@example.com</tt>, say) can be continued in a newly created - multi-user chatroom by calling:</p> - - <blockquote> - <code>CreateChannel({ - ...ChannelType: ...Text, - ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3] - })</code> - </blockquote> - - <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC - at the same time:</p> - - <blockquote> - <code>CreateChannel({ - ...ChannelType: ...Text, - ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3], - ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net'] - })</code> - </blockquote> - - <p>To continue <var>C3</var> in a particular multi-user - chatroom (rather than the implementation inventing a unique name for - the room), call:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({ - ...ChannelType: ...Text, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: ...Room, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com', - ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3] - })</code> - </blockquote> - - <p>Note the use of EnsureChannel — if a channel for - <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be - equivalent to inviting <tt>chris@example.com</tt> to the existing - channel.</p> - - <p>In the above cases, the text channel <var>C3</var> SHOULD remain open - and fully functional (until explicitly closed by a client); new - incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in - <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed - only to <tt>chris@example.com</tt>.</p> - - <tp:rationale> - <p>If there is an open 1-1 text channel with a contact, in every - other situation new messages will appear in that channel. Given - that the old channel remains open — which is the least surprising - behaviour, and eases us towards a beautiful world where channels - never close themselves — it stands to reason that it should be - where new messages from Chris should appear. On MSN, creating a - conference from <var>C3</var> should migrate the underlying - switchboard from <var>C3</var> to the new channel; this is an - implementation detail, and should not affect the representation on - D-Bus. With a suitable change of terminology, Skype has the same - behaviour.</p> - - <p>If the current handler of that channel doesn't want this to happen - (maybe it transformed the existing tab into the group chat window, - and so there'd be no UI element still around to show new messages), - then it should just <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the - old 1-1 channel; it'll respawn if necessary.</p> - </tp:rationale> - - <p>Either of the XMPP cases could work for Call channels, to - upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases - could in principle work for link-local XMPP (XEP-0174).</p> - - <p>XMPP and MSN do not natively have a concept of merging two or more - channels C1, C2... into one channel, Cn. However, the GSM-style - merging API can be supported on XMPP and MSN, as an API short-cut - for upgrading C1 into a conference Cn (which invites the - TargetHandle of C1 into Cn), then immediately inviting the - TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p> - - <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests' - >RequestableChannelClasses</tp:dbus-ref></h4> - - <p>A GSM connection might advertise the following channel class for - conference calls:</p> - - <blockquote> - <code> -( Fixed = {<br/> - ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: - ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/> - },<br/> - Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>, - <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia' - >InitialAudio</tp:dbus-ref> - ]<br/> -) - </code> - </blockquote> - - <p>This indicates support for starting audio-only conference calls by - merging two or more existing channels (since - <tp:member-ref>InitialInviteeHandles</tp:member-ref> and - <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p> - - <p>An XMPP connection might advertise the following classes for ad-hoc - multi-user text chats:</p> - - <blockquote> - <code> -( Fixed = {<br/> - ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: - ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/> - },<br/> - Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>, - <tp:member-ref>InitialInviteeHandles</tp:member-ref>, - <tp:member-ref>InitialInviteeIDs</tp:member-ref>, - <tp:member-ref>InvitationMessage</tp:member-ref> - ]<br/> -),<br/> -( Fixed = {<br/> - ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: - ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/> - ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>: - Room<br/> - },<br/> - Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, - <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/> - <tp:member-ref>InitialChannels</tp:member-ref>, - <tp:member-ref>InitialInviteeHandles</tp:member-ref>, - <tp:member-ref>InitialInviteeIDs</tp:member-ref>, - <tp:member-ref>InvitationMessage</tp:member-ref> - ]<br/> -) - </code> - </blockquote> - - <p>The first class indicates support for starting ad-hoc (nameless) chat - rooms, upgraded from existing 1-1 channels and/or inviting new - contacts, along with a message to be sent along with the invitations. - The second indicates support for upgrading to a particular named chat - room.</p> - </tp:docstring> - - <property name="Channels" tp:name-for-bindings="Channels" - access="read" type="ao"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The individual <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that - are continued by this conference, which have the same <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref> = CONTACT.</p> - - <p>This property MUST NOT be requestable; instead, the - <tp:member-ref>InitialChannels</tp:member-ref> property may be - specified when requesting a channel.</p> - - <tp:rationale> - <p>This is consistent with requesting - <tp:member-ref>InitialInviteeHandles</tp:member-ref> and - <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than - requesting <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref> - and some hypothetical ID version of that property.</p> - </tp:rationale> - - <p>Change notification is via the - <tp:member-ref>ChannelMerged</tp:member-ref> and - <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p> - </tp:docstring> - </property> - - <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new channel is added to the value of - <tp:member-ref>Channels</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Channel" type="o"> - <tp:docstring>The channel that was added to - <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> - </arg> - - <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring>A new channel-specific handle for the <tp:dbus-ref - namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of - <var>Channel</var>, as will appear in - <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a - global handle is used for - <var>Channel</var>'s TargetHandle on the <tp:dbus-ref - namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface - of this channel.</tp:docstring> - </arg> - - <arg name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring> - </arg> - </signal> - - <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a channel is removed from the value of - <tp:member-ref>Channels</tp:member-ref>, either because it closed - or because it was split using the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface" - >Splittable.DRAFT.Split</tp:dbus-ref> method.</p> - - <p>If a channel is removed because it was closed, <tp:dbus-ref - namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted - before this signal.</p> - </tp:docstring> - - <arg name="Channel" type="o"> - <tp:docstring>The channel that was removed from - <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> - </arg> - - <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Additional information about the removal, which may include - the same well-known keys as the Details argument of - <tp:dbus-ref namespace="ofdT.Channel.Interface.Group" - >MembersChangedDetailed</tp:dbus-ref>, with the same semantics. - </tp:docstring> - </arg> - </signal> - - <property name="InitialChannels" tp:name-for-bindings="Initial_Channels" - access="read" type="ao" tp:immutable="yes" tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p> - - <p>This property SHOULD be requestable. Omitting it from a request is - equivalent to providing it with an empty list as value. Requests - where its value has at least two channel paths SHOULD be expected to - succeed on any implementation of this interface. If - <tp:member-ref>InitialInviteeHandles</tp:member-ref> and - <tp:member-ref>InitialInviteeIDs</tp:member-ref> are - <var>Allowed_Properties</var> in <tp:dbus-ref - namespace='ofdT.Connection.Interface.Requests' - >RequestableChannelClasses</tp:dbus-ref>, then requests with zero - or one channel paths SHOULD also succeed; otherwise, clients SHOULD - NOT make requests with zero or one paths for this property.</p> - - <tp:rationale> - <p>In GSM, a pair of calls can be merged into a conference, but you - can't start a conference call from zero or one existing calls. In - XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 - channel into a chatroom; however, on these protocols, it is also - possible to fake GSM-style merging by upgrading the first channel, - then inviting the targets of all the other channels into it.</p> - </tp:rationale> - - <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD - NOT be altered by merging them into a conference. However, depending on - the protocol, the Channels MAY be placed in a "frozen" state by placing - them in this property's value or by calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface" - >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p> - - <tp:rationale> - <p>In Jingle, nothing special will happen to merged calls. UIs MAY - automatically place calls on hold before merging them, if that is - the desired behaviour; this SHOULD always work. Not doing - an implicit hold/unhold seems to preserve least-astonishment.</p> - - <p>In GSM, the calls that are merged go into a state similar to - Hold, but they cannot be unheld, only split from the conference - call using <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p> - </tp:rationale> - - <p>Depending on the protocol, it might be signalled to remote users - that this channel is a continuation of all the requested channels, - or that it is only a continuation of the first channel in the - list.</p> - - <tp:rationale> - <p>In MSN, the conference steals the underlying switchboard (protocol - construct) from one of its component channels, so the conference - appears to remote users to be a continuation of that channel and no - other. The connection manager has to make some arbitrary choice, so - we arbitrarily mandate that it SHOULD choose the first channel in - the list as the one to continue.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialInviteeHandles" - tp:name-for-bindings="Initial_Invitee_Handles" - access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes" - tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of additional contacts invited to this conference when it - was created.</p> - - <p>If it is possible to invite new contacts when creating a conference - (as opposed to merging several channels into one new conference - channel), this property SHOULD be requestable, and appear in the allowed - properties in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property - SHOULD NOT be requestable, and its value SHOULD always be the empty - list.</p> - - <tp:rationale> - <p>On GSM you have to place a 1-1 call before you can merge it into a - conference; on the other hand, you can invite new contacts to XMPP - Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a - 1-1 channel with them first.</p> - </tp:rationale> - - <p>If included in a request, the given contacts are automatically - invited into the new channel, as if they had been added with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" - >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles, - <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after - the channel was created.</p> - - <tp:rationale> - <p>This is a simple convenience API for the common case that a UI - upgrades a 1-1 chat to a multi-user chat solely in order to invite - someone else to participate.</p> - </tp:rationale> - - <p>If the local user was not the initiator of this channel, the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" - >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this - property, together with any other contacts invited at the same time - (if that information is known).</p> - - <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be - combined in a single request.</p> - - <tp:rationale> - <p>For example, if you have a 1-1 channel C1 with Rob, and you want - to invite Sjoerd to join the discussion, you can do so by - requesting a channel with InitialChannels=[C1] and - InitialInviteeHandles=[sjoerd], - or InitialChannels=[C1] and - InitialInviteeIDs=["sjoerd@example.com"].</p> - </tp:rationale> - - <p>If a request includes some combination of InitialInviteeHandles, - InitialInviteeIDs and InitialChannels, then the value of - InitialInviteeHandles on the resulting channel SHOULD be the union of - the handles from InitialInviteeHandles, the handles corresponding - to the InitialInviteeIDs, and the target handles of the - InitialChannels, with any duplicate handles removed. Because this - property is immutable, its value SHOULD be computed before the - channel is announced via the NewChannels signal.</p> - - <tp:rationale> - <p>This simplifies identification of new channels in clients - they - only have to look at one of the properties, not both. For example, - after either of the requests mentioned above, the NewChannels - signal would announce the channel with InitialChannels=[C1], - InitialInviteeHandles=[rob, sjoerd], and - InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialInviteeIDs" - tp:name-for-bindings="Initial_Invitee_IDs" - access="read" type="as" tp:immutable="yes" tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of additional contacts invited to this conference when it - was created.</p> - - <p>This property SHOULD be requestable if and only if - <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable. - Its semantics are the same, except that it takes a list of the - string representations of contact handles; invitations are sent to - any contact present in either or both of these properties.</p> - - <p>When a channel is created, the values of InitialInviteeHandles and - InitialInviteeIDs MUST correspond to each other. In particular, this - means that the value of InitialInviteeIDs will include the TargetID - of each channel in InitialChannels, and the ID corresponding to each - handle in InitialInviteeHandles.</p> - </tp:docstring> - </property> - - <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message" - access="read" type="s" tp:immutable="yes" tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The message that was sent to the - <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were - invited.</p> - - <p>This property SHOULD be requestable, and appear in the allowed - properties in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref>, in protocols where - invitations can have an accompanying text message.</p> - - <tp:rationale> - <p>This allows invitations with a message to be sent when using - <tp:member-ref>InitialInviteeHandles</tp:member-ref> or - <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p> - </tp:rationale> - - <p>If the local user was not the initiator of this channel, the - message with which they were invited (if any) SHOULD appear in the - value of this property.</p> - </tp:docstring> - </property> - - <property name="OriginalChannels" tp:name-for-bindings="Original_Channels" - type="a{uo}" tp:type="Channel_Originator_Map" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>On GSM conference calls, it is possible to have the same phone - number in a conference twice; for instance, it could be the number of - a corporate switchboard. This is represented using channel-specific - handles; whether or not a channel uses channel-specific handles is - reported in <tp:dbus-ref - namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>. - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref> - property specifies the mapping from opaque channel-specific handles - to actual numbers; this property specifies the original 1-1 channel - corresponding to each channel-specific handle in the conference.</p> - - <p>In protocols where this situation cannot arise, such as XMPP, - this property MAY remain empty.</p> - - <p>For example, consider this situation:</p> - - <ol> - <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact - <tt>+441234567890</tt> (which is assigned the handle <var>h</var>, - say), and ask to be put through to Simon McVittie;</li> - <li>Put that call on hold;</li> - <li>Place another call (with path <tt>/call/to/jonny</tt>) to - <tt>+441234567890</tt>, and ask to be put - through to Jonny Lamb;</li> - <li>Request a new channel with - <tp:member-ref>InitialChannels</tp:member-ref>: - <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li> - </ol> - - <p>The new channel will have the following properties, for some handles - <var>s</var> and <var>j</var>:</p> - - <blockquote> - <code>{<br/> - ...<tp:dbus-ref - namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>: - Channel_Specific_Handles | (other flags),<br/> - ...<tp:dbus-ref - namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>: - [self_handle, s, j],<br/> - ...<tp:dbus-ref - namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>: - { s: h, j: h },<br/> - ...<tp:member-ref>InitialChannels</tp:member-ref>: - ['/call/to/simon', '/call/to/jonny'],<br/> - ...<tp:member-ref>Channels</tp:member-ref>: - ['/call/to/simon', '/call/to/jonny'],<br/> - ...<tp:member-ref>OriginalChannels</tp:member-ref>: - { s: '/call/to/simon', j: '/call/to/jonny' },<br/> - # ...standard properties like ChannelType: Group elided...<br/> - }</code> - </blockquote> - - <p>Change notification is via the - <tp:member-ref>ChannelMerged</tp:member-ref> and - <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if - <var>Channel_Specific_Handle</var> in the former is non-zero, this - property SHOULD be updated to map that handle to the merged channel's - path.</p> - </tp:docstring> - </property> - - <tp:mapping name="Channel_Originator_Map"> - <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A channel-specific handle for a participant in this conference. - </tp:docstring> - </tp:member> - <tp:member name="Original_Channel" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The object path of <tp:member-ref>Channels</tp:member-ref> - representing the original 1-1 channel with - <var>Channel_Specific_Handle</var>. - </tp:docstring> - </tp:member> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A mapping from members of a conference to the original 1-1 channel with - that contact, if any. See - <tp:member-ref>OriginalChannels</tp:member-ref> for details. - </tp:docstring> - </tp:mapping> - </interface> -</node> diff --git a/qt4/spec/Channel_Interface_Credentials_Storage.xml b/qt4/spec/Channel_Interface_Credentials_Storage.xml deleted file mode 100644 index e44b13e32..000000000 --- a/qt4/spec/Channel_Interface_Credentials_Storage.xml +++ /dev/null @@ -1,59 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Credentials_Storage" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2011 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.CredentialsStorage.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.10">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel interface for SASL authentication channels that can save the - credentials in the connection manager.</p> - - <p>This interface is unlikely to be present for any SASL channels that are - more complex than a simple password prompt (e.g. - <code>X-TELEPATHY-PASSWORD</code> or <code>PLAIN</code>).</p> - - <p>In practice, this interface should only be implemented by connection - managers that implement the <tp:dbus-ref - namespace="ofdT">ConnectionManager.Interface.AccountStorage.DRAFT</tp:dbus-ref> - interface. To clear a password that has been saved in this manner, a - client should call <tp:dbus-ref - namespace="ofdT.ConnectionManager.Interface">AccountStorage.DRAFT.ForgetCredentials</tp:dbus-ref> - on the Account.</p> - </tp:docstring> - - <method name="StoreCredentials" tp:name-for-bindings="Store_Credentials"> - <arg direction="in" name="Store" type="b"> - <tp:docstring> - Whether to store the authentication credentials. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This method tells the connection manager whether to store the - authentication response in order to allow the connection manager to - sign-on automatically in the future.</p> - <p>If credentials have been stored in this way, the client SHOULD NOT - attempt to store the credentials locally in a keyring.</p> - <p>This method MUST be called before <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication">AcceptSASL</tp:dbus-ref> - is called or it will have no effect.</p> - </tp:docstring> - </method> - </interface> -</node> diff --git a/qt4/spec/Channel_Interface_DTMF.xml b/qt4/spec/Channel_Interface_DTMF.xml deleted file mode 100644 index d74ea6fa7..000000000 --- a/qt4/spec/Channel_Interface_DTMF.xml +++ /dev/null @@ -1,342 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2006 INdT</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF"> - <tp:xor-requires> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> - </tp:xor-requires> - <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this - interface should now be ignored by CMs. This is primarily to allow this - interface to be used with <tp:dbus-ref - namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> - channels.</tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An interface that gives a Channel the ability to send DTMF events over - audio streams which have been established using the StreamedMedia channel - type. The event codes used are in common with those defined in <a - href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are - listed in the <tp:type>DTMF_Event</tp:type> enumeration. - </tp:docstring> - - <method name="StartTone" tp:name-for-bindings="Start_Tone"> - <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became - vestigial.</tp:changed> - <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> - <tp:docstring>A stream ID as defined in the StreamedMedia channel - type. This argument is included for backwards compatibility and MUST - be ignored by the implementations - the tone SHOULD be sent to all - eligible streams in the channel.</tp:docstring> - </arg> - <arg direction="in" name="Event" type="y" tp:type="DTMF_Event"> - <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring> - </arg> - - <tp:docstring> - <p>Start sending a DTMF tone to all eligible streams in the channel. - Where possible, the tone will continue until - <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols, - it may only be possible to send events with a predetermined length. In - this case, the implementation MAY emit a fixed-length tone, and the - StopTone method call SHOULD return NotAvailable.</p> - <tp:rationale> - The client may wish to control the exact duration and timing of the - tones sent as a result of user's interaction with the dialpad, thus - starting and stopping the tone sending explicitly. - </tp:rationale> - - <p>Tone overlaping or queueing is not supported, so this method can only - be called if no DTMF tones are already being played.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given stream ID was invalid. Deprecated, since stream IDs - are ignored. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - There are no eligible audio streams. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> - <tp:docstring> - DTMF tones are already being played. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="StopTone" tp:name-for-bindings="Stop_Tone"> - <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became - vestigial.</tp:changed> - <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> - <tp:docstring>A stream ID as defined in the StreamedMedia channel - type. This argument is included for backwards compatibility and MUST - be ignored by the implementations - the sending SHOULD be stoped in - all eligible streams in the channel.</tp:docstring> - </arg> - - <tp:docstring> - Stop sending any DTMF tones which have been started using the - <tp:member-ref>StartTone</tp:member-ref> or - <tp:member-ref>MultipleTones</tp:member-ref> methods. - If there is no current tone, this method will do nothing. - If MultipleTones was used, the client should not assume the - sending has stopped immediately; instead, the client should wait - for the StoppedTones signal. - <tp:rationale> - On some protocols it might be impossible to cancel queued tones - immediately. - </tp:rationale> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given stream ID was invalid. Deprecated, since stream IDs - are ignored. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Continuous tones are not supported by this stream. Deprecated, - since stream IDs are ignored. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones"> - <tp:added version="0.19.6" /> - <tp:changed version="0.21.3">The characters [pPxXwW,] must - also be supported.</tp:changed> - <arg direction="in" name="Tones" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A string representation of one or more DTMF - events. Implementations of this method MUST support all of the - following characters in this string:</p> - - <ul> - <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#' - correspond to the members of <tp:type>DTMF_Event</tp:type></li> - - <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an - implementation-defined pause, typically for 3 seconds</li> - - <li>'w' or 'W' waits for the user to continue, by stopping - interpretation of the string, and if there is more to be played, - emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal - with the rest of the string as its argument: see that signal - for details</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - <p>Send multiple DTMF events to all eligible streams in the channel. - Each tone will be played for an implementation-defined number of - milliseconds (typically 250ms), followed by a gap before the next tone - is played (typically 100ms). The - duration and gap are defined by the protocol or connection manager.</p> - - <tp:rationale> - <p>In cases where the client knows in advance the tone sequence it - wants to send, it's easier to use this method than manually start - and stop each tone in the sequence.</p> - - <p>The tone and gap lengths may need to vary for interoperability, - according to the protocol and other implementations' ability to - recognise tones. At the time of writing, GStreamer uses a - minimum of 250ms tones and 100ms gaps when playing in-band DTMF - in the normal audio stream, or 70ms tones and 50ms gaps when - encoding DTMF as <code>audio/telephone-event</code>.</p> - </tp:rationale> - - <p>Tone overlaping or queueing is not supported, so this method can only - be called if no DTMF tones are already being played.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The supplied Tones string was invalid. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - There are no eligible audio streams. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> - <tp:docstring> - DTMF tones are already being played. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <property name="CurrentlySendingTones" - tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read"> - <tp:added version="0.19.6" /> - <tp:docstring> - Indicates whether there are DTMF tones currently being sent in the - channel. If so, the client should wait for - <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to - send more tones. - </tp:docstring> - </property> - - <property name="InitialTones" tp:name-for-bindings="Initial_Tones" - type="s" access="read"> - <tp:added version="0.19.6" /> - <tp:docstring> - <p>If non-empty in a channel request that will create a new channel, - the connection manager should send the tones immediately after - at least one eligible audio stream has been created in the - channel.</p> - - <p>This property is immutable (cannot change).</p> - </tp:docstring> - </property> - - <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones" - type="s" access="read"> - <tp:added version="0.21.3" /> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The tones waiting for the user to continue, if any.</p> - - <p>When this property is set to a non-empty value, - <tp:member-ref>TonesDeferred</tp:member-ref> is emitted. - When any tones are played (i.e. whenever - <tp:member-ref>SendingTones</tp:member-ref> is emitted), - this property is reset to the empty string.</p> - </tp:docstring> - </property> - - <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred"> - <tp:added version="0.21.3" /> - <arg name="Tones" type="s"> - <tp:docstring>The new non-empty value of - <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when 'w' or 'W', indicating "wait for the user to continue", - is encountered while playing a DTMF string queued by - <tp:member-ref>MultipleTones</tp:member-ref> or - <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events - after the 'w', which have not yet been played, are placed in the - <tp:member-ref>DeferredTones</tp:member-ref> property and copied - into this signal's argument.</p> - - <p>When the channel handler is ready to continue, it MAY pass the - value of <tp:member-ref>DeferredTones</tp:member-ref> to - <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending. - Alternatively, it MAY ignore the deferred tones, or even play - different tones instead. Any deferred tones are discarded the next - time a tone is played.</p> - - <p>This signal SHOULD NOT be emitted if there is nothing left to play, - i.e. if the 'w' was the last character in the DTMF string.</p> - </tp:docstring> - </signal> - - <signal name="SendingTones" tp:name-for-bindings="Sending_Tones"> - <tp:added version="0.19.6" /> - <arg name="Tones" type="s"> - <tp:docstring>DTMF string (one or more events) that is to be played. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>DTMF tone(s)are being sent to all eligible streams in the channel. - The signal is provided to indicating the fact that the streams are - currently being used to send one or more DTMF tones, so any other - media input is not getting through to the audio stream. It also - serves as a cue for the - <tp:member-ref>StopTone</tp:member-ref> method.</p> - </tp:docstring> - </signal> - - <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones"> - <tp:added version="0.19.6" /> - <arg name="Cancelled" type="b"> - <tp:docstring>True if the DTMF tones were actively cancelled via - <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>DTMF tones have finished playing on streams in this channel.</p> - </tp:docstring> - </signal> - - <tp:enum name="DTMF_Event" type="y"> - <tp:enumvalue suffix="Digit_0" value="0"> - <tp:docstring>0</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_1" value="1"> - <tp:docstring>1</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_2" value="2"> - <tp:docstring>2</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_3" value="3"> - <tp:docstring>3</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_4" value="4"> - <tp:docstring>4</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_5" value="5"> - <tp:docstring>5</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_6" value="6"> - <tp:docstring>6</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_7" value="7"> - <tp:docstring>7</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_8" value="8"> - <tp:docstring>8</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Digit_9" value="9"> - <tp:docstring>9</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Asterisk" value="10"> - <tp:docstring>*</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Hash" value="11"> - <tp:docstring>#</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Letter_A" value="12"> - <tp:docstring>A</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Letter_B" value="13"> - <tp:docstring>B</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Letter_C" value="14"> - <tp:docstring>C</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Letter_D" value="15"> - <tp:docstring>D</tp:docstring> - </tp:enumvalue> - </tp:enum> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Destroyable.xml b/qt4/spec/Channel_Interface_Destroyable.xml deleted file mode 100644 index ce5592327..000000000 --- a/qt4/spec/Channel_Interface_Destroyable.xml +++ /dev/null @@ -1,82 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Destroyable" - 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:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, - USA.</p> - </tp:license> - - <interface - name="org.freedesktop.Telepathy.Channel.Interface.Destroyable"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:added version="0.17.14">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface exists to support channels where - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> - is insufficiently destructive. At the moment this means - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref>, - but the existence of this interface means that unsupported channels - can be terminated in a non-channel-type-specific way.</p> - </tp:docstring> - - <method name="Destroy" tp:name-for-bindings="Destroy"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Close the channel abruptly, possibly with loss of data. The - connection manager MUST NOT re-create the channel unless/until - more events occur.</p> - - <tp:rationale> - <p>The main motivating situation for this method is that when a Text - channel with pending messages is closed with Close, it comes back - as an incoming channel (to avoid a race between Close and an - incoming message). If Destroy is called on a Text channel, the CM - should delete all pending messages and close the channel, and - the channel shouldn't be re-created until/unless another message - arrives.</p> - </tp:rationale> - - <p>Most clients SHOULD call - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> - instead. However, if a client explicitly intends to destroy the - channel with possible loss of data, it SHOULD call this method - if this interface is supported (according to the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref> - property), falling back to Close if not.</p> - - <p>In particular, channel dispatchers SHOULD use this method if - available when terminating channels that cannot be handled - correctly (for instance, if no handler has been installed for - a channel type, or if the handler crashes repeatedly).</p> - - <p>Connection managers do not need to implement this interface on - channels where Close and Destroy would be equivalent.</p> - - <tp:rationale> - <p>Callers need to be able to fall back to Close in any case.</p> - </tp:rationale> - </tp:docstring> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Group.xml b/qt4/spec/Channel_Interface_Group.xml deleted file mode 100644 index 92de9c5c4..000000000 --- a/qt4/spec/Channel_Interface_Group.xml +++ /dev/null @@ -1,1166 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2006 INdT</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Group"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List"> - <tp:docstring>A structure representing a contact whose attempt to - join a group is to be confirmed by the local user using - <tp:member-ref>AddMembers</tp:member-ref>.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added"> - <tp:docstring> - The contact to be added to the group - </tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Contact_Handle" name="Actor"> - <tp:docstring> - The contact requesting or causing the change - </tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason"> - <tp:docstring> - The reason for the change - </tp:docstring> - </tp:member> - <tp:member type="s" name="Message"> - <tp:docstring> - A human-readable message from the Actor, or an empty string - if there is no message - </tp:docstring> - </tp:member> - </tp:struct> - - <method name="AddMembers" tp:name-for-bindings="Add_Members"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to invite to the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Invite all the given contacts into the channel, or accept requests for - channel membership for contacts on the pending local list.</p> - - <p>A message may be provided along with the request, which will be sent - to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and - CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT - <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this - message should be provided.</p> - - <p>Attempting to add contacts who are already members is allowed; - connection managers must silently accept this, without error.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> - </tp:possible-errors> - </method> - - <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members"> - <tp:deprecated version="0.17.6">Use GetAll on the D-Bus - Properties D-Bus interface to get properties including Members, - RemotePendingMembers and LocalPendingMembers instead, falling back to - this method and GetLocalPendingMembersWithInfo if necessary. - </tp:deprecated> - - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Members"> - <tp:docstring> - array of handles of current members - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Local_Pending"> - <tp:docstring> - array of handles of local pending members - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Remote_Pending"> - <tp:docstring> - array of handles of remote pending members - </tp:docstring> - </arg> - <tp:docstring> - Returns arrays of all current, local and remote pending channel - members. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u"> - <tp:flag suffix="Can_Add" value="1"> - <tp:docstring> - The <tp:member-ref>AddMembers</tp:member-ref> method can be used to - add or invite members who are - not already in the local pending list (which is always valid). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Can_Remove" value="2"> - <tp:docstring> - The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used - to remove channel members - (removing those on the pending local list is always valid). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Can_Rescind" value="4"> - <tp:docstring> - The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used - on people on the remote - pending list. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Add" value="8"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>AddMembers</tp:member-ref> on - contacts who are not currently pending members. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Remove" value="16"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are currently channel members. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Accept" value="32"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>AddMembers</tp:member-ref> on - contacts who are locally pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Reject" value="64"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are locally pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Rescind" value="128"> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - contacts who are remote pending. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Channel_Specific_Handles" value="256"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - The members of this group have handles which are specific to - this channel, and are not valid as general-purpose handles on - the connection. Depending on the channel, it may be possible to - check the <tp:member-ref>HandleOwners</tp:member-ref> property or - call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the - owners of these handles, which should be done if you wish to (e.g.) - subscribe to the contact's presence. - </p> - - <p> - Connection managers must ensure that any given handle is not - simultaneously a general-purpose handle and a channel-specific - handle. - </p> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Only_One_Group" value="512"> - <tp:docstring> - Placing a contact in multiple groups of this type is not allowed - and will raise NotAvailable (on services where contacts may only - be in one user-defined group, user-defined groups will have - this flag). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Handle_Owners_Not_Available" value="1024"> - <tp:docstring> - In rooms with channel specific handles (ie Channel_Specific_Handles - flag is set), this flag indicates that no handle owners are - available, apart from the owner of the - <tp:member-ref>SelfHandle</tp:member-ref>. - - <tp:rationale> - This used to be an important optimization to avoid repeated - GetHandleOwners calls, before we introduced the - <tp:member-ref>HandleOwners</tp:member-ref> property and - <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. - </tp:rationale> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Properties" value="2048"> - <tp:docstring> - This flag indicates that all the properties introduced in - specification 0.17.6 are fully supported. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Members_Changed_Detailed" value="4096"> - <tp:docstring> - Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref> - will be emitted for changes to this group's members in addition to - <tp:member-ref>MembersChanged</tp:member-ref>. - Clients can then connect to the former and ignore emission of the - latter. This flag's state MUST NOT change over the lifetime of a - channel. - - <tp:rationale> - If it were allowed to change, client bindings would have to always - connect to MembersChanged just in case the flag ever went away (and - generally be unnecessarily complicated), which would mostly negate - the point of having this flag in the first place. - </tp:rationale> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Message_Depart" value="8192"> - <tp:added version="0.17.21"/> - <tp:docstring> - A message may be sent to the server when calling - <tp:member-ref>RemoveMembers</tp:member-ref> on - the <tp:member-ref>SelfHandle</tp:member-ref>. - - <tp:rationale> - This would be set for XMPP Multi-User Chat or IRC channels, - but not for a typical implementation of streamed media calls. - </tp:rationale> - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags" - access="read" tp:name-for-bindings="Group_Flags"> - <tp:docstring> - An integer representing the bitwise-OR of flags on this - channel. The user interface can use this to present information about - which operations are currently valid. Change notification is via - the <tp:member-ref>GroupFlagsChanged</tp:member-ref> signal. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetGroupFlags if - Channel_Group_Flag_Properties is not present.</tp:added> - </property> - - <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags"> - <arg direction="out" type="u" tp:type="Channel_Group_Flags" - name="Group_Flags"> - <tp:docstring> - The value of the GroupFlags property - </tp:docstring> - </arg> - <tp:docstring> - Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use GetAll on the D-Bus - Properties D-Bus interface to get properties including GroupFlags - instead, falling back to this method if necessary.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:mapping name="Handle_Owner_Map"> - <tp:docstring> - A map from channel-specific handles to their owners. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetHandleOwners if - Channel_Group_Flag_Properties is not present.</tp:added> - - <tp:member type="u" name="Channel_Specific_Handle" - tp:type="Contact_Handle"> - <tp:docstring> - A nonzero channel-specific handle - </tp:docstring> - </tp:member> - <tp:member type="u" name="Global_Handle" tp:type="Contact_Handle"> - <tp:docstring> - The global handle that owns the corresponding channel-specific - handle, or 0 if this could not be determined - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map" - access="read" tp:name-for-bindings="Handle_Owners"> - <tp:docstring> - A map from channel-specific handles to their owners, including - at least all of the channel-specific handles in this channel's members, - local-pending or remote-pending sets as keys. Any handle not in - the keys of this mapping is not channel-specific in this channel. - Handles which are channel-specific, but for which the owner is - unknown, MUST appear in this mapping with 0 as owner. Change - notification is via the - <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. - </tp:docstring> - <tp:added version="0.17.6"/> - </property> - - <signal name="HandleOwnersChanged" - tp:name-for-bindings="Handle_Owners_Changed"> - <tp:docstring> - Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref> - property changes. - </tp:docstring> - <tp:added version="0.17.6">This signal should not be relied on - unless Channel_Group_Flag_Properties is present.</tp:added> - - <arg name="Added" type="a{uu}" tp:type="Handle_Owner_Map"> - <tp:docstring> - A map from channel-specific handles to their owners, in which the - keys include all the handles that were added to the keys of the - HandleOwners property, and all the handles in that property whose - owner has changed - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The channel-specific handles that were removed from the keys of the - HandleOwners property, as a result of the contact leaving this group - in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal - </tp:docstring> - </arg> - </signal> - - <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners"> - <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of integer handles representing members of the channel - </tp:docstring> - </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners"> - <tp:docstring> - An array of integer handles representing the owner handles of - the given room members, in the same order, or 0 if the - owner is not available - </tp:docstring> - </arg> - <tp:docstring> - If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on - the channel, then the handles of the group members are specific - to this channel, and are not meaningful in a connection-wide - context such as contact lists. This method allows you to find - the owner of the handle if it can be discovered in this channel, - or 0 if the owner is not available. - </tp:docstring> - <tp:deprecated version="0.17.6">Clients should use the - HandleOwners property and HandleOwnersChanged signal if - Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag, - so handles in this channel are globally meaningful and calling - this method is not necessary - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - One of the given handles is not a member - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetLocalPendingMembers" - tp:name-for-bindings="Get_Local_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns the To_Be_Added handle (only) for each structure in the - <tp:member-ref>LocalPendingMembers</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the LocalPendingMembers - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <method name="GetLocalPendingMembersWithInfo" - tp:name-for-bindings="Get_Local_Pending_Members_With_Info"> - <tp:added version="0.15.0" /> - <tp:docstring> - Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the LocalPendingMembers - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]" - name="Info"> - <tp:docstring> - An array of structs containing: - <ul> - <li> - A handle representing the contact requesting channel membership - </li> - <li> - A handle representing the contact making the request, or 0 if - unknown - </li> - <li> - The reason for the request: one of the values of - <tp:type>Channel_Group_Change_Reason</tp:type> - </li> - <li> - A string message containing the reason for the request if any (or - blank if none) - </li> - </ul> - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <property name="LocalPendingMembers" access="read" - type="a(uuus)" tp:type="Local_Pending_Info[]" - tp:name-for-bindings="Local_Pending_Members"> - <tp:docstring> - An array of structs containing handles representing contacts - requesting channel membership and awaiting local approval with - <tp:member-ref>AddMembers</tp:member-ref>. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties is - not present, clients should fall back to using the - deprecated GetLocalPendingMembersWithInfo method, or fall back - from that to the deprecated GetAllMembers method.</tp:added> - </property> - - <property name="Members" tp:name-for-bindings="Members" - access="read" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The members of this channel. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties - is not set, fall back to calling GetAllMembers.</tp:added> - </property> - - <method name="GetMembers" tp:name-for-bindings="Get_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns the <tp:member-ref>Members</tp:member-ref> property. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the Members - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <property name="RemotePendingMembers" access="read" type="au" - tp:type="Contact_Handle[]" tp:name-for-bindings="Remote_Pending_Members"> - <tp:docstring> - An array of handles representing contacts who have been - invited to the channel and are awaiting remote approval. - </tp:docstring> - <tp:added version="0.17.6">If Channel_Group_Flag_Properties - is not set, fall back to calling GetAllMembers.</tp:added> - </property> - - <method name="GetRemotePendingMembers" - tp:name-for-bindings="Get_Remote_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]" - name="Handles"/> - <tp:docstring> - Returns an array of handles representing contacts who have been - invited to the channel and are awaiting remote approval. - </tp:docstring> - <tp:deprecated version="0.17.6">Use the - <tp:member-ref>RemotePendingMembers</tp:member-ref> - property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed"> - <tp:docstring> - Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property - changes. - </tp:docstring> - <tp:added version="0.17.6">This signal should not be relied on - unless Channel_Group_Flag_Properties is present.</tp:added> - - <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> - <tp:docstring> - The new value of the SelfHandle property. - </tp:docstring> - </arg> - </signal> - - <property name="SelfHandle" type="u" tp:type="Contact_Handle" - access="read" tp:name-for-bindings="Self_Handle"> - <tp:docstring> - The handle for the user on this channel (which can also be a - local or remote pending member), or 0 if the user is not a member at - all (which is likely to be the case, for instance, on <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref> - channels). Note that this is different from the result of - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref> - on some protocols, so the value of this handle should - always be used with the methods of this interface. - </tp:docstring> - <tp:added version="0.17.6">For backwards compatibility, - clients should fall back to calling GetSelfHandle if - Channel_Group_Flag_Properties is not present.</tp:added> - </property> - - <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle" - name="Self_Handle"/> - <tp:docstring> - Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref> - property. - </tp:docstring> - <tp:deprecated version="0.17.6">Clients should retrieve the - SelfHandle property using GetAll instead, - if Channel_Group_Flag_Properties is present.</tp:deprecated> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <signal name="GroupFlagsChanged" tp:name-for-bindings="Group_Flags_Changed"> - <arg name="Added" type="u" tp:type="Channel_Group_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been set - </tp:docstring> - </arg> - <arg name="Removed" type="u" tp:type="Channel_Group_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been cleared - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the flags as returned by - <tp:member-ref>GetGroupFlags</tp:member-ref> are changed. - The user interface should be updated as appropriate. - </tp:docstring> - </signal> - - <tp:enum name="Channel_Group_Change_Reason" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The reason for a set of handles to move to one of - <tp:member-ref>Members</tp:member-ref>, - <tp:member-ref>LocalPendingMembers</tp:member-ref> or - <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed - from the group. A client may supply a reason when attempting to - remove members from a group with - <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons - are supplied by the CM when emitting - <tp:member-ref>MembersChanged</tp:member-ref> and - <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason - codes have different meanings depending on the <var>Actor</var> in a - MembersChanged signal.</p> - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>No reason was provided for this change.</p> - - <p>In particular, this reason SHOULD be used when representing - users joining a named chatroom in the usual way, users leaving - a chatroom by their own request, and normal termination of a - StreamedMedia call by the remote user.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed from - a group for this reason and the actor is not the SelfHandle, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Terminated</code>.</p> - - <p>If the SelfHandle is removed from a group for this reason and - the actor is also the SelfHandle, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Offline" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a user going offline. Also used when - user is already offline, but this wasn't known previously.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called is offline, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason Offline.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If a handle is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Offline</code>.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Kicked" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a kick operation.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Busy" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a busy indication.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called is busy, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason Busy.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Busy</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invited" value="4"> - <tp:docstring> - The change is due to an invitation. This reason SHOULD only be used - when contacts are added to the remote-pending set (to indicate that - the contact has been invited) or to the members (to indicate that - the contact has accepted the invitation). - - <tp:rationale> - Otherwise, what would it mean? - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Banned" value="5"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is due to a kick+ban operation.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed - from a group for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Error" value="6"> - <tp:docstring> - The change is due to an error occurring. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invalid_Contact" value="7"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because the requested contact does not exist.</p> - - <p>For instance, if the user invites a nonexistent contact to a - chatroom or attempts to call a nonexistent contact, this could - be indicated by the CM adding that contact's handle to - remote-pending for reason None or Invited, then removing it for - reason Invalid_Contact. In the case of a 1-1 StreamedMedia - call, the CM SHOULD remove the self handle from the Group - in the same signal.</p> - - <tp:rationale> - For 1-1 calls, the call terminates as a result of removing the - remote contact, so the SelfHandle should be removed at the same - time as the remote contact and for the same reason. - </tp:rationale> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="No_Answer" value="8"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because the requested contact did not respond.</p> - - <p>If a one-to-one <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called did not respond, or the - local user did not respond to an incoming call, the - connection manager SHOULD indicate this by removing both the - <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's - handle from the Group interface with reason No_Answer.</p> - - <tp:rationale> - Documenting existing practice. - </tp:rationale> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.NoAnswer</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Renamed" value="9"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because a contact's unique identifier changed. - There must be exactly one handle in the removed set and exactly - one handle in one of the added sets. The <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref> - signal on the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref> - interface will have been emitted for the same handles, - shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Permission_Denied" value="10"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is because there was no permission to contact the - requested handle.</p> - - <p>If a contact is removed from a group for this reason, the - equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>. - </p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Separated" value="11"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If members are removed with this reason code, the change is - because the group has split into unconnected parts which can only - communicate within themselves (e.g. netsplits on IRC use this - reason code). - </p> - <p> - If members are added with this reason code, the change is because - unconnected parts of the group have rejoined. If this channel - carries messages (e.g. <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref> - channels) applications must - assume that the contacts being added are likely to have missed some - messages as a result of the separation, and that the contacts - in the group are likely to have missed some messages from the - contacts being added. - </p> - <p>Note that from the added contacts' perspective, they have been - in the group all along, and the contacts we indicate to be in - the group (including the local user) have just rejoined - the group with reason Separated. Application protocols in Tubes - should be prepared to cope with this situation. - </p> - - <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be - removed from channels with this reason.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="MembersChanged" tp:name-for-bindings="Members_Changed"> - <arg name="Message" type="s"> - <tp:docstring> - A string message from the server, or blank if not - </tp:docstring> - </arg> - <arg name="Added" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members added to the channel - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members removed from the channel - </tp:docstring> - </arg> - <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending local approval - </tp:docstring> - </arg> - <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending remote approval - </tp:docstring> - </arg> - <arg name="Actor" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact handle of the person who made the change, or 0 - if not known - </tp:docstring> - </arg> - <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason"> - <tp:docstring> - A reason for the change - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when contacts join any of the three lists (members, local - pending or remote pending) or when they leave any of the three lists. - There may also be a message from the server regarding this change, - which may be displayed to the user if desired.</p> - - <p>All channel-specific handles that are mentioned in this signal - MUST be represented in the value of the - <tp:member-ref>HandleOwners</tp:member-ref> property. - In practice, this will mean that - <tp:member-ref>HandleOwnersChanged</tp:member-ref> is - emitted <em>before</em> emitting a MembersChanged signal in which - channel-specific handles are added, but that it is emitted - <em>after</em> emitting a MembersChanged signal in which - channel-specific handles are removed.</p> - - <p>See <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - for an overview of how group state changes are used to indicate the - progress of a call.</p> - </tp:docstring> - </signal> - - <tp:mapping name="Handle_Identifier_Map"> - <tp:docstring> - A map from handles to the corresponding normalized string identifier. - </tp:docstring> - <tp:added version="0.17.17"/> - - <tp:member type="u" name="Handle" tp:type="Contact_Handle"> - <tp:docstring> - A nonzero handle - </tp:docstring> - </tp:member> - <tp:member type="s" name="Identifier"> - <tp:docstring> - The same string that would be returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> - for this handle. - </tp:docstring> - </tp:member> - </tp:mapping> - - <signal name="MembersChangedDetailed" - tp:name-for-bindings="Members_Changed_Detailed"> - <arg name="Added" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members added to the channel - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members removed from the channel - </tp:docstring> - </arg> - <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending local approval - </tp:docstring> - </arg> - <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who are pending remote approval - </tp:docstring> - </arg> - <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Information about the change, which may include the following - well-known keys:</p> - - <dl> - <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt> - <dd>The contact handle of the person who made the change; 0 or - omitted if unknown or not applicable.</dd> - - <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt> - <dd>A reason for the change.</dd> - - <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt> - <dd> - <p>The string identifiers for handles mentioned in this signal, to - give clients the minimal information necessary to react to the - event without waiting for round-trips. Connection managers - SHOULD include the identifiers for members added to the group and - for the actor (if any); they MAY omit the identifiers for handles - which have been removed from the group.</p> - - <tp:rationale> - <p>On IRC, an event such as a netsplit could cause the vast - majority of a channel to leave. Given that clients should - already know the identifiers of a channel's members, including - potentially hundreds of strings in the netsplit signal is - unnecessary.</p> - </tp:rationale> - - <p>Clients MUST NOT assume that the presence or absence of a - handle in this mapping is meaningful. This mapping is merely - an optimization for round-trip reduction, and connection - managers MAY add additional handles, omit some handles, or - omit the mapping completely.</p> - </dd> - - <dt>message (s)</dt> - <dd>A string message from the server regarding the change</dd> - - <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt> - <dd>A (possibly implementation-specific) DBus error describing the - change, providing more specific information than the - <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This - MUST only be present if it is strictly more informative than - 'change-reason'; if present, 'change-reason' MUST be set to the - closest available reason. - - <tp:rationale> - A SIP connection manager might want to signal "402 Payment - required" as something more specific than Error or - Permission_Denied so that a SIP-aware UI could handle it - specially; including a namespaced error permits this to be done - without <tp:type>Channel_Group_Change_Reason</tp:type> being - extended to encompass every error any CM ever wants to report. - </tp:rationale> - </dd> - - <dt>debug-message (s)</dt> - <dd>Debugging information on the change. SHOULD NOT be shown to - users in normal circumstances.</dd> - </dl> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when contacts join any of the three lists (members, local - pending or remote pending) or when they leave any of the three - lists. This signal provides a superset of the information provided by - <tp:member-ref>MembersChanged</tp:member-ref>; - if the channel's <tp:member-ref>GroupFlags</tp:member-ref> - contains Members_Changed_Detailed, then clients may listen exclusively - to this signal in preference to that signal.</p> - - <p>All channel-specific handles that are mentioned in this signal - MUST be represented in the value of the - <tp:member-ref>HandleOwners</tp:member-ref> property. In practice, - this will mean that - <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted - <em>before</em> emitting a MembersChangedDetailed signal in which - channel-specific handles are added, but that it is emitted - <em>after</em> emitting a MembersChangedDetailed signal in which - channel-specific handles are removed.</p> - - <p>See <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - for an overview of how group state changes are used to indicate the - progress of a call.</p> - </tp:docstring> - <tp:added version="0.17.16"/> - </signal> - - <method name="RemoveMembers" tp:name-for-bindings="Remove_Members"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to remove from the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Requests the removal of contacts from a channel, reject their - request for channel membership on the pending local list, or - rescind their invitation on the pending remote list.</p> - - <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group, - it can be removed via this method, in order to leave the group - gracefully. This is the recommended way to leave a chatroom, close - or reject a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call, and so on.</p> - - <p>Accordingly, connection managers SHOULD support - doing this, regardless of the value of - <tp:member-ref>GroupFlags</tp:member-ref>. - If doing so fails with PermissionDenied, this is considered to a bug - in the connection manager, but clients MUST recover by falling back - to closing the channel with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - method.</p> - - <p>Removing any contact from the local pending list is always - allowed. Removing contacts other than the - <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members - is allowed if and only if Channel_Group_Flag_Can_Remove is in the - <tp:member-ref>GroupFlags</tp:member-ref>, - while removing contacts other than the - <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list - is allowed if and only if Channel_Group_Flag_Can_Rescind is in the - <tp:member-ref>GroupFlags</tp:member-ref>.</p> - - <p>A message may be provided along with the request, which will be - sent to the server if supported. See the - Channel_Group_Flag_Message_Remove, - Channel_Group_Flag_Message_Depart, - Channel_Group_Flag_Message_Reject and - Channel_Group_Flag_Message_Rescind - <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this - message should be provided.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="RemoveMembersWithReason" - tp:name-for-bindings="Remove_Members_With_Reason"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of contact handles to remove from the channel - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A string message, which can be blank if desired - </tp:docstring> - </arg> - <arg direction="in" name="Reason" type="u" - tp:type="Channel_Group_Change_Reason"> - <tp:docstring> - A reason for the change - </tp:docstring> - </arg> - <tp:docstring> - As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may - be provided where - appropriate. The reason code may be ignored if the underlying - protocol is unable to represent the given reason. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The provided reason code was invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for channels which have multiple members, and where the members - of the channel can change during its lifetime. Your presence in the channel - cannot be presumed by the channel's existence (for example, a channel you - may request membership of but your request may not be granted).</p> - - <p>This interface implements three lists: a list of current members - (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending - and remote pending members - (<tp:member-ref>LocalPendingMembers</tp:member-ref> and - <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively). - Contacts on the remote - pending list have been invited to the channel, but the remote user has not - accepted the invitation. Contacts on the local pending list have requested - membership of the channel, but the local user of the framework must accept - their request before they may join. A single contact should never appear on - more than one of the three lists. The lists are empty when the channel is - created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal - (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains - Members_Changed_Detailed, the - <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal) - should be emitted when information - is retrieved from the server, or changes occur.</p> - - <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or - <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates - that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from - the channel, and the channel subsequently emits <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>, - clients SHOULD consider the details given in the MembersChanged or - MembersChangedDetailed signal to be the reason why the channel closed.</p> - - <p>Addition of members to the channel may be requested by using - <tp:member-ref>AddMembers</tp:member-ref>. If - remote acknowledgement is required, use of the AddMembers method will cause - users to appear on the remote pending list. If no acknowledgement is - required, AddMembers will add contacts to the member list directly. If a - contact is awaiting authorisation on the local pending list, AddMembers - will grant their membership request.</p> - - <p>Removal of contacts from the channel may be requested by using - <tp:member-ref>RemoveMembers</tp:member-ref>. If a contact is awaiting - authorisation on the local pending - list, RemoveMembers will refuse their membership request. If a contact is - on the remote pending list but has not yet accepted the invitation, - RemoveMembers will rescind the request if possible.</p> - - <p>It should not be presumed that the requester of a channel implementing this - interface is immediately granted membership, or indeed that they are a - member at all, unless they appear in the list. They may, for instance, - be placed into the remote pending list until a connection has been - established or the request acknowledged remotely.</p> - - <p>If the local user joins a Group channel whose members or other state - cannot be discovered until the user joins (e.g. many chat room - implementations), the connection manager should ensure that the channel - is, as far as possible, in a consistent state before adding the local - contact to the members set; until this happens, the local contact should - be in the remote-pending set. For instance, if the connection manager - queries the server to find out the initial members list for the - channel, it should leave the local contact in the remote-pending set - until it has finished receiving the initial members list. - </p> - - <p>If the protocol provides no reliable way to tell whether the complete - initial members list has been received yet, the connection manager - should make a best-effort attempt to wait for the full list - (in the worst case, waiting for a suitable arbitrary timeout) - rather than requiring user interfaces to do so on its behalf.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_HTML.xml b/qt4/spec/Channel_Interface_HTML.xml deleted file mode 100644 index ad86867ca..000000000 --- a/qt4/spec/Channel_Interface_HTML.xml +++ /dev/null @@ -1,86 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_HTML" - 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:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Channel.Interface.HTML.DRAFT" - tp:causes-havoc="unfinished"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> - <tp:requires - interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> - <tp:added version="0.17.5">(draft version, not API-stable)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface extends the Messages interface to support - capability discovery, so clients can decide what subset of HTML - is supported.</p> - - <p>(However, the capability discovery mechanism has not been written - yet, so this interface MUST NOT be used. It exists only to - indicate what direction we intend to go in.)</p> - - <tp:rationale> - <p>XMPP supports all of XHTML-IM, and SIP (at least theoretically) - supports all of XHTML. However, many protocols are more limited - - for instance, in MSN you can only set font properties for a - whole message at a time. We should not mislead users into thinking - they can send MSN messages where individual words are emphasized.</p> - </tp:rationale> - - <p>If this interface is present, clients MAY send XHTML formatted text - in message parts with type "text/html", and SHOULD interpret - "text/html" message parts received in reply.</p> - - <p>Client authors SHOULD pay careful attention to the security - considerations in XEP-0071, "XHTML-IM", to avoid exposing client users - to security risks. Clients MUST NOT assume that connection managers - will filter messages to remove unsafe HTML.</p> - - <tp:rationale> - <p>Connection managers are the components in Telepathy that are most - likely to be exploitable by a remote attacker to run malicious code - (since they are network-facing), so any filtering that the CM does - might be subverted.</p> - </tp:rationale> - - <p>To avoid misleading users, clients SHOULD only present UI for the - subset of HTML that is indicated to be supported by this - interface. It follows that clients SHOULD NOT send unsupported - markup to the connection manager. However, even if the connection - manager cannot send arbitrary XHTML, it MUST cope gracefully - with being given arbitrary XHTML by a client.</p> - - <tp:rationale> - <p>Connection managers should be lenient in what they receive.</p> - </tp:rationale> - - <p>Clients MUST NOT send HTML that is not well-formed XML, but - connection managers MAY signal HTML that is malformed or invalid. - Clients SHOULD attempt to parse messages as XHTML, but fall back - to using a permissive "tag-soup" HTML parser if that fails. - (FIXME: or should the presence of this interface imply that the - CM fixes up "text/html" to be XHTML? In practice that would result - in all the CMs having to link against libxml2 or something... the - rationale above no longer applies here, since dropping a malformed - message is "safe")</p> - </tp:docstring> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Hold.xml b/qt4/spec/Channel_Interface_Hold.xml deleted file mode 100644 index ef5a08f19..000000000 --- a/qt4/spec/Channel_Interface_Hold.xml +++ /dev/null @@ -1,222 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Hold" 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:license xmlns="http://www.w3.org/1999/xhtml"> -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. - -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. - -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. - </tp:license> - - <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"> - <tp:xor-requires> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> - </tp:xor-requires> - <tp:changed version="0.17.4">first API-stable version</tp:changed> - - <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. (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 - any media streams you continue to receive. It also requests that the - connection manager free up any resources that are only needed for - an actively used channel (e.g. in a GSM or PBX call, it will be - necessary to place an active call on hold before you can start - another call).</p> - </tp:docstring> - - <method name="GetHoldState" tp:name-for-bindings="Get_Hold_State"> - <tp:docstring> - Return whether the local user has placed the channel on hold. - </tp:docstring> - - <arg name="HoldState" direction="out" type="u" - tp:type="Local_Hold_State"> - <tp:docstring> - The state of the channel - </tp:docstring> - </arg> - - <arg name="Reason" direction="out" type="u" - tp:type="Local_Hold_State_Reason"> - <tp:docstring> - The reason why the channel is in that state - </tp:docstring> - </arg> - </method> - - <signal name="HoldStateChanged" tp:name-for-bindings="Hold_State_Changed"> - <tp:docstring> - Emitted to indicate that the hold state has changed for this channel. - This may occur as a consequence of you requesting a change with - <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a - result of a request from - another process. - </tp:docstring> - - <arg name="HoldState" type="u" tp:type="Local_Hold_State"> - <tp:docstring> - The state of the channel - </tp:docstring> - </arg> - - <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason"> - <tp:docstring> - The reason for the state change - </tp:docstring> - </arg> - </signal> - - <tp:enum name="Local_Hold_State" type="u"> - <tp:docstring> - The hold state of a channel. - </tp:docstring> - - <tp:enumvalue value="0" suffix="Unheld"> - <tp:docstring> - All streams are unheld (the call is active). New channels SHOULD - have this hold state. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="1" suffix="Held"> - <tp:docstring> - All streams are held (the call is on hold) - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="2" suffix="Pending_Hold"> - <tp:docstring> - The connection manager is attempting to move to state Held, but - has not yet completed that operation. It is unspecified whether - any, all or none of the streams making up the channel are on hold. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="3" suffix="Pending_Unhold"> - <tp:docstring> - The connection manager is attempting to move to state Held, but - has not yet completed that operation. It is unspecified whether - any, all or none of the streams making up the channel are on hold. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Local_Hold_State_Reason" type="u"> - <tp:docstring> - The reason for a change to the Local_Hold_State. Clients MUST - treat unknown values as equivalent to Local_Hold_State_Reason_None. - </tp:docstring> - - <tp:enumvalue value="0" suffix="None"> - <tp:docstring> - The reason cannot be described by any of the predefined values - (connection managers SHOULD avoid this reason, but clients MUST - handle it gracefully) - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="1" suffix="Requested"> - <tp:docstring> - The change is in response to a user request - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="2" suffix="Resource_Not_Available"> - <tp:docstring> - The change is because some resource was not available - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <method name="RequestHold" tp:name-for-bindings="Request_Hold"> - <arg direction="in" name="Hold" type="b"> - <tp:docstring> - A boolean indicating whether or not the channel should be on hold - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that the channel be put on hold (be instructed not to send - any media streams to you) or be taken off hold.</p> - - <p>If the connection manager can immediately tell that the requested - state change could not possibly succeed, this method SHOULD - return the NotAvailable error. If the requested state is the - same as the current state, this method SHOULD return successfully - without doing anything.</p> - - <p>Otherwise, this method SHOULD immediately set the hold state to - Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold - (as appropriate), emitting - <tp:member-ref>HoldStateChanged</tp:member-ref> if this is a change, - and return successfully.</p> - - <p>The eventual success or failure of the request is indicated by a - subsequent HoldStateChanged signal, changing the hold state to - Local_Hold_State_Held or Local_Hold_State_Unheld.</p> - - <p>If the channel has multiple streams, and the connection manager - succeeds in changing the hold state of one stream but fails to - change the hold state of another, it SHOULD attempt to revert - all streams to their previous hold states.</p> - - <p>The following state transitions SHOULD be used, where - appropriate:</p> - - <ul> - <li>Successful hold: - (Unheld, any reason) → (Pending_Hold, Requested) → - (Held, Requested) - </li> - <li>Successful unhold: - (Held, any reason) → (Pending_Unhold, Requested) → - (Unheld, Requested) - </li> - <li>Attempting to unhold fails at the first attempt to acquire a - resource: - (Held, any reason) → (Pending_Unhold, Requested) → - (Held, Resource_Not_Available) - </li> - <li>Attempting to unhold acquires one resource, but fails to acquire - a second, and takes time to release the first: - (Held, any reason) → (Pending_Unhold, Requested) → - (Pending_Hold, Resource_Not_Available) → - (Held, Resource_Not_Available) - </li> - </ul> - </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:docstring> - The requested hold state cannot be achieved; for example, - if only a limited number of channels can be in the "not on hold" - state, attempts to exceed this number will raise NotAvailable. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Media_Signalling.xml b/qt4/spec/Channel_Interface_Media_Signalling.xml deleted file mode 100644 index 242c95284..000000000 --- a/qt4/spec/Channel_Interface_Media_Signalling.xml +++ /dev/null @@ -1,235 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for signalling a channel containing synchronised media - sessions which can contain an arbitrary number of streams. The - presence of this interface on a Channel indicates that the connection - manager will not carry out the actual streaming for this channel, - and that the client handling the channel is responsible for doing - so; in most cases we recommend doing this by using the - telepathy-farsight library.</p> - - <tp:rationale> - <p>Streaming audio and (particularly) video requires a high level of - integration with the UI, and having the connection manager act as - a proxy would be likely to introduce unacceptable latency. As a - result, audio/video streaming is offloaded into the client - where possible, as an exception to the general design of - Telepathy.</p> - </tp:rationale> - - <p>The negotiation interface is based on the API of the - <a href="http://farsight.freedesktop.org/">Farsight</a> library. - This, in turn, is based upon the IETF MMusic ICE drafts, where - connections are established by signalling potential connection - candidates to the peer until a usable connection is found, and - codecs are negotiated with an SDP-style offer and answer. However, - the principles should be applicable to other media streaming methods - and the API re-used without difficulty.</p> - - <p>Note that the naming conventions used in the MediaStreamHandler - and MediaSessionHandler interfaces are rather confusing; methods - have signal-like names and signals have method-like names, due to - the API being based rather too closely on that of Farsight. This - is for historical reasons and will be fixed in a future release - of the Telepathy specification.</p> - </tp:docstring> - - <tp:simple-type name="Media_Session_Type" type="s"> - <tp:docstring>The type of a media session. Currently, the only supported - value is "rtp".</tp:docstring> - </tp:simple-type> - - <tp:struct name="Media_Session_Handler_Info" - array-name="Media_Session_Handler_Info_List"> - <tp:docstring>A struct representing a active session handler.</tp:docstring> - <tp:member type="o" name="Session_Handler"> - <tp:docstring>The object path of the session handler, which is on the - same bus name as the channel.</tp:docstring> - </tp:member> - <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type"> - <tp:docstring>The media session's type</tp:docstring> - </tp:member> - </tp:struct> - - <method name="GetSessionHandlers" - tp:name-for-bindings="Get_Session_Handlers"> - <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]" - name="Session_Handlers"/> - <tp:docstring> - Returns all currently active session handlers on this channel - as a list of (session_handler_path, type). - </tp:docstring> - </method> - - <signal name="NewSessionHandler" tp:name-for-bindings="New_Session_Handler"> - <arg name="Session_Handler" type="o"> - <tp:docstring> - Object path of the new <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Media.SessionHandler</tp:dbus-ref> - object - </tp:docstring> - </arg> - <arg name="Session_Type" tp:type="Media_Session_Type" type="s"> - <tp:docstring> - String indicating type of session, eg "rtp" - </tp:docstring> - </arg> - <tp:docstring> - Signal that a session handler object has been created. The client - should create a session object and create streams for the streams - within. - </tp:docstring> - </signal> - - <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 - 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. - </tp:docstring> - </tp:property> - - <tp:hct name="gtalk-p2p"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property is <code>gtalk-p2p</code>.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="ice-udp"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property is <code>ice-udp</code>.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="wlm-8.5"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property is <code>wlm-8.5</code>.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="wlm-2009"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property is <code>wlm-2009</code>.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="video/h264" is-family="yes"> - <tp:docstring> - <p>The client supports media streaming with H264 (etc.).</p> - - <p>This handler capability token is a one of a family - of similar tokens: for any other audio or video codec whose MIME - type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler - capability token of this form may exist (the subtype MUST appear - in lower case in this context). Clients MAY support more - codecs than they explicitly advertise support for; clients SHOULD - explicitly advertise support for their preferred codec(s), and - for codecs like H264 that are, in practice, significant in codec - negotiation.</p> - - <tp:rationale> - <p>For instance, the XMPP capability used by the Google Video - Chat web client to determine whether a client is compatible - with it requires support for H264 video, so an XMPP - connection manager that supports this version of Jingle should - not advertise the Google Video Chat capability unless there - is at least one installed client that declares that it supports - <code>video/h264</code> on StreamedMedia channels.</p> - </tp:rationale> - - <p>For example, a client could advertise support for - Speex, Theora and H264 by having three - handler capability tokens, - <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>, - <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and - <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>, - in its <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> - property.</p> - - <p>Clients MAY have media signalling abilities without explicitly - supporting any particular codec, and connection managers SHOULD - support this usage.</p> - - <tp:rationale> - <p>This is necessary to support gatewaying between two Telepathy - connections, in which case the available codecs might not be - known to the gatewaying process.</p> - </tp:rationale> - </tp:docstring> - </tp:hct> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Mergeable_Conference.xml b/qt4/spec/Channel_Interface_Mergeable_Conference.xml deleted file mode 100644 index cd606c1b7..000000000 --- a/qt4/spec/Channel_Interface_Mergeable_Conference.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Mergeable_Conference" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Conference"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for multi-user conference channels that can have - additional individual channels merged into them after they are - created.</p> - - <tp:rationale> - <p>This interface addresses part of freedesktop.org <a - href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug - #24906</a> (GSM-compatible conference calls). GSM is currently - the only protocol known to implement this; PBXs might implement - it too.</p> - - <p>It might be made into a mandatory-to-implement part of Conference, - or kept as a separate interface, when stabilized.</p> - </tp:rationale> - </tp:docstring> - - <method name="Merge" - tp:name-for-bindings="Merge"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that the given channel be incorporated into this - channel.</p> - - <p>The given channel SHOULD be added to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface" - >Conference.Channels</tp:dbus-ref> if and only if the - underlying protocol signals the merge in some way. It MUST NOT be - added to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface" - >Conference.InitialChannels</tp:dbus-ref> (to preserve - immutability).</p> - - <tp:rationale> - <p>In GSM it is possible to merge additional calls into an ongoing - conference.</p> - - <p>In XMPP this method could be implemented to merge a 1-1 Text - channel into a MUC Text channel by inviting the peer from the Text - channel into the MUC, or to merge a 1-1 Jingle call into a Muji - call by inviting the peer from the Jingle call into the Muji call. - (MUC and Muji channels are both implemented by XMPP MUCs, with - Handle_Type_Room.)</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Channel" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel with the same <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref> - as this one, but with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref> = CONTACT.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given channel isn't suitable for merging into this one: for - instance, it might have the wrong channel type or handle type. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It will never be possible to merge channels into this particular - conference. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The given channel is theoretically suitable for merging into this - one, but that's not currently possible for some reason (for - instance, this SHOULD be raised if a limit on the number of - channels in a conference is exceeded). - <strong>[FIXME: PermissionDenied?]</strong> - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> diff --git a/qt4/spec/Channel_Interface_Messages.xml b/qt4/spec/Channel_Interface_Messages.xml deleted file mode 100644 index 62e83846a..000000000 --- a/qt4/spec/Channel_Interface_Messages.xml +++ /dev/null @@ -1,1433 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Messages" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2008–2010 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.Channel.Interface.Messages"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> - <tp:added version="0.17.16">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface extends the <tp:dbus-ref - namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref> - interface to support more general messages, including:</p> - - <ul> - <li>messages with attachments (like MIME multipart/mixed)</li> - <li>groups of alternatives (like MIME multipart/alternative)</li> - <li>delivery reports (which replace <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>), - addding support for protocols where the message content is not echoed - back to the sender on failure and for receiving positive - acknowledgements, as well as ensuring that incoming delivery reports - are not lost if no client is handling the channel yet;</li> - <li>any extra types of message we need in future</li> - </ul> - - <p>Incoming messages, outgoing messages, and delivery reports are all - represented as lists of <tp:type>Message_Part</tp:type> structures, - with a format reminiscent of e-mail. Messages are sent by calling - <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are - announced to other clients which may be interested in the channel by - the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming - messages and delivery reports are signalled by - <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the - the <tp:member-ref>PendingMessages</tp:member-ref> property until - acknowledged by calling <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>. - Only the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> - for a channel should acknowledge messages; <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s - (such as loggers) and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s - for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p> - - <tp:rationale> - <p>If observers were allowed to acknowledge messages, then messages - might have been acknowledged before the handler even got to see the - channel, and hence could not be shown to the user.</p> - </tp:rationale> - - <p>If this interface is present, clients that support it SHOULD - listen for the <tp:member-ref>MessageSent</tp:member-ref> and - <tp:member-ref>MessageReceived</tp:member-ref> signals, and - ignore the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> - signals on the Text interface (which are guaranteed to duplicate - signals from this interface).</p> - - <p>Although this specification supports formatted (rich-text) - messages with unformatted alternatives, implementations SHOULD NOT - attempt to send formatted messages until the Telepathy specification - has also been extended to cover capability discovery for message - formatting.</p> - - <tp:rationale> - We intend to expose all rich-text messages as XHTML-IM, but on some - protocols, formatting is an extremely limited subset of that format - (e.g. there are protocols where foreground/background colours, font - and size can be set, but only for entire messages). - Until we can tell UIs what controls to offer to the user, it's - unfriendly to offer the user controls that may have no effect. - </tp:rationale> - </tp:docstring> - - <property name="SupportedContentTypes" type="as" access="read" - tp:name-for-bindings="Supported_Content_Types" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of MIME types supported by this channel, with more preferred - MIME types appearing earlier in the list. The list MAY include "*/*" - to indicate that attachments with arbitrary MIME types can be sent. - This list MUST NOT be empty, since all Messages implementations - MUST accept messages containing a single "text/plain" part.</p> - - <p>Items in this list MUST be normalized to lower-case.</p> - - <p>Some examples of how this property interacts with the - <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p> - - <dl> - <dt>A simple IM implementation: only plain text messages are - allowed</dt> - <dd>SupportedContentTypes = ['text/plain'], - MessagePartSupportFlags = 0</dd> - - <dt>Formatted text with a plain text alternative is allowed (see the - HTML interface draft)</dt> - <dd>SupportedContentTypes = ['text/html', 'text/plain'], - MessagePartSupportFlags = 0</dd> - - <dt>JPEG or PNG images may be sent, but without any attached - text</dt> - <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', - 'image/png'], MessagePartSupportFlags = 0</dd> - - <dt>Unformatted text to which an optional JPEG or PNG image may be - attached</dt> - <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', - 'image/png'], MessagePartSupportFlags = One_Attachment</dd> - - <dt>Formatted text to which arbitrarily many images may be - attached</dt> - <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg', - 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags = - One_Attachment | Multiple_Attachments</dd> - - <dt>A full SIP implementation: arbitrary MIME messages are - allowed</dt> - <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags = - One_Attachment | Multiple_Attachments</dd> - </dl> - </tp:docstring> - </property> - - <property name="MessageTypes" type="au" - tp:type="Channel_Text_Message_Type[]" access="read" - tp:name-for-bindings="Message_Types" - tp:immutable="yes"> - <tp:added version="0.21.5"> - This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text" - >GetMessageTypes</tp:dbus-ref>; fall back to that method for - compatibility with older connection managers. - </tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of message types which may be sent on this channel.</p> - </tp:docstring> - </property> - - <property name="MessagePartSupportFlags" type="u" - tp:type="Message_Part_Support_Flags" access="read" - tp:name-for-bindings="Message_Part_Support_Flags" - tp:immutable="yes"> - <tp:docstring> - Flags indicating the level of support for message parts on this - channel. - </tp:docstring> - </property> - - <tp:flags name="Message_Part_Support_Flags" - value-prefix="Message_Part_Support_Flag" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Flags indicating the level of support for message parts on this - channel. They are designed such that setting more flags always - implies that the channel has more capabilities.</p> - - <p>If no flags are set, this indicates that messages may contain - a single message part whose content-type is any of the types - from SupportedContentTypes, possibly with some alternatives.</p> - - <p>There is no flag indicating support for alternatives. This is - because the SendMessage implementation can always accept messages - containing alternatives, even if the underlying protocol does not, - by deleting all alternatives except the first (most preferred) - that is supported.</p> - - <tp:rationale> - Each of the flags so far implies the previous flag, so we could - have used a simple enumeration here; however, we've defined - the message-part support indicator as a flag set for future - expansion. - </tp:rationale> - - <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some - examples.</p> - </tp:docstring> - - <tp:flag suffix="One_Attachment" value="1"> - <tp:docstring> - <tp:member-ref>SendMessage</tp:member-ref> will accept messages - containing a textual message body, - plus a single attachment of any type listed in the - SupportedContentTypes property. It does not make sense for this - flag to be set if Message_Part_Support_Flag_Data_Only is not also set - (because the connection manager can trivially provide an empty text - part if necessary). - </tp:docstring> - </tp:flag> - <tp:flag suffix="Multiple_Attachments" value="2"> - <tp:docstring> - SendMessage will accept messages containing a textual message body, - plus an arbitrary number of attachments of any type listed in the - SupportedContentTypes property. It does not make sense for this - flag to be set if Message_Part_Support_Flag_One_Attachment is not - also set. - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:mapping name="Message_Part" array-name="Message_Part_List" - array-depth="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Part of a message's content. In practice, this mapping never - appears in isolation: incoming messages are represented by a list of - <tp:type>Message_Part</tp:type> mappings in the - <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing - messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as - a list of these mappings.</p> - - <p>The first part of the message contains "headers", which refer - to the entire message. The second and subsequent parts contain the - message's content, including plain text, formatted text and/or - attached files. Well-known keys for the header and body parts are - defined by the <tp:type>Message_Header_Key</tp:type> and - <tp:type>Message_Body_Key</tp:type> types, respectively. It is an - error for a connection manager to put keys referring to the message - as a whole in the second or subsequent Message_Part, or keys intended - for body parts in the first Message_Part; clients MUST recover from - this error by ignoring these mis-placed keys.</p> - - <tp:rationale> - <p>Instead of representing messages as aa{sv} where the first - dictionary is special (a dictionary of headers), we could have - used a signature like (a{sv}aa{sv}) to separate out the headers - and the body parts.</p> - - <p>However, this would make access to the messages more awkward. - In Python, the syntax for access to a header field would remain - <code>message[0]['message-type']</code>, but access to a body - field in the second body part would change from - <code>message[2]['content'] to message[1][1]['content']</code>. In - GLib, the message would change from being a - <code>GPtrArray(GHashTable)</code> to being a - <code>GValueArray(GHashTable, GPtrArray(GHashTable))</code> which - is rather inconvenient to dereference.</p> - </tp:rationale> - - <p>In any group of parts with the same non-empty value for the - <tt>alternative</tt> key (which represent alternative versions of the - same content), more faithful versions of the intended message MUST - come before less faithful versions (note that this order is the - opposite of MIME <tt>multipart/alternative</tt> parts). Clients - SHOULD display the first alternative that they understand.</p> - - <tp:rationale> - <p>Specifying the preference order means that if the underlying - protocol doesn't support alternatives, the CM can safely delete - everything apart from the first supported alternative when - sending messages.</p> - - <p>The order is the reverse of MIME because MIME's rationale for - placing the "plainest" part first (legibility in pre-MIME UAs) - does not apply to us, and placing the most preferred part - first simplifies display (a client can iterate the message - in order, display the first alternative that it understands, - and skip displaying all subsequent parts with the same - "alternative" key).</p> - </tp:rationale> - - <p>Clients SHOULD present all parts that are not redundant - alternatives in the order they appear in this array, possibly - excluding parts that are referenced by another displayed part. - It is implementation-specific how the parts are presented to the - user.</p> - - <tp:rationale> - <p>This allows CMs to assume that all parts are actually shown to - the user, even if they are not explicitly referenced - we do - not yet recommend formatted text, and there is no way for - plain text to reference an attachment since it has no concept of - markup or references. This also forces clients to do something - sensible with messages that consist entirely of "attachments", - with no "body" at all.</p> - - <p>For instance, when displaying the above example, a client that - understands the HTML part should display the JPEG image once, - between the two lines "Here is a photo of my cat:" and - "Isn't it cute?"; it may additionally present the image in some - way for a second time, after "Isn't it cute?", or may choose - not to.</p> - - <p>A client that does not understand HTML, displaying the same - message, should display the plain-text part, followed by the JPEG - image.</p> - </tp:rationale> - - <p>Connection managers, clients and extensions to this specification - SHOULD NOT include <tp:type>Handle</tp:type>s as values in a - Message_Part, except for <code>message-sender</code> in the - header.</p> - - <tp:rationale> - <p>Reference-counting handles in clients becomes problematic if - the channel proxy cannot know whether particular map values - are handles or not.</p> - </tp:rationale> - - <h4>Example messages</h4> - - <p>A rich-text message, with an embedded image, might be represented - as:</p> - - <pre> -[ - { - 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c', - 'message-sender': 42, - 'message-sent': 1210067943, - 'message-received': 1210067947, - 'message-type': 0, # = Channel_Text_Message_Type_Normal - 'pending-message-id': 437, - }, - { 'alternative': 'main', - 'content-type': 'text/html', - 'content': 'Here is a photo of my cat:<br />' + - '<img src="cid:catphoto" alt="lol!" />' + - '<br />Isn't it cute?', - }, - { 'alternative': 'main', - 'content-type': 'text/plain', - 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?', - }, - { 'identifier': 'catphoto', - 'content-type': 'image/jpeg', - 'size': 101000, - 'needs-retrieval': True, - }, -]</pre> - - <p>telepathy-ring, Nokia's GSM connection manager, represents vCards - sent via SMS as:</p> - - <pre> -[ - { - 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c', - 'message-sender': 42, - 'message-sent': 1210067943, - 'message-received': 1210067947, - 'message-type': 0, # = Channel_Text_Message_Type_Normal - 'pending-message-id': 437, - }, - { 'content-type': 'text/x-vcard', - 'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes - }, -]</pre> - - <h3>Delivery reports</h3> - - <div> - <p>Delivery reports are also represented as messages with the - <tt>message-type</tt> header mapping to - <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report. - Delivery reports SHOULD contain the <tt>message-sender</tt> header, - mapping to the intended recipient of the original message, if - possible; other headers specific to delivery reports are defined by - the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second - and subsequent parts, if present, are a human-readable report from - the IM service.</p> - - <p>For backwards- and forwards-compatibility, whenever a delivery - error report is signalled—that is, with <tt>delivery-status</tt> - mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or - Permanently_Failed—<tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> - SHOULD also be emitted; whenever <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> - is emitted, a delivery report MUST also be signalled. - Delivery report messages on this interface MUST be represented in - emissions of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> - as messages with the Non_Text_Content - <tp:type>Channel_Text_Message_Flags</tp:type>; clients which - understand this interface SHOULD ignore the SendError signal in - favour of listening for delivery reports, as mentioned in the - introduction.</p> - - <p>The result of attempting to send delivery reports using - <tp:member-ref>SendMessage</tp:member-ref> is currently - undefined.</p> - - <h4>Example delivery reports</h4> - - <dl> - <dt>A minimal delivery report indicating permanent failure of the - sent message whose token was - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown - reason</dt> - <dd><pre> -[{ -# header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Permanently_Failed, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -} -# no body -]</pre></dd> - - <dt>A delivery report where the failed message is echoed back to the - sender rather than being referenced by ID, and the failure reason - is that this protocol cannot send messages to offline contacts - such as the contact with handle 123</dt> - <dd><pre> -[{ # header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Temporarily_Failed, -'delivery-error': Channel_Text_Send_Error_Offline, -'delivery-echo': - [{ # header of original message - 'message-sender': 1, - 'message-sent': 1210067943, - }, - { # body of original message - 'content-type': 'text/plain', - 'content': 'Hello, world!', - }] - ], - -# no body -]</pre></dd> - - <dt>A maximally complex delivery report: the server reports a - bilingual human-readable failure message because the user sent - a message "Hello, world!" with token - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact - with handle 123, but that handle represents a contact who does not - actually exist</dt> - <dd><pre> -[{ # header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Permanently_Failed, -'delivery-error': Channel_Text_Send_Error_Invalid_Contact, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -'delivery-echo': - [{ # header of original message - 'message-sender': 1, - 'message-sent': 1210067943, - }, - { # body of original message - 'content-type': 'text/plain', - 'content': 'Hello, world!', - }] - ], -}, -{ # message from server (alternative in English) -'alternative': '404', -'content-type': 'text/plain', -'lang': 'en', -'content': 'I have no contact with that name', -}, -{ # message from server (alternative in German) -'alternative': '404'. -'content-type': 'text/plain', -'lang': 'de', -'content', 'Ich habe keinen Kontakt mit diesem Namen', -} -]</pre></dd> - - <dt>A minimal delivery report indicating successful delivery - of the sent message whose token was - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt> - <dd><pre> -[{ -# header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Delivered, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -} -# no body -]</pre></dd> - - </dl> - - </div> - </tp:docstring> - - <tp:member name="Key" type="s"> - <tp:docstring> - A key, which SHOULD be one of the well-known keys specified by - <tp:type>Message_Header_Key</tp:type>, - <tp:type>Message_Body_Key</tp:type> or - <tp:type>Delivery_Report_Header_Key</tp:type> if possible. - </tp:docstring> - </tp:member> - - <tp:member name="Value" type="v"> - <tp:docstring> - The value corresponding to the given key, which SHOULD be one of the - specified types for well-known keys. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:simple-type type="s" name="Message_Header_Key"> - <tp:added version="0.19.8"/> - <tp:changed version="0.21.5"> - Removed <tt>protocol-token</tt>—which had never been implemented—and - respecified <tt>message-token</tt> not to have unimplementable - uniqueness guarantees. - </tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a - message, which contains metadata about the message as a whole, along - with the corresponding value types. Some keys make sense for both - incoming and outgoing messages, while others are only meaningful for - one or the other.</p> - - <dl> - <dt>message-token (s - - <tp:type>Protocol_Message_Token</tp:type>) - </dt> - <dd> - <p>An opaque identifier for the message, as used by the - underlying protocol. For outgoing messages, this SHOULD be - globally unique; for incoming messages, this is <em>not</em> - guaranteed to uniquely identify a message, <em>even within the - scope of a single channel or contact</em>; the only guarantee - made is that two messages with different <tt>message-token</tt> - headers are different messages.</p> - - <p>Clients wishing to determine whether a new message with the - <tt>scrollback</tt> header matches a previously-logged message - with the same <tt>message-token</tt> SHOULD compare the - message's sender, contents, <tt>message-sent</tt> or - <tt>message-received</tt> timestamp, etc. Note that, in XMPP, - the server only supplies a timestamp for scrollback messages, - not for messages received while you are in a room; thus, - non-scrollback messages will lack a <tt>message-sent</tt> - timestamp.</p> - - <tp:rationale> - <p>In practice, most protocols do not provide globally-unique - identifiers for messages. Connection managers, being - stateless, do not have the necessary information — namely, IM - logs — to generate reliable unique tokens for messages.</p> - - <p>For instance, some XMPP clients (including Gabble) stamp - messages they send with unique identifiers, but others number - outgoing messages in a conversation from 1 upwards.</p> - </tp:rationale> - </dd> - - <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> - <dd>The time the message was sent (if unavailable, the time - it arrived at a central server MAY be used). Omitted if no - reasonable approximation is available; SHOULD always be present - on outgoing messages.</dd> - - <dt>message-received (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> - <dd>The time the message was received locally. SHOULD always - be present.</dd> - - <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>)</dt> - <dd>The contact who sent the message. If 0 or omitted, the contact - who sent the message could not be determined.</dd> - - <dt>message-sender-id (s)</dt> - <dd>The identifier of the contact who sent the message, - i.e. the result of calling <tp:dbus-ref - namespace="ofdT.Connection">InspectHandles</tp:dbus-ref> - on <code>message-sender</code>. If omitted, clients MUST - fall back to looking at <code>message-sender</code>.</dd> - - <dt>sender-nickname (s)</dt> - <dd>The nickname chosen by the sender of the message, which can be - different for each message in a conversation.</dd> - - <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>) - </dt> - <dd>The type of message; if omitted, - Channel_Text_Message_Type_Normal MUST be assumed. MAY - be omitted for normal chat messages.</dd> - - <dt>supersedes (s – <tp:type>Protocol_Message_Token</tp:type>)</dt> - <dd>If present, this message supersedes a previous message, - identified by its <tt>protocol-token</tt> or - <tt>message-token</tt> header. The user interface MAY, for - example, choose to replace the superseded message with this - message, or grey out the superseded message. - - <tp:rationale>Skype, for example, allows the user to amend - messages they have already sent (to correct typos, - etc.).</tp:rationale> - </dd> - - <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt> - <dd>The incoming message ID. This MUST NOT be present on outgoing - messages. Clients SHOULD NOT store this key - it is only valid - for as long as the message remains unacknowledged.</dd> - - <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt> - <dd>This message is specific to the given interface, which is - neither Text nor Messages. It SHOULD be ignored if that - interface is not supported. (Note that an 'interface' key - can also appear on the second and subsequent parts, where - it indicates that that part (only) should be ignored if - unsupported.)</dd> - - <dt>scrollback (b)</dt> - <dd>If present and true, the incoming message was part of a - replay of message history (this matches the Scrollback flag in - <tp:type>Channel_Text_Message_Flags</tp:type>). This flag - does not make sense on outgoing messages and SHOULD NOT - appear there.</dd> - - <dt>rescued (b)</dt> - <dd>If present and true, the incoming message has been seen in - a previous channel during the lifetime of the Connection, - but had not been acknowledged when that channel closed, causing - an identical channel (in which the message now appears) to open. - This matches the Rescued flag in - <tp:type>Channel_Text_Message_Flags</tp:type>; it - does not make sense on outgoing messages, and SHOULD NOT - appear there.</dd> - </dl> - - </tp:docstring> - </tp:simple-type> - - <tp:simple-type type="s" name="Message_Body_Key"> - <tp:added version="0.19.8"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Well-known keys for the second and subsequent - <tp:type>Message_Part</tp:type>s of a message, which contain the - message content, along with the corresponding value types.</p> - - <dl> - <dt>identifier (s — - <tp:type>Protocol_Content_Identifier</tp:type>)</dt> - <dd>An opaque identifier for this part. - Parts of a message MAY reference other parts by treating - this identifier as if it were a MIME Content-ID and using - the cid: URI scheme.</dd> - - <dt>alternative (s)</dt> - <dd> - <p>If present, this part of the message is an alternative for - all other parts with the same value for "alternative". - Clients SHOULD only display one of them (this is expected to - be used for XHTML messages in a future version of this - specification).</p> - - <p>If omitted, this part is not an alternative for any other - part.</p> - - <p>Parts of a message MAY reference the group of alternatives - as a whole (i.e. a reference to whichever of them is chosen) - by treating this identifier as if it were the MIME Content-ID - of a multipart/alternative part, and using the cid: URI - scheme.</p> - </dd> - - <dt>content-type (s)</dt> - <dd> - <p>The MIME type of this part. See the documentation - for <tp:member-ref>MessageReceived</tp:member-ref> and - <tp:member-ref>MessageSent</tp:member-ref> for notes on the - special status of "text/plain" parts.</p> - - <p>Connection managers MUST NOT signal parts without a - 'content-type' key; if a protocol provides no way to determine - the MIME type, the connection manager is responsible for - guessing it, but MAY fall back to "text/plain" for text and - "application/octet-stream" for non-text.</p> - - <p>Clients MUST ignore parts without a 'content-type' key, which - are reserved for future expansion.</p> - - <p>When sending messages, clients SHOULD normalize the - content-type to lower case, but connection managers SHOULD NOT - rely on this. When signalling sent or received messages, - connection managers MUST normalize the content-type to lower - case.</p> - </dd> - - <dt>lang (s)</dt> - <dd>The natural language of this part, identified by a - RFC 3066 language tag. - - <tp:rationale> - XMPP allows alternative-selection by language as well as - by content-type. - </tp:rationale> - </dd> - - <dt>size (u)</dt> - <dd>The size in bytes (if needs-retrieval is true, this MAY be an - estimated or approximate size). SHOULD be omitted if 'content' - is provided. - - <tp:rationale> - There's no point in providing the size if you're already - providing all the content. - </tp:rationale> - </dd> - - <dt>thumbnail (b)</dt> - <dd> - <p>This part is a thumbnail. To represent an image together with - its thumbnail in a single message, there should be one part for - the full image followed by a part for the thumbnail (following - the “more complete versions first” requirement), with the same - 'alternative' value. For example:</p> - - <pre> -[ ... , - { 'alternative': 'catphoto', - 'content-type': 'image/jpeg', - 'size': 150000, - 'content': [0xFF, 0xD8, ... 0xFF 0xD9], - }, - { 'alternative': 'catphoto', - 'content-type': 'image/jpeg' - 'size': 1024, - 'thumbnail': True, - 'content': [0xFF, 0xD8, ... 0xFF 0xD9], - }, - ... -]</pre> - </dd> - - <dt>needs-retrieval (b)</dt> - <dd>If false or omitted, the connection - manager already holds this part in memory. If present and true, - this part must be retrieved on demand (like MIME's - <tt>message/external-body</tt>) by a mechanism to be defined later. - - <tp:rationale>The mechanism was meant to be - <tp:member-ref>GetPendingMessageContent</tp:member-ref>, but - that didn't work out. It's worth leaving the header in in - preparation for a future mechanism. - </tp:rationale> - </dd> - - <dt>truncated (b)</dt> - <dd>The content available via the 'content' key has been truncated - by the server or connection manager (equivalent to - Channel_Text_Message_Flag_Truncated in the Text interface). - </dd> - - <dt>content (s or ay)</dt> - <dd>The part's content, if it is available and - sufficiently small to include here (implies that - 'needs-retrieval' is false or omitted). Otherwise, omitted. - If the part is human-readable text or HTML, the value for this - key MUST be a UTF-8 string (D-Bus signature 's'). - If the part is not text, the value MUST be a byte-array - (D-Bus signature 'ay'). If the part is a text-based format - that is not the main body of the message (e.g. an iCalendar - or an attached XML document), the value SHOULD be a UTF-8 string, - transcoding from another charset to UTF-8 if necessary, but - MAY be a byte-array (of unspecified character set) if - transcoding fails or the source charset is not known.</dd> - - <!-- FIXME: "sufficiently small to include" is not currently - defined; we should add some API so clients can tell the - CM how large a message it should emit in the signal.--> - - <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt> - <dd>This part is specific to the given interface, which is - neither Text nor Messages. It SHOULD be ignored if that - interface is not supported. (Note that an 'interface' key - can also appear on the first part, where it indicates that the - entire message should be ignored if unsupported.)</dd> - </dl> - </tp:docstring> - </tp:simple-type> - - <tp:simple-type type="s" name="Delivery_Report_Header_Key"> - <tp:added version="0.19.8"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a - delivery report, along with the corresponding value types. Some of - these are special-cases of headers defined by - <tp:type>Message_Header_Key</tp:type>.</p> - - <dl> - <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>, as - defined by <tp:type>Message_Header_Key</tp:type>)</dt> - <dd>MUST be the intended recipient of the original message, if - available (zero or omitted if the intended recipient is - unavailable or is not a contact, e.g. a chatroom), even if the - delivery report actually came from an intermediate server.</dd> - - <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>, - as defined by <tp:type>Message_Header_Key</tp:type>)</dt> - <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd> - - <dt>delivery-status (u - <tp:type>Delivery_Status</tp:type>)</dt> - <dd>The status of the message. All delivery reports MUST contain - this key in the first Message_Part.</dd> - - <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt> - - <dd> - <p>An identifier for the message to which this delivery report - refers. MUST NOT be an empty string. Omitted if not - available.</p> - - <p>Clients may match this against the token produced by the - SendMessage method and MessageSent signal. A status report - with no token could match any sent message, and a sent - message with an empty token could match any status report. - If multiple sent messages match, clients SHOULD use some - reasonable heuristic.</p> - - <tp:rationale> - In an ideal world, we could unambiguously match reports - against messages; however, deployed protocols are not ideal, - and not all reports and messages can be matched. - </tp:rationale> - </dd> - - <dt>delivery-error (u - - <tp:type>Channel_Text_Send_Error</tp:type>)</dt> - <dd> - The reason for the failure. MUST be omitted if this was a - successful delivery; SHOULD be omitted if it would be - Channel_Text_Send_Error_Unknown. - </dd> - - <dt>delivery-dbus-error (s - - <tp:type>DBus_Error_Name</tp:type>)</dt> - <dd> - The reason for the failure, specified as a (possibly - implementation-specific) D-Bus error. MUST be omitted if this was - a successful delivery. If set, the 'delivery-error' key SHOULD be - set to the closest available value. - </dd> - - <dt>delivery-error-message (s)</dt> - <dd> - Debugging information on why the message could not be delivered. - MUST be omitted if this was a successful delivery; MAY always be - omitted. - </dd> - - <dt>delivery-echo (aa{sv} - <tp:type>Message_Part[]</tp:type>)</dt> - <dd> - <p>The message content, as defined by the Messages interface. - Omitted if no content is available. Content MAY have been - truncated, message parts MAY have been removed, and message - parts MAY have had their content removed (i.e. the message part - metadata is present, but the 'content' key is not).</p> - - <tp:rationale> - Some protocols, like XMPP, echo the failing message back to - the sender. This is sometimes the only way to match it - against the sent message, so we include it here. - </tp:rationale> - </dd> - - </dl> - </tp:docstring> - </tp:simple-type> - - <tp:simple-type type="u" name="Message_Part_Index" - array-name="Message_Part_Index_List"> - <tp:deprecated version="0.21.5"> - This type is only used by - <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is - unimplemented and deprecated. - </tp:deprecated> - <tp:added version="0.17.17"/> - <tp:docstring> - The index of a message part within a message. - </tp:docstring> - </tp:simple-type> - - <tp:mapping name="Message_Part_Content_Map"> - <tp:added version="0.17.17"/> - <tp:deprecated version="0.21.5"> - This structure is only used by - <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is - unimplemented and deprecated. - </tp:deprecated> - <tp:docstring> - A mapping from message part indexes to their content, as returned by - <tp:member-ref>GetPendingMessageContent</tp:member-ref>. - </tp:docstring> - - <tp:member type="u" tp:type="Message_Part_Index" name="Part"> - <tp:docstring> - Indexes into the array of <tp:type>Message_Part</tp:type>s that - represents a message. The "headers" part (which is not a valid - argument to GetPendingMessageContent) is considered to be part 0, - so the valid part numbers start at 1 (for the second message part). - </tp:docstring> - </tp:member> - - <tp:member type="v" name="Content"> - <tp:docstring> - The message part's content. The variant MUST contain either type - 's' or 'ay' (UTF-8 text string, or byte array), following the - same rules as for the value of the 'content' key in - the <tp:type>Message_Part</tp:type> mappings. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:simple-type type="s" name="Protocol_Message_Token" - array-name="Protocol_Message_Token_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An opaque token used to identify messages in the underlying. - protocol. As a special case, the empty string indicates that there - is no particular identification for a message.</p> - - <p>CM implementations SHOULD use an identifier expected to be unique, - such as a UUID, for outgoing messages (if possible).</p> - - <p>Some protocols can only track a limited number of messages - in a small message-ID space (SMS messages are identified by a single - byte), and some implementations send non-unique identifiers (some - XMPP clients use very simple message IDs, such as an incrementing - integer that resets to 1 at the beginning of each connection). As a - result, clients MUST NOT assume that protocol tokens will not be - re-used.</p> - - <p>In particular, clients SHOULD use a heuristic to assign delivery - reports to messages, such as matching on message content or - timestamp (if available), or assuming that the delivery report - refers to the most recent message with that ID.</p> - </tp:docstring> - </tp:simple-type> - - <tp:simple-type name="Protocol_Content_Identifier" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A protocol-specific identifier for a blob of content, as used for - the <tt>identifier</tt> key in a <tp:type>Message_Part</tp:type>. The - same identifier MAY be re-used if the same content, byte-for-byte, - appears as a part of several messages.</p> - - <tp:rationale> - <p>On XMPP, these identifiers might be Content-IDs for custom - smileys implemented using <a - href="http://xmpp.org/extensions/xep-0231.html">XEP-0232 Bits of - Binary</a>; the same smiley might well appear in multiple - messages.</p> - </tp:rationale> - </tp:docstring> - </tp:simple-type> - - <method name="SendMessage" tp:name-for-bindings="Send_Message"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Submit a message to the server for sending. - If this method returns successfully, the message has been submitted - to the server and the <tp:member-ref>MessageSent</tp:member-ref> - signal is emitted. A corresponding - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref> - signal on the Text interface MUST also be emitted.</p> - - <p>This method MUST return before the MessageSent signal is - emitted.</p> - - <tp:rationale> - <p>This means that the process sending the message is the first - to see the <tp:type>Protocol_Message_Token</tp:type>, and can - relate the message to the corresponding - <tp:member-ref>MessageSent</tp:member-ref> signal by comparing - message tokens (if supported by the protocol).</p> - </tp:rationale> - - <p>If this method fails, message submission to the server has failed - and no signal on this interface (or the Text interface) is - emitted.</p> - - <p>If this method succeeds, message submission to the server has - succeeded, but the message has not necessarily reached its intended - recipient. If a delivery failure is detected later, this is - signalled by receiving a message whose <code>message-type</code> - header maps to - <tp:type>Channel_Text_Message_Type</tp:type>_Delivery_Report. - Similarly, if delivery is detected to have been successful - (which is not possible in all protocols), a successful delivery - report will be signalled.</p> - </tp:docstring> - - <arg direction="in" type="aa{sv}" tp:type="Message_Part[]" - name="Message"> - <tp:docstring> - The message content, including any attachments or alternatives. - This MUST NOT include the following headers, or any others that - do not make sense for a client to specify: - <code>message-sender</code>, <code>message-sender-id</code>, - <code>message-sent</code>, <code>message-received</code>, - <code>pending-message-id</code>. - </tp:docstring> - </arg> - <arg direction="in" name="Flags" type="u" - tp:type="Message_Sending_Flags"> - <tp:docstring> - Flags affecting how the message is sent. The channel MAY ignore some - or all flags, depending on - <tp:member-ref>DeliveryReportingSupport</tp:member-ref>; the flags - that were handled by the CM are provided in - <tp:member-ref>MessageSent</tp:member-ref>. - </tp:docstring> - </arg> - - <arg direction="out" type="s" tp:type="Protocol_Message_Token" - name="Token"> - <tp:docstring> - An opaque token used to match any incoming delivery or failure - reports against this message, or an empty string if the message - is not readily identifiable. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The requested message is malformed and cannot be sent. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag" - type="u"> - <tp:docstring> - Flags altering the way a message is sent. The "most usual" action - should always be to have these flags unset. Some indication of which - flags are supported is provided by the - <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. - </tp:docstring> - - <tp:flag suffix="Report_Delivery" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Provide a successful delivery report if possible, even if this is - not the default for this protocol. Ignored if delivery reports are - not possible on this protocol.</p> - - <tp:rationale> - <p>In some protocols, like XMPP, it is not conventional to request - or send positive delivery notifications.</p> - </tp:rationale> - - <p>Delivery failure reports SHOULD always be sent, but if this flag - is present, the connection manager MAY also try harder to obtain - failed delivery reports or allow them to be matched to outgoing - messages.</p> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Report_Read" value="2"> - <tp:added version="0.19.9"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Provide a delivery report when the message is read by the - recipient, even if this is not the default for this protocol. - Ignored if read reports are not possible on this protocol.</p> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Report_Deleted" value="4"> - <tp:added version="0.19.9"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Provide a delivery report when the message is deleted by the - recipient, even if this is not the default for this protocol. - Ignored if such reports are not possible on this protocol.</p> - </tp:docstring> - </tp:flag> - </tp:flags> - - <signal name="MessageSent" tp:name-for-bindings="Message_Sent"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Signals that a message has been submitted for sending. This - MUST be emitted exactly once per emission of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref> - signal on the Text interface, for backwards-compatibility; clients - SHOULD ignore the latter if this interface is present, as mentioned - in the introduction.</p> - - <p>This SHOULD be emitted as soon as the CM determines it's - theoretically possible to send the message (e.g. the parameters are - supported and correct).</p> - - <tp:rationale> - <p>This signal allows a process that is not the caller of - SendMessage to log sent messages.</p> - </tp:rationale> - </tp:docstring> - - <arg type="aa{sv}" tp:type="Message_Part[]" name="Content"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The message content (see <tp:type>Message_Part</tp:type> for full - details). If the message that was passed to - <tp:member-ref>SendMessage</tp:member-ref> has a formatted text - part that the connection manager recognises, but no - <tt>text/plain</tt> alternative, the CM MUST use the formatted text - part to generate a <tt>text/plain</tt> alternative which is also - included in this signal argument.</p> - - <p>The connection manager SHOULD include the - <code>message-sender</code>, <code>message-sender-id</code> and - <code>message-sent</code> headers in the representation of the - message that is signalled here. If the channel has - channel-specific handles, the <code>message-sender</code> and - <code>message-sender-id</code> SHOULD reflect the sender that - other contacts will see.</p> - - <p>If the connection manager can predict that the message will be - altered during transmission, this argument SHOULD reflect what - other contacts will receive, rather than being a copy of the - argument to SendMessage (if the message is truncated, - formatting or alternatives are dropped, etc., then the edited - version SHOULD appear in this signal).</p> - </tp:docstring> - </arg> - - <arg name="Flags" type="u" tp:type="Message_Sending_Flags"> - <tp:docstring> - <p>Flags affecting how the message was sent. The flags might be a - subset of those passed to SendMessage if the caller requested - unsupported flags.</p> - </tp:docstring> - </arg> - - <arg name="Message_Token" type="s" tp:type="Protocol_Message_Token"> - <tp:docstring> - An opaque token used to match any incoming delivery or failure - reports against this message, or an empty string if the message - is not readily identifiable. - </tp:docstring> - </arg> - </signal> - - <property name="PendingMessages" type="aaa{sv}" access="read" - tp:type="Message_Part[][]" tp:name-for-bindings="Pending_Messages"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of incoming messages that have neither been acknowledged nor - rejected. This list is a more detailed version of the one returned - by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>, - and contains the same messages, uniquely identified by the same - pending message IDs. Its items can be removed using - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.</p> - - <p>Change notification is via - <tp:member-ref>MessageReceived</tp:member-ref> and - <tp:member-ref>PendingMessagesRemoved</tp:member-ref>.</p> - </tp:docstring> - </property> - - <signal name="PendingMessagesRemoved" - tp:name-for-bindings="Pending_Messages_Removed"> - <tp:docstring> - The messages with the given IDs have been removed from the - <tp:member-ref>PendingMessages</tp:member-ref> list. Clients SHOULD NOT - attempt to acknowledge those messages. - - <tp:rationale> - This completes change notification for the PendingMessages property - (previously, there was change notification when pending messages - were added, but not when they were removed). - </tp:rationale> - </tp:docstring> - - <arg name="Message_IDs" type="au" tp:type="Message_ID[]"> - <tp:docstring> - The messages that have been removed from the pending message list. - </tp:docstring> - </arg> - </signal> - - <method name="GetPendingMessageContent" - tp:name-for-bindings="Get_Pending_Message_Content"> - <tp:deprecated version='0.21.5' - xmlns="http://www.w3.org/1999/xhtml"> - This method has never been implemented, and in any case would have been - impossible to use correctly when multiple clients (such as a logger and - the handler) are interested in a text channel. See <a - href='https://bugs.freedesktop.org/show_bug.cgi?id=26417'>freedesktop.org - bug #26417</a> for more details. - </tp:deprecated> - <tp:docstring> - Retrieve the content of one or more parts of a pending message. - Note that this function may take a considerable amount of time - to return if the part's 'needs-retrieval' flag is true; consider - extending the default D-Bus method call timeout. Additional API is - likely to be added in future, to stream large message parts. - </tp:docstring> - - <arg name="Message_ID" type="u" tp:type="Message_ID" direction="in"> - <tp:docstring> - The ID of a pending message - </tp:docstring> - </arg> - - <arg name="Parts" type="au" direction="in" - tp:type="Message_Part_Index[]"> - <tp:docstring> - The desired entries in the array of message parts, identified by - their position. The "headers" part (which is not a valid argument - to this method) is considered to be part 0, so the valid part - numbers start at 1 (for the second Message_Part). - </tp:docstring> - </arg> - - <arg name="Content" type="a{uv}" direction="out" - tp:type="Message_Part_Content_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The content of the requested parts. The keys in this mapping - are positions in the array of message parts; the values are - either of type 's' or 'ay' (UTF-8 text string, or byte array), - following the same rules as for the value of the 'content' key in - the <tp:type>Message_Part</tp:type> mappings.</p> - - <p>If the one of the requested part numbers was greater than zero - but referred to a part that had no content (i.e. it had no - 'content-type' key or no 'content' key), it is simply omitted from - this mapping; this is not considered to be an error condition.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Either there is no pending message with the given message ID, - or one of the part numbers given was 0 or too large. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <signal name="MessageReceived" tp:name-for-bindings="Message_Received"> - <tp:docstring> - Signals that a message has been received and added to the pending - messages queue. This MUST be emitted exactly once per emission of the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> - signal on the Text interface, for backwards-compatibility; clients - SHOULD ignore the latter in favour of this signal if this interface is - present, as mentioned in the introduction. - </tp:docstring> - - <arg type="aa{sv}" tp:type="Message_Part[]" name="Message"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The message content, including any attachments or alternatives. If - the incoming message contains formatted text without a plain text - alternative, the connection manager MUST generate a - <tt>text/plain</tt> alternative from the formatted text, and - include it in this message (both here, and in the - <tp:member-ref>PendingMessages</tp:member-ref> property).</p> - </tp:docstring> - </arg> - </signal> - - <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" - plural="Delivery_Statuses" type="u"> - <tp:docstring> - <p>The status of a message as indicated by a delivery report.</p> - - <p>If this enum is extended in future specifications, this should - only be to add new, non-overlapping conditions (i.e. all failures - should still be signalled as either Temporarily_Failed - or Permanently_Failed). If additional detail is required (e.g. - distinguishing between the various types of permanent failure) this - will be done using additional - <tp:type>Delivery_Report_Header_Key</tp:type>s.</p> - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - The message's disposition is unknown. - Clients SHOULD consider all messages to have status - Delivery_Status_Unknown unless otherwise specified; connection - managers SHOULD NOT signal this delivery status explicitly. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Delivered" value="1"> - <tp:docstring> - The message has been delivered to the intended recipient. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Temporarily_Failed" value="2"> - <tp:docstring> - Delivery of the message has failed. Clients SHOULD notify the user, - but MAY automatically try sending another copy of the message. - - <tp:rationale> - Similar to errors with type="wait" in XMPP; analogous to - 4xx errors in SMTP. - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Permanently_Failed" value="3"> - <tp:docstring> - Delivery of the message has failed. Clients SHOULD NOT try again - unless by specific user action. If the user does not modify the - message or alter configuration before re-sending, this error is - likely to happen again. - - <tp:rationale> - Similar to errors with type="cancel", type="modify" - or type="auth" in XMPP; analogous to 5xx errors in SMTP. - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Accepted" value="4"> - <tp:docstring> - An intermediate server has accepted the message but the message - has not been yet delivered to the ultimate recipient. The - connection manager might send a Failed report or Delivered report - later. - - <tp:rationale> - Similar to "202 Accepted" success code in SIP; analogous to - 251 and 252 responses in SMTP. - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Read" value="5"> - <tp:added version="0.19.9"/> - <tp:docstring> - The message has been read by the intended recipient. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Deleted" value="6"> - <tp:added version="0.19.9"/> - <tp:docstring> - The message has been deleted by the intended recipient. This MAY be - signalled on its own if the message is deleted without being read, or - after <code>Read</code> if the message was read before being deleted. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:flags name="Delivery_Reporting_Support_Flags" - value-prefix="Delivery_Reporting_Support_Flag" type="u"> - <tp:docstring> - Flags indicating the level of support for delivery reporting on this - channel, as found on the - <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. Any - future flags added to this set will conform to the - convention that the presence of an extra flag implies that - more operations will succeed. Note that CMs may always provide more - reports than are requested in the - <tp:type>Message_Sending_Flags</tp:type> passed to - <tp:member-ref>SendMessage</tp:member-ref>. - - <tp:rationale> - If senders want delivery reports, they should ask for them. If they - don't want delivery reports, they can just ignore them, so there's no - need to have capability discovery for what will happen if a delivery - report isn't requested. - </tp:rationale> - </tp:docstring> - - <tp:flag suffix="Receive_Failures" value="1"> - <tp:docstring> - Clients MAY expect to receive negative delivery reports if - Message_Sending_Flag_Report_Delivery is specified when sending. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Receive_Successes" value="2"> - <tp:docstring> - Clients MAY expect to receive positive delivery reports if - Message_Sending_Flag_Report_Delivery is specified when sending. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Receive_Read" value="4"> - <tp:added version="0.19.9"/> - <tp:docstring> - Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> - <code>Read</code> reports if Message_Sending_Flag_Report_Read - is specified when sending. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Receive_Deleted" value="8"> - <tp:added version="0.19.9"/> - <tp:docstring> - Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> - <code>Deleted</code> reports if Message_Sending_Flag_Report_Deleted - is specified when sending. - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="DeliveryReportingSupport" access="read" - tp:type="Delivery_Reporting_Support_Flags" type="u" - tp:name-for-bindings="Delivery_Reporting_Support" - tp:immutable="yes"> - <tp:docstring> - A bitfield indicating features supported by this channel. - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Password.xml b/qt4/spec/Channel_Interface_Password.xml deleted file mode 100644 index 4e201ddf5..000000000 --- a/qt4/spec/Channel_Interface_Password.xml +++ /dev/null @@ -1,104 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> -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 -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. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Password"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:flags name="Channel_Password_Flags" value-prefix="Channel_Password_Flag" type="u"> - <tp:flag suffix="Provide" value="8"> - <tp:docstring> - The <tp:member-ref>ProvidePassword</tp:member-ref> method must be - called now for the user to join the channel - </tp:docstring> - </tp:flag> - </tp:flags> - <method name="GetPasswordFlags" tp:name-for-bindings="Get_Password_Flags"> - <arg direction="out" type="u" tp:type="Channel_Password_Flags" - name="Password_Flags"> - <tp:docstring> - An integer with the logical OR of all the flags set - (values of ChannelPasswordFlags) - </tp:docstring> - </arg> - <tp:docstring> - Returns the bitwise-OR of the flags relevant to the password on this - channel. The user interface can use this to present information about - which operations are currently valid. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - <signal name="PasswordFlagsChanged" - tp:name-for-bindings="Password_Flags_Changed"> - <arg name="Added" type="u" tp:type="Channel_Password_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been set - </tp:docstring> - </arg> - <arg name="Removed" type="u" tp:type="Channel_Password_Flags"> - <tp:docstring> - A bitwise OR of the flags which have been cleared - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the flags as returned by - <tp:member-ref>GetPasswordFlags</tp:member-ref> are changed. - The user interface should be updated as appropriate. - </tp:docstring> - </signal> - <method name="ProvidePassword" tp:name-for-bindings="Provide_Password"> - <arg direction="in" name="Password" type="s"> - <tp:docstring> - The password - </tp:docstring> - </arg> - <arg direction="out" type="b" name="Correct"> - <tp:docstring> - A boolean indicating whether or not the password was correct - </tp:docstring> - </arg> - <tp:docstring> - Provide the password so that the channel can be joined. Must be - called with the correct password in order for channel joining to - proceed if the 'provide' password flag is set. - </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.InvalidArgument"/> - </tp:possible-errors> - </method> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for channels that may have a password set that users need - to provide before being able to join, or may be able to view or change - once they have joined the channel.</p> - - <p>The <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the - associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref> - signal indicate whether the channel has a password, whether the user - must now provide it to join, and whether it can be viewed or changed - by the user.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Room.xml b/qt4/spec/Channel_Interface_Room.xml deleted file mode 100644 index ffdf4a96d..000000000 --- a/qt4/spec/Channel_Interface_Room.xml +++ /dev/null @@ -1,373 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Room" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2010 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.Channel.Interface.Room.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:added version="0.19.11">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Different IM protocols use a variety of ways to name chat rooms. The - simplest example is perhaps IRC, where chat rooms have short, - persistent, human-readable string names, and are generally global - across the network. Skype chat rooms have persistent string names, so - you can leave and re-join a room, but these names are opaque unique - identifiers. MSN chat rooms are unnamed, and you can only join one by - being invited. And XMPP wins the coveted “most complicated chat rooms” - prize: chat rooms may be hosted by different servers with different DNS - names; normally they have human-readable names, except that all MUCs on - Google Talk's conference server have UUIDs as names, and <a - href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym - title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4 - <q>Requesting a Unique Room Name</q></a> defines a protocol for - requesting a unique, opaque room name on the server.</p> - - <p>This interface intends to support and differentiate these mechanisms - more clearly than the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - properties can alone. It initially contains a pair of properties used - to represent the human-readable parts of a - <tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples - for different protocols are represented as follows:</p> - - <ul> - <li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a - channel with properties - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>Room</code>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - = <code>"#telepathy"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>, - <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating - that the room has a human-readable identifier, and is not confined to - a particular server on the network. - - <tp:rationale> - Actually, IRC supports creating “local” channels specific to the - server they are created on. These channels have identifiers - starting with <tt>&</tt> rather than <tt>#</tt>. These could be - represented by setting <tp:member-ref>Server</tp:member-ref> - appropriately. - </tp:rationale> - </li> - - <li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>Room</code>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - = <code>"0xdeadbeef"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, - <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating - that the room has an identifier but no human-readable name. - </li> - - <li>An MSN group chat has - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>None</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, - <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating - that the room has neither an identifier (so it cannot be re-joined - later) nor a human-readable name. - </li> - - <li>A standard Jabber multi-user chat - <tt>jdev@conference.jabber.org</tt> has - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>Room</code>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - = <code>"jdev@conference.jabber.org"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>, - <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>. - </li> - - <li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>Room</code>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, - <tp:member-ref>Server</tp:member-ref> = - <code>"groupchat.google.com"</code>, indicating that the room has a - persistent identifier, no human-readable name, and is hosted by a - particular server. - </li> - - <li>Similarly, a XEP-0045 §10.1.4 uniquely-named room - <tt>lrcgsnthzvwm@conference.jabber.org</tt> has - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = <code>Room</code>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - = <code>"lrcgsnthzvwm@conference.jabber.org"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, - <tp:member-ref>Server</tp:member-ref> = - <code>"conference.jabber.org"</code>, indicating that the room has a - persistent identifier, no human-readable name, and is hosted by a - particular server. - </li> - </ul> - - <h4>Requestable channel classes</h4> - - <p>If the connection supports joining text chat rooms by unique - identifier, like Skype, it should advertise a - <tp:type>Requestable_Channel_Class</tp:type> matching:</p> - - <blockquote> - <pre> -( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" - >Text</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref>: Room, - }, - Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetID</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandle</tp:dbus-ref>, - ] -)</pre></blockquote> - - <p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandle</tp:dbus-ref>.</p> - - <p>If, like IRC, the room identifiers are also human-readable, the - RCCs should also include RoomID in <var>Allowed_Properties</var>:</p> - - <blockquote> - <pre> -( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" - >Text</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref>: Room, - }, - Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetID</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandle</tp:dbus-ref>, - ...<tp:member-ref>RoomID</tp:member-ref> - ] -), - -( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" - >Text</tp:dbus-ref> - }, - Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>, - ] -)</pre></blockquote> - - <p>Requests may specify the RoomID in place of - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - . Note how <tp:member-ref>RoomID</tp:member-ref> appears - in <var>Allowed_Properties</var> of a different RCC because - when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref> is omitted (or is None), both - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandle</tp:dbus-ref> and - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetID</tp:dbus-ref> must also be omitted. - <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction - with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - in some situations, as explained below in the <em>Requesting room - channels</em> section. - </p> - - <p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref> - should also be included in the allowed properties, but - CMs MUST use a reasonable default - <tp:member-ref>Server</tp:member-ref> if not explicitly - specified in a channel request. The CM's default server MAY - be configurable by a connection parameter specified on a - <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" - >RequestConnection</tp:dbus-ref> call, similarly to how the - fallback conference server is specified on jabber connections in - gabble.</p> - - <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref> - should be fixed to the empty string, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - should be None:</p> - - <blockquote> - <pre> -( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" - >Text</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref>: None, - ...<tp:member-ref>RoomID</tp:member-ref>: "", - }, - Allowed = [ ] -)</pre></blockquote> - - <h4>Requesting room channels</h4> - - <p>When explicitly joining a room, the CM cannot know whether the room - ID is unique or not. As a result, if this is the case, adding an - empty string <tp:member-ref>RoomID</tp:member-ref> into the channel - request will ensure the CM knows. For example:</p> - - <blockquote> - <pre> -{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org", - ...<tp:member-ref>RoomID</tp:member-ref>: "" -}</pre></blockquote> - - <p>If <tp:member-ref>RoomID</tp:member-ref> features in - <var>Allowed_Properties</var> then the only value allowed in conjunction - with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - is the empty string. Requests with conflicting - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - and <tp:member-ref>RoomID</tp:member-ref> properties - will fail with InvalidArgument.</p> - - <p>To create a XEP-0045 §10.1.4 uniquely-named room channel - on the conference.jabber.org server, then the following channel - request should be made:</p> - - <blockquote> - <pre> -{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, - ...<tp:member-ref>RoomID</tp:member-ref>: "" - ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" -}</pre> - </blockquote> - - <p>If everything is successful, then when the channel request is - satisfied, a new channel will appear with the following properties:</p> - - <blockquote> - <pre> -{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, - ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org", - ...<tp:member-ref>RoomID</tp:member-ref>: "" - ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" -}</pre> - </blockquote> - - <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) - and then created a room with such a name on the said server. The empty - <tp:member-ref>RoomID</tp:member-ref> property shows that the room name - is not human-readable.</p> - - </tp:docstring> - - <property name="RoomID" tp:name-for-bindings="Room_ID" type="s" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The human-readable identifier of a chat room. Note that if - non-empty, this property (and perhaps also - <tp:member-ref>Server</tp:member-ref>) should be sufficient in - a channel request to join the room. XMPP MUCs have a room name - concept which is more like a topic, except more - persistent. This D-Bus property is <strong>not</strong> this - XMPP room name, but the bit before the @ in the room jid.</p> - - <p>This property cannot change during the lifetime of the channel. It - should appear in the <var>Allowed_Properties</var> of a - <tp:type>Requestable_Channel_Class</tp:type> for the connection if - rooms on this connection have human-readable names, and can be joined - by name.</p> - </tp:docstring> - </property> - - <property name="Server" tp:name-for-bindings="Server" type="s" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For protocols with a concept of chatrooms on multiple servers with - different DNS names (like XMPP), the DNS name of the server hosting - this channel (for example, <tt>"conference.jabber.org"</tt> or - <tt>"groupchat.google.com"</tt>). For other protocols, the empty - string.</p> - - <p>This property cannot change during the lifetime of the channel. It - should appear in the <var>Allowed_Properties</var> of a - <tp:type>Requestable_Channel_Class</tp:type> for the connection if - and only if non-empty values are supported.</p> - </tp:docstring> - </property> - - <tp:struct name="Room_Subject"> - <tp:docstring> - A struct representing the subject of a room channel. - </tp:docstring> - <tp:member type="s" name="Subject"> - <tp:docstring> - A human-readable description of the current subject of - conversation in the channel, similar to /topic in IRC. - </tp:docstring> - </tp:member> - <tp:member type="s" name="Actor"> - <tp:docstring> - A normalized contact ID representing who last modified the - subject, or the empty string if it is not known. - </tp:docstring> - </tp:member> - <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp"> - <tp:docstring> - A unix timestamp indicating when the subject was last modified. - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="Subject" tp:name-for-bindings="Subject" - type="(ssx)" tp:type="Room_Subject" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The subject on the room such as the topic in an IRC channel, - or the room name in XMPP MUCs. In protocols which do not support - subjects (like MSN), this property should be ("", "", 0).</p> - - <tp:rationale>This property replaces the subject, subject-contact, and - subject-timestamp Telepathy properties of Text channels, as Telepathy - properties are soon to be deprecated completely.</tp:rationale> - - <p>This property may change during the lifetime of the channel and - MUST not be included in a channel request.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_SASL_Authentication.xml b/qt4/spec/Channel_Interface_SASL_Authentication.xml deleted file mode 100644 index 7985a6bd5..000000000 --- a/qt4/spec/Channel_Interface_SASL_Authentication.xml +++ /dev/null @@ -1,723 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_SASL_Authentication" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication"> - <tp:added version="0.21.5">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel interface for SASL authentication, - as defined by - <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>. - When this interface appears on a <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channel, it represents authentication with the server. In future, - it could also be used to authenticate with secondary services, - or even to authenticate end-to-end connections with contacts. As a result, - this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type" - >ServerAuthentication</tp:dbus-ref> to allow for a potential future - Channel.Type.PeerAuthentication interface.</p> - - <p>In any protocol that requires a password, the connection manager can - use this channel to let a user interface carry out a simple SASL-like - handshake with it, as a way to get the user's credentials - interactively. This can be used to connect to protocols that may - require a password, without requiring that the password is saved in - the <tp:dbus-ref - namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> - - <p>In some protocols, such as XMPP, authentication with the server - is also carried out using SASL. In these protocols, a channel with this - interface can provide a simple 1:1 mapping of the SASL negotiations - taking place in the protocol, allowing more advanced clients to - perform authentication via SASL mechanisms not known to the - connection manager.</p> - - <tp:rationale> - <p>By providing SASL directly when the protocol supports it, we can - use mechanisms like Kerberos or Google's <code>X-GOOGLE-TOKEN</code> - without specific support in the connection manager.</p> - </tp:rationale> - - <p>For channels managed by a - <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>, - only the channel's <tp:dbus-ref - namespace="ofdT.Client">Handler</tp:dbus-ref> may call the - methods on this interface. Other clients MAY observe the - authentication process by watching its signals and properties.</p> - - <tp:rationale> - <p>There can only be one Handler, which is a good fit for SASL's - 1-1 conversation between a client and a server.</p> - </tp:rationale> - </tp:docstring> - - <tp:simple-type name="SASL_Mechanism" type="s" - array-name="SASL_Mechanism_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A SASL mechanism, as defined by - <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a> - and registered in - <a href="http://www.iana.org/assignments/sasl-mechanisms">the - IANA registry of SASL mechanisms</a>, or an unregistered - SASL mechanism such as <code>X-GOOGLE-TOKEN</code> used in the - same contexts.</p> - - <p>As a special case, pseudo-mechanisms starting with - <code>X-TELEPATHY-</code> are defined by this specification. - Use of these pseudo-mechanisms indicates that the user's credentials - are to be passed to the connection manager, which will then use - them for authentication with the service, either by implementing - the client side of some SASL mechanisms itself or by using a - non-SASL protocol. The only such pseudo-mechanism currently - defined is <code>X-TELEPATHY-PASSWORD</code>.</p> - - <p>The <code>X-TELEPATHY-PASSWORD</code> mechanism is extremely - simple:</p> - - <ul> - <li>The client MUST call - <tp:member-ref>StartMechanismWithData</tp:member-ref>, with - Initial_Data set to the password encoded in UTF-8. - For simplicity, calling <tp:member-ref>StartMechanism</tp:member-ref> - followed by calling <tp:member-ref>Respond</tp:member-ref> is not - allowed in this mechanism.</li> - - <li>The connection manager uses the password, together with - authentication details from the Connection parameters, to - authenticate itself to the server.</li> - - <li>When the connection manager finishes its attempt to authenticate - to the server, the channel's state changes to - either SASL_Status_Server_Succeeded or - SASL_Status_Server_Failed as appropriate.</li> - </ul> - </tp:docstring> - </tp:simple-type> - - <property name="AvailableMechanisms" - tp:name-for-bindings="Available_Mechanisms" - type="as" tp:type="SASL_Mechanism[]" - access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The SASL mechanisms as offered by the server, plus any - pseudo-SASL mechanisms supported by the connection manager for - credentials transfer. For instance, in a protocol that - natively uses SASL (like XMPP), this might be - <code>[ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", - "SCRAM-SHA-1" ]</code>.</p> - - <p>To make it possible to implement a very simple password-querying - user interface without knowledge of any particular SASL mechanism, - implementations of this interface MUST implement the - pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>, unless none - of the available mechanisms use a password at all.</p> - </tp:docstring> - </property> - - <property name="HasInitialData" tp:name-for-bindings="Has_Initial_Data" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, <tp:member-ref>StartMechanismWithData</tp:member-ref> - can be expected to work for SASL mechanisms not starting with - <code>X-TELEPATHY-</code> (this is the case in most, but not all, - protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref> - must be used instead.</p> - - <p>This property does not affect the <code>X-TELEPATHY-</code> - pseudo-mechanisms such as <code>X-TELEPATHY-PASSWORD</code>, - which can use - <tp:member-ref>StartMechanismWithData</tp:member-ref> regardless - of the value of this property.</p> - </tp:docstring> - </property> - - <property name="CanTryAgain" tp:name-for-bindings="Can_Try_Again" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, <tp:member-ref>StartMechanism</tp:member-ref> and (if - supported) <tp:member-ref>StartMechanismWithData</tp:member-ref> - can be expected to work when in one of the Failed states. If - false, the only thing you can do after failure is to close the - channel.</p> - - <tp:rationale> - <p>Retrying isn't required to work, although some protocols and - implementations allow it.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property type="u" tp:type="SASL_Status" access="read" - name="SASLStatus" tp:name-for-bindings="SASL_Status"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The current status of this channel. - Change notification is via the - <tp:member-ref>SASLStatusChanged</tp:member-ref> signal. - </tp:docstring> - </property> - - <property type="s" tp:type="DBus_Error_Name" access="read" - name="SASLError" tp:name-for-bindings="SASL_Error"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The reason for the <tp:member-ref>SASLStatus</tp:member-ref>, or - an empty string if the state is neither - Server_Failed nor Client_Failed.</p> - - <p>In particular, an ordinary authentication failure (as would - be produced for an incorrect password) SHOULD be represented by - <tp:error-ref>AuthenticationFailed</tp:error-ref>, - cancellation by the user's request SHOULD be represented - by <tp:error-ref>Cancelled</tp:error-ref>, and - cancellation by a local process due to inconsistent or invalid - challenges from the server SHOULD be represented by - <tp:error-ref>ServiceConfused</tp:error-ref>.</p> - - <p>If this interface appears on a <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channel, and connection to the server fails with an authentication - failure, this error code SHOULD be copied into the - <tp:dbus-ref - namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> - signal.</p> - </tp:docstring> - </property> - - <property name="SASLErrorDetails" - tp:name-for-bindings="SASL_Error_Details" - access="read" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tp:member-ref>SASLError</tp:member-ref> is non-empty, - any additional information about the last - disconnection; otherwise, the empty map. The keys and values are - the same as for the second argument of - <tp:dbus-ref - namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p> - - <p>If this interface appears on a <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channel, and connection to the server fails with an authentication - failure, these details SHOULD be copied into the - <tp:dbus-ref - namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> - signal.</p> - </tp:docstring> - </property> - - <property name="AuthorizationIdentity" - tp:name-for-bindings="Authorization_Identity" - type="s" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The identity for which authorization is being attempted, - typically the 'account' from the <tp:dbus-ref - namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref> - parameters, normalized and formatted according to the - conventions used for SASL in this protocol.</p> - - <tp:rationale> - <p>The normalization used for SASL might not be the same - normalization used elsewhere: for instance, in a protocol - with email-like identifiers such as XMPP or SIP, the user - "juliet@example.com" might have to authenticate to the - example.com server via SASL PLAIN as "juliet".</p> - </tp:rationale> - - <p>This is usually achieved by using the authorization identity for - authentication, but an advanced Handler could offer the option - to authenticate under a different identity.</p> - - <p>The terminology used here is that the authorization identity - is who you want to act as, and the authentication identity is - used to prove that you may do so. For instance, if Juliet is - authorized to access a role account, "sysadmin@example.com", - and act on its behalf, it might be possible to authenticate - as "juliet@example.com" with her own password, but request to - be authorized as "sysadmin@example.com" instead of her own - account. See - <a href="http://tools.ietf.org/html/rfc4422#section-3.4.1">RFC - 4422 §3.4.1</a> for more details.</p> - - <tp:rationale> - <p>In SASL the authorization identity is normally guessed from - the authentication identity, but the information available - to the connection manager is the identity for which - authorization is required, such as the desired JID in XMPP, - so that's what we signal to UIs; it's up to the UI to - choose whether to authenticate as the authorization identity - or some other identity.</p> - - <p>As a concrete example, the "sysadmin" XMPP account mentioned - above would have <code>{ 'account': 'sysadmin@example.com' }</code> - in its Parameters, and this property would also be - 'sysadmin@example.com'. A simple Handler would - merely prompt for sysadmin@example.com's password, - and use that JID as both the authorization and authentication - identity, which might result in SASL PLAIN authentication with the - initial response - '\000sysadmin@example.com\000root'.</p> - - <p>A more advanced Handler might also ask for an authentication - identity, defaulting to 'sysadmin@example.com'; if Juliet - provided authentication identity 'juliet@example.com' and - password 'romeo', the Handler might perform SASL PLAIN - authentication using the initial response - 'sysadmin@example.com\000juliet@example.com\000romeo'.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="DefaultUsername" - tp:name-for-bindings="Default_Username" - type="s" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The default username for use with SASL mechanisms that deal - with a "simple username" (as defined in <a - href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>). If - such a SASL mechanism is in use, clients SHOULD default to - using the DefaultUsername; also, if the client uses - the DefaultUsername, it SHOULD assume that the authorization - identity <tp:member-ref>AuthorizationIdentity</tp:member-ref> - will be derived from it by the server.</p> - - <tp:rationale> - <p>In XMPP, <a href="http://trac.tools.ietf.org/wg/xmpp/trac/ticket/49"> - servers typically expect</a> "user@example.com" to - authenticate with username "user"; this was a SHOULD in <a - href="http://tools.ietf.org/html/rfc3920">RFC 3920</a>.</p> - - <p><a - href="http://tools.ietf.org/html/draft-ietf-xmpp-3920bis-19">3920bis</a> - weakens that SHOULD to "in the absence of local information - provided by the server, an XMPP client SHOULD assume that - the authentication identity for such a SASL mechanism is the - combination of a user name and password, where the simple - user name is the localpart of the user's JID".</p> - </tp:rationale> - - <p>For example, in the simple case, if the user connects with - <tp:dbus-ref - namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ - account: "<tt>user@example.com</tt>" }) and use PLAIN with - password "password", he or she should authenticate like so: - "<tt>\0user\0password</tt>" and the channel will look like - this:</p> - -<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "user", - "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "user@example.com } -</pre></blockquote> - - <p>In the complex case, if the same user is using his or her - sysadmin powers to log in as the "announcements" role address, - he or she would connect with <tp:dbus-ref - namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ - account: "<tt>announcements@example.com</tt>" }) and the SASL - channel would look like this:</p> - -<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "announcements", - "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "announcements@example.com } -</pre></blockquote> - - <p>A sufficiently elaborate UI could give the opportunity - to override the username from "announcements" to "user". - The user's simple username is still "user", and the password is - still "password", but this time he or she is trying to authorize - to act as <tt>announcements@example.com</tt>, so the UI would - have to perform SASL PLAIN with this string: - "<tt>announcements@example.com\0user\0password</tt>", where - "announcements@example.com" is the - <tp:member-ref>AuthorizationIdentity</tp:member-ref>.</p> - </tp:docstring> - </property> - - <property name="DefaultRealm" tp:name-for-bindings="Default_Realm" - type="s" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The default realm (as defined in - <a href="http://tools.ietf.org/html/rfc2831#section-2.1.1">RFC - 2831</a>) to use for authentication, if the server does not - supply one.</p> - - <tp:rationale> - <p>The server is not required to provide a realm; if it doesn't, - the client is expected to ask the user or provide a sensible - default, typically the requested DNS name of the server. - In some implementations of <code>DIGEST-MD5</code>, the - server does not specify a realm, but expects that the client - will choose a particular default, and authentication will - fail if the client's default is different. Connection - managers for protocols where this occurs are more easily able - to work around these implementations than a generic client - would be.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="MaySaveResponse" tp:name-for-bindings="May_Save_Response" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Whether or not the client can save the authentication response and - re-use it to automate future authentication challenges.</p> - - <p>If this property is <code>False</code>, the client SHOULD NOT attempt - to cache the authentication response in its own keyring.</p> - - <p>If this property is not specified, it should be treated as if it were - <code>True</code>.</p> - - <tp:rationale>Some protocols or services may have terms and conditions - that prohibit caching a user's credentials.</tp:rationale> - - </tp:docstring> - </property> - - - <method name="StartMechanism" tp:name-for-bindings="Start_Mechanism"> - <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> - <tp:docstring> - The chosen mechanism. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Start an authentication try using <var>Mechanism</var>, without - sending initial data (an "initial response" as defined in RFC - 4422).</p> - - <tp:rationale> - <p>This method is appropriate for mechanisms where the client - cannot send anything until it receives a challenge from the - server, such as - <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> - in "initial authentication" mode.</p> - </tp:rationale> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The channel is not in a state where starting authentication makes - sense (i.e. SASL_Status_Not_Started, or (if - <tp:member-ref>CanTryAgain</tp:member-ref> is true) - SASL_Status_Server_Failed or - SASL_Status_Client_Failed). You should call - <tp:member-ref>AbortSASL</tp:member-ref> and wait for - SASL_Status_Client_Failed before starting another attempt. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The server or connection manager doesn't implement the given - SASL mechanism. Choose a SASL mechanism from - <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort - authentication if none of them are suitable. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="StartMechanismWithData" - tp:name-for-bindings="Start_Mechanism_With_Data"> - <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> - <tp:docstring> - The chosen mechanism. - </tp:docstring> - </arg> - <arg direction="in" name="Initial_Data" type="ay"> - <tp:docstring> - Initial data (an "initial response" in RFC 4422's terminology) to send - with the mechanism. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Start an authentication try using <var>Mechanism</var>, and send - <var>Initial_Data</var> as the "initial response" defined in - <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422 - §3.3</a>.</p> - - <tp:rationale> - <p>This method is appropriate for mechanisms where the client may - send data first, such as <code>PLAIN</code>, or must send data - first, such as - <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> - in "subsequent authentication" mode.</p> - - <p>Having two methods allows any mechanism where it makes a difference - to distinguish between the absence of an initial response - (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte - initial response (StartMechanismWithData, with Initial_Data - empty).</p> - </tp:rationale> - - <p>If the <tp:member-ref>HasInitialData</tp:member-ref> - property is false, this indicates that the underlying protocol - does not make it possible to send initial data. In such protocols, - this method may only be used for the <code>X-TELEPATHY-</code> - pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>), - and will fail if used with an ordinary SASL mechanism.</p> - - <tp:rationale> - <p>For instance, the IRC SASL extension implemented in Charybdis and - Atheme does not support initial data - the first message in the - exchange only carries the mechanism. This is significant if using - <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>, - which cannot be used in the faster "subsequent authentication" - mode on a protocol not supporting initial data.</p> - </tp:rationale> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The channel is not in a state where starting authentication makes - sense (i.e. SASL_Status_Not_Started, or (if - <tp:member-ref>CanTryAgain</tp:member-ref> is true) - SASL_Status_Server_Failed or - SASL_Status_Client_Failed). You should call - <tp:member-ref>AbortSASL</tp:member-ref> and wait for - SASL_Status_Client_Failed before starting another attempt. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The server or connection manager doesn't implement the given - SASL mechanism (choose one from - <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort - authentication if none of them are suitable), or doesn't allow - initial data to be sent (as indicated by - <tp:member-ref>HasInitialData</tp:member-ref>; call - <tp:member-ref>StartMechanism</tp:member-ref> instead). - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Respond" tp:name-for-bindings="Respond"> - <arg direction="in" name="Response_Data" type="ay"> - <tp:docstring> - The response data. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Send a response to the the last challenge received via - <tp:member-ref>NewChallenge</tp:member-ref>.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Either the state is not In_Progress, or no challenge has been - received yet, or you have already responded to the last challenge. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <method name="AcceptSASL" tp:name-for-bindings="Accept_SASL"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If the channel's status is SASL_Status_Server_Succeeded, - this method confirms successful authentication and advances - the status of the channel to SASL_Status_Succeeded.</p> - - <p>If the channel's status is SASL_Status_In_Progress, calling this - method indicates that the last - <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact - additional data sent after a successful SASL negotiation, and - declares that from the client's point of view, authentication - was successful. This advances the state of the channel to - SASL_Status_Client_Accepted.</p> - - <p>In mechanisms where the server authenticates itself to the client, - calling this method indicates that the client considers this to have - been successful. In the case of <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channels, this means that the connection manager MAY continue to - connect, and MAY advance the <tp:dbus-ref - namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Either the state is neither In_Progress nor Server_Succeeded, or no - challenge has been received yet, or you have already responded to - the last challenge. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <method name="AbortSASL" tp:name-for-bindings="Abort_SASL"> - <arg direction="in" name="Reason" type="u" tp:type="SASL_Abort_Reason"> - <tp:docstring> - Reason for abort. - </tp:docstring> - </arg> - <arg direction="in" name="Debug_Message" type="s"> - <tp:docstring> - Debug message for abort. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Abort the current authentication try.</p> - - <p>If the current status is SASL_Status_Server_Failed or - SASL_Status_Client_Failed, this method returns successfully, but has - no further effect. If the current status is SASL_Status_Succeeded - or SASL_Status_Client_Accepted then NotAvailable is raised. - Otherwise, it changes the channel's state to - SASL_Status_Client_Failed, with an appropriate error name and - reason code.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The current state is either Succeeded or Client_Accepted. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="SASLStatusChanged" tp:name-for-bindings="SASL_Status_Changed"> - <tp:docstring> - Emitted when the status of the channel changes. - </tp:docstring> - <arg type="u" tp:type="SASL_Status" name="Status"> - <tp:docstring> - The new value of <tp:member-ref>SASLStatus</tp:member-ref>. - </tp:docstring> - </arg> - <arg type="s" tp:type="DBus_Error_Name" name="Reason"> - <tp:docstring> - The new value of <tp:member-ref>SASLError</tp:member-ref>. - </tp:docstring> - </arg> - <arg type="a{sv}" tp:type="String_Variant_Map" name="Details"> - <tp:docstring> - The new value of <tp:member-ref>SASLErrorDetails</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <signal name="NewChallenge" tp:name-for-bindings="New_Challenge"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new challenge is received from the server, or when - a message indicating successful authentication and containing - additional data is received from the server.</p> - - <p>When the channel's handler is ready to proceed, it should respond - to the challenge by calling <tp:member-ref>Respond</tp:member-ref>, - or respond to the additional data by calling - <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call - <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p> - </tp:docstring> - <arg name="Challenge_Data" type="ay"> - <tp:docstring> - The challenge data or additional data from the server. - </tp:docstring> - </arg> - </signal> - - <tp:enum name="SASL_Abort_Reason" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A reason why SASL authentication was aborted by the client.</p> - </tp:docstring> - - <tp:enumvalue suffix="Invalid_Challenge" value="0"> - <tp:docstring> - The server sent an invalid challenge or data. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="User_Abort" value="1"> - <tp:docstring> - The user aborted the authentication. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="SASL_Status" type="u" plural="SASL_Statuses"> - <tp:enumvalue suffix="Not_Started" value="0"> - <tp:docstring> - The initial state. The Handler SHOULD either - call <tp:member-ref>AbortSASL</tp:member-ref>, or connect to the - <tp:member-ref>NewChallenge</tp:member-ref> signal then call - <tp:member-ref>StartMechanism</tp:member-ref> or - <tp:member-ref>StartMechanismWithData</tp:member-ref>. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="In_Progress" value="1"> - <tp:docstring> - The challenge/response exchange is in progress. The Handler SHOULD - call either <tp:member-ref>Respond</tp:member-ref> or - <tp:member-ref>AcceptSASL</tp:member-ref> exactly once per emission - of <tp:member-ref>NewChallenge</tp:member-ref>, or call - <tp:member-ref>AbortSASL</tp:member-ref> at any time. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Server_Succeeded" value="2"> - <tp:docstring> - The server has indicated successful authentication, and the - connection manager is waiting for confirmation from the Handler. - The Handler must call either <tp:member-ref>AcceptSASL</tp:member-ref> or - <tp:member-ref>AbortSASL</tp:member-ref> to indicate whether it - considers authentication to have been successful. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Client_Accepted" value="3"> - <tp:docstring> - The Handler has indicated successful authentication, and the - connection manager is waiting for confirmation from the server. - The state will progress to either Succeeded or Server_Failed when - confirmation is received. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Succeeded" value="4"> - <tp:docstring> - Everyone is happy (the server sent success, and the client has called - <tp:member-ref>AcceptSASL</tp:member-ref>). Connection to the server - will proceed as soon as this state is reached. The Handler SHOULD - call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - to close the channel. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Server_Failed" value="5"> - <tp:docstring> - The server has indicated an authentication failure. - If <tp:member-ref>CanTryAgain</tp:member-ref> is true, - the client may try to authenticate again, by calling - <tp:member-ref>StartMechanism</tp:member-ref> or - <tp:member-ref>StartMechanismWithData</tp:member-ref> again. - Otherwise, it should give up completely, by calling <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - on the channel. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Client_Failed" value="6"> - <tp:docstring> - The client has indicated an authentication failure. The - possible actions are the same as for Server_Failed. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_SMS.xml b/qt4/spec/Channel_Interface_SMS.xml deleted file mode 100644 index 4cfe3f2f8..000000000 --- a/qt4/spec/Channel_Interface_SMS.xml +++ /dev/null @@ -1,179 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_SMS" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> -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. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details. - -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. - </tp:license> - - <interface - name="org.freedesktop.Telepathy.Channel.Interface.SMS"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> - <tp:added version='0.19.12'>Imported from - rtcom-telepathy-glib, with the unused properties removed and the - documentation tidied up.</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains SMS-specific properties for text - channels.</p> - - <p>The presence of this interface on a channel does not imply that - messages will be delivered via SMS.</p> - - <p>This interface MAY appear in the - <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property - of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be - immutable and false. It SHOULD appear on channels where - <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and - also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is - mutable (i.e. channels that might fall back to sending SMS at any - time, such as on MSN).</p> - - <h4>Handler filters</h4> - - <p>A handler for class 0 SMSes should advertise the following filter:</p> - - <blockquote><code> -{ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: - ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/> - ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>: - <tp:type>Handle_Type</tp:type>_Contact,<br/> - ...<tp:dbus-ref namespace='ofdT.Channel.Interface'>SMS.Flash</tp:dbus-ref>: - True,<br/> -}</code></blockquote> - - <p>It should also set its <tp:dbus-ref - namespace='ofdT.Client.Handler'>BypassApproval</tp:dbus-ref> property - to <code>True</code>, so that it is invoked immediately for new - channels.</p> - </tp:docstring> - - <property name="Flash" tp:name-for-bindings="Flash" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <code>True</code>, then this channel is exclusively for - receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref - namespace='ofdT.Channel.Interface.Messages'>SendMessage</tp:dbus-ref> - on this channel). If <code>False</code>, no incoming class 0 SMSes - will appear on this channel.</p> - - <p>This property is immutable (cannot change), and therefore SHOULD - appear wherever immutable properties are reported, e.g. <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests" - >NewChannels</tp:dbus-ref> signals.</p> - - <tp:rationale> - <p>Class 0 SMSes should be displayed immediately to the user, and - need not be saved to the device memory unless the user explicitly - chooses to do so. This is unlike “normal”, class 1 SMSes, which - must be stored, but need not be shown immediately in their entirity - to the user.</p> - - <p>Separating class 0 SMSes into their own channel with this - immutable property allows them to be dispatched to a different - <tp:dbus-ref namespace='ofdT.Client'>Handler</tp:dbus-ref>—which - would include this property in its <tp:dbus-ref - namespace='ofdT.Client.Handler' - >HandlerChannelFilter</tp:dbus-ref>—avoiding the normal Text - channel handler having to decide for each message whether it should - be displayed to the user immediately or handled normally.</p> - - <p>Currently, no mechanism is defined for <em>sending</em> class 0 - SMSes. It seems reasonable to support specifying the class of an - outgoing SMS in its header <tp:type>Message_Part</tp:type>, rather - than requiring the UI to request a special channel for such SMSes; - hence, we define here that channels with Flash set to - <code>True</code> are read-only.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="SMSChannel" - tp:name-for-bindings="SMS_Channel" - type="b" - access="read" tp:requestable="yes" tp:immutable="sometimes"> - <tp:added version="0.21.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If TRUE, messages sent and received on this channel are transmitted - via SMS.</p> - - <p>If this property is included in the channel request, the - Connection Manager MUST return an appropriate channel (i.e. if TRUE - the channel must be for SMSes, if FALSE it must not), or else fail - to provide the requested channel with the - <tp:error-ref>NotCapable</tp:error-ref> - error.</p> - - <p>For example, to explicitly request an SMS channel to a contact. - You might construct a channel request like:</p> - - <blockquote><pre>{ - Channel.Type: Channel.Type.Text, - Channel.TargetHandleType: Handle_Type_Contact, - Channel.TargetID: escher.cat, - Channel.Interface.SMS.SMSChannel: True, -}</pre></blockquote> - - <tp:rationale> - Some protocols allow us to send SMSes to a remote contact, without - knowing the phone number to which those SMSes will be sent. This - provides a mechanism to request such channels. - </tp:rationale> - - <p>If this property is not included in the channel request, the - Connection Manager MAY return an SMS channel if that is the most - appropriate medium (i.e. if the channel target is a phone - number).</p> - - <tp:rationale> - To some types of identifiers (i.e. phone numbers) it only makes - sense to return an SMS channel, this is what happens currently with - telepathy-ring. We don't want to break this behaviour when we are - not explicit about the type of channel we want. Alternatively, for - protocols where there is an SMS fallback for IM messages, it's - possible that we don't care what sort of channel we get, and simply - want notification of the transport. - </tp:rationale> - - <p>Some protocols have a fallback to deliver IM messages via SMS. - On these protocols, the Connection Manager SHOULD set the property - value as appropriate, and notify its change with - <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p> - - <tp:rationale> - Protocols such as MSN can fall back to delivering IM messages via - SMS. Where possible we want clients to be able to inform the user - that their messages are going to be redirected to the remote - contact's phone. - </tp:rationale> - </tp:docstring> - </property> - - <signal name="SMSChannelChanged" - tp:name-for-bindings="SMS_Channel_Changed"> - <tp:added version="0.21.7"/> - <arg name="SMSChannel" type="b"> - <tp:docstring> - The new value for <tp:member-ref>SMSChannel</tp:member-ref>. - </tp:docstring> - </arg> - <tp:docstring> - This signal indicates a change in the - <tp:member-ref>SMSChannel</tp:member-ref> property. - </tp:docstring> - </signal> - </interface> -</node> diff --git a/qt4/spec/Channel_Interface_Securable.xml b/qt4/spec/Channel_Interface_Securable.xml deleted file mode 100644 index d9d971394..000000000 --- a/qt4/spec/Channel_Interface_Securable.xml +++ /dev/null @@ -1,78 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Securable" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright> - - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, - USA.</p> - </tp:license> - - <interface name="org.freedesktop.Telepathy.Channel.Interface.Securable"> - <tp:added version="0.21.5">as stable API</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface exists to expose security information about - <tp:dbus-ref namespace="ofdT">Channel</tp:dbus-ref>s. The two - properties are sometimes immutable and can be used to make - decisions on how cautious to be about transferring sensitive - data. The special case of <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channels is one example of where the two properties are - immutable.</p> - - <p>For example, clients MAY use these properties to decide - whether the <code>PLAIN</code> mechanism is acceptable for a - <tp:dbus-ref - namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref> - channel.</p> - </tp:docstring> - - <property name="Encrypted" - tp:name-for-bindings="Encrypted" type="b" - access="read" tp:immutable="sometimes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if this channel occurs over an encrypted - connection. This <strong>does not</strong> imply that steps - have been taken to avoid man-in-the-middle attacks.</p> - - <tp:rationale> - <p>For future support for <a - href="http://tools.ietf.org/html/rfc5056">RFC 5056 Channel - Binding</a> it is desirable to be able to use some SASL - mechanisms over an encrypted connection to an unverified peer, - which can prove that it is the desired destination during - the SASL negotiation.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="Verified" - tp:name-for-bindings="Verified" type="b" - access="read" tp:immutable="sometimes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if this channel occurs over a connection that is - protected against tampering, and has been verified to be with - the desired destination: for instance, one where TLS was - previously negotiated, and the TLS certificate has been - verified against a configured certificate authority or - accepted by the user.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Service_Point.xml b/qt4/spec/Channel_Interface_Service_Point.xml deleted file mode 100644 index 787397b20..000000000 --- a/qt4/spec/Channel_Interface_Service_Point.xml +++ /dev/null @@ -1,86 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint"> - <tp:added version="0.19.7">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for channels - that can indicate when/if they are connected to some form - of service point. For example, when - dialing 9-1-1 in the US, a GSM modem/network will recognize that as - an emergency call, and inform higher levels of the stack that the - call is being handled by an emergency service. In this example, - the call is handled by a Public Safety Answering Point (PSAP) which is labeled - as "urn:service:sos". Other networks and protocols may handle this - differently while still using this interface.</p> - - <p>Note that while the majority of examples given in this - documentation are for GSM calls, they could just as easily be - SIP calls, GSM SMS's, etc.</p> - </tp:docstring> - - <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point" - type="(us)" tp:type="Service_Point" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This property is used to indicate that the channel target is a - well-known service point. Please note that the CM (or lower layers - of the stack or network) may forward the connection to other other - service points, which the CM SHOULD indicate via - <tp:member-ref>ServicePointChanged</tp:member-ref> - signal.</p> - - <p>This property SHOULD be set for channel requests that are - specifically targeting service points.</p> - </tp:docstring> - </property> - - <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point" - type="(us)" tp:type="Service_Point" access="read"> - <tp:docstring> - The service point that the channel is connected to. If the channel is - not connected to a service point, the CM MUST set the - <tp:type>Service_Point_Type</tp:type> field to None; for instance, - this will be the case for ordinary calls. - </tp:docstring> - </property> - - <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed"> - <tp:docstring> - <p>Emitted when a channel changes the service point that it's connected to. This - might be a new call being connected to a service, a call connected to - a service being routed to a different service - (ie, an emergency call being routed from a generic emergency PSAP to - a poison control PSAP), or any number of other things.</p> - - <p>Note that this should be emitted as soon as the CM has been notified - of the switch, and has updated its internal state. The CM MAY still - be in the process of connecting to the new service point.</p> - </tp:docstring> - - <arg name="Service_Point" type="(us)" tp:type="Service_Point"> - <tp:docstring> - The new service point that is being used. - </tp:docstring> - </arg> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Splittable.xml b/qt4/spec/Channel_Interface_Splittable.xml deleted file mode 100644 index 760c13406..000000000 --- a/qt4/spec/Channel_Interface_Splittable.xml +++ /dev/null @@ -1,71 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Splittable" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Channel.Interface.Splittable.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for channels that can be made conceptually part of a - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" - >Conference</tp:dbus-ref>, and can then be detached from that - conference.</p> - - <tp:rationale> - <p>This interface addresses part of freedesktop.org <a - href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug - #24906</a> (GSM-compatible conference calls). GSM is currently - the only protocol known to implement this; PBXs might implement - it too.</p> - </tp:rationale> - </tp:docstring> - - <method name="Split" - tp:name-for-bindings="Split"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that this channel is removed from any - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" - >Conference</tp:dbus-ref> of which it is a part.</p> - - <p>This implies that the media streams within the conference are put on - hold and the media streams within the member channel leaving the - conference are unheld.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - This channel isn't in a conference. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This channel is in a conference but can't currently be split away - from it. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> diff --git a/qt4/spec/Channel_Interface_Transfer.xml b/qt4/spec/Channel_Interface_Transfer.xml deleted file mode 100644 index 02591c1d1..000000000 --- a/qt4/spec/Channel_Interface_Transfer.xml +++ /dev/null @@ -1,53 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Transfer" - tp:causes-havoc='not well-tested'> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <method name="Transfer"> - <arg direction="in" name="Member" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the member to transfer - </tp:docstring> - </arg> - <arg direction="in" name="Destination" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the destination contact - </tp:docstring> - </arg> - <tp:docstring> - Request that the given channel member instead connects to a different - contact ID. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - <tp:docstring> - An interface for channels where you may request that one of the members - connects to somewhere else instead. - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Tube.xml b/qt4/spec/Channel_Interface_Tube.xml deleted file mode 100644 index 858a15dd9..000000000 --- a/qt4/spec/Channel_Interface_Tube.xml +++ /dev/null @@ -1,258 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A <i>tube</i> is a mechanism for arbitrary data transfer between - two or more IM users, used to allow applications on the users' - 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 - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Type.StreamTube</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 - tubes, you have to create several tube channels.</p> - - <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type> - Contact (for 1-1 communication) or 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</tp:dbus-ref> and/or - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>) - even if no client has indicated via - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> - that such a tube is supported. They SHOULD also allow clients to offer tubes with any - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref> - to any contact which supports the corresponding tube capability.</p> - - <tp:rationale> - <p>This lowers the barrier to entry for those writing new tube - applications, and preserves interoperability with older versions of - the Telepathy stack which did not support rich capabilities.</p> - </tp:rationale> - </tp:docstring> - - <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" - 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 - negotiate parameters in-band. The allowable keys, - types and values are defined by the service, but connection managers - must support the value being a string (D-Bus type <tt>'s'</tt>), - array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus - type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean - (D-Bus type <tt>'b'</tt>).</p> - - <p>When the tube is offered, the parameters are transmitted with the - offer and appear as a property of the incoming tube for other - participants.</p> - - <p>For example, a stream tube for <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> - <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might - use the following properties, as defined in <a - href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782) - Service Types</a>:</p> - - <pre> -{ 'u': 'some-username', - 'p': 'top-secret-password', - 'path': '/etc/passwd', -}</pre> - - <p>When requesting a tube with - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request; instead, it is set - when <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref> - (as appropriate) is called. Its value is undefined until the tube is - offered; once set, its value 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> - - <property name="State" type="u" tp:type="Tube_Channel_State" access="read" - tp:name-for-bindings="State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>State of the tube in this channel.</p> - - <p>When requesting a tube with - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request.</p> - </tp:docstring> - </property> - - <tp:enum name="Tube_Channel_State" type="u"> - <tp:enumvalue suffix="Local_Pending" value="0"> - <tp:docstring> - The initiator offered the tube. The tube is waiting to be - accepted/closed locally. If the client accepts the tube, the tube's - state will be Open. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Pending" value="1"> - <tp:docstring> - The tube is waiting to be accepted/closed remotely. If the - recipient accepts the tube, the tube's state will be Open. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="2"> - <tp:docstring> - The initiator offered the tube and the recipient accepted it. The - tube is open for traffic. The tube's state stays in this state until - it is closed. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Not_Offered" value="3"> - <tp:docstring> - The tube channel has been requested but the tube is not yet offered. - The client should offer the tube to the recipient and the tube's - state will be Remote_Pending. The method used to offer the tube - depends on the tube type. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="TubeChannelStateChanged" - tp:name-for-bindings="Tube_Channel_State_Changed"> - <tp:docstring> - Emitted when the state of the tube channel changes. Valid state - transitions are documented with <tp:type>Tube_Channel_State</tp:type>. - </tp:docstring> - <arg name="State" type="u" tp:type="Tube_Channel_State"> - <tp:docstring> - The new state of the tube. - </tp:docstring> - </arg> - </signal> - - <tp:enum name="Socket_Address_Type" type="u"> - <tp:enumvalue suffix="Unix" value="0"> - <tp:docstring> - A Unix socket. The address variant contains a byte-array, signature 'ay', - containing the path of the socket. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Abstract_Unix" value="1"> - <tp:docstring> - An abstract Unix socket. The address variant contains a byte-array, - signature 'ay', containing the path of the socket including the - leading null byte. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="IPv4" value="2"> - <tp:docstring> - An IPv4 socket. The address variant contains a Socket_Address_IPv4, - i.e. a structure with signature (sq) - in which the string is an IPv4 dotted-quad address literal - (and must not be a DNS name), while the 16-bit unsigned integer is - the port number. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="IPv6" value="3"> - <tp:docstring> - An IPv6 socket. The address variant contains a Socket_Address_IPv6, - i.e. a structure with signature (sq) - in which the string is an IPv6 address literal as specified in - RFC2373 (and must not be a DNS name), while the 16-bit unsigned - integer is the port number. - </tp:docstring> - </tp:enumvalue> - - </tp:enum> - - <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. - a Unix socket that accepts all local connections, or an IP socket - listening on 127.0.0.1 (or ::1) or rejecting connections not from - that address). The associated variant must be ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Port" value="1"> - <tp:docstring> - May only be used on IP sockets. The associated variant must contain - a struct Socket_Address_IPv4 (or Socket_Address_IPv6) - containing the string form of an IP address of the appropriate - version, and a port number. The socket can only be accessed if the - connecting process has that address and port number; all other - connections will be rejected. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Netmask" value="2"> - <tp:deprecated version="0.17.25">This has never been implemented. - If you want to share a service to your whole LAN, Telepathy is - not the way to do it.</tp:deprecated> - <tp:docstring> - May only be used on IP sockets. The associated variant must contain - a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with - signature (sy), containing the string form of an - IP address of the appropriate version, and a prefix length "n". - The socket can only be accessed if the first n bits of the - connecting address match the first n bits of the given address. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Credentials" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>May only be used on UNIX sockets. - The connecting process must send a byte when - it first connects, which is not considered to be part of the data - stream. If the operating system uses sendmsg() with SCM_CREDS or - SCM_CREDENTIALS to pass credentials over sockets, the connecting - process must do so if possible; if not, it must still send the - byte.</p> - - <p>The listening process will disconnect the connection unless it - can determine by OS-specific means that the connecting process - has the same user ID as the listening process.</p> - - <p>The associated variant must be ignored.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Request.xml b/qt4/spec/Channel_Request.xml deleted file mode 100644 index fbb67925e..000000000 --- a/qt4/spec/Channel_Request.xml +++ /dev/null @@ -1,303 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Request" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2008–2011 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.ChannelRequest"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel request is an object in the <tp:dbus-ref - namespace='ofdT'>ChannelDispatcher</tp:dbus-ref> representing - an ongoing request for some channels to be created or found. They are - created by methods such as <tp:dbus-ref - namespace='ofdT.ChannelDispatcher'>CreateChannel</tp:dbus-ref>. There - can be any number of ChannelRequest objects at the same time.</p> - - <p>Its well-known bus name is the same as that of the ChannelDispatcher, - <code>"org.freedesktop.Telepathy.ChannelDispatcher"</code>.</p> - - <tp:rationale> - <p>See - <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" - type="o" access="read"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - on which this request was made. This property cannot change. - </tp:docstring> - </property> - - <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" - type="x" tp:type="User_Action_Timestamp" access="read"> - <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.</p> - - <p>This property is set when the channel request is created, - and can never change.</p> - </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"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of dictionaries containing desirable properties for - the channel or channels to be created.</p> - - <tp:rationale> - <p>This is an array so that we could add a CreateChannels method in - future without redefining the API of ChannelRequest.</p> - </tp:rationale> - - <p>This property is set when the channel request is created, - and can never change.</p> - </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> - - <tp:rationale> - <p>The client that created this object calls this method - when it has connected signal handlers for - <tp:member-ref>Succeeded</tp:member-ref> and - <tp:member-ref>Failed</tp:member-ref>.</p> - </tp:rationale> - - <p>Clients other than the client which created the ChannelRequest - MUST NOT call this method.</p> - - <p>This method SHOULD return immediately; on success, the request - might still fail, but this will be indicated asynchronously - by the <tp:member-ref>Failed</tp:member-ref> signal.</p> - - <p>Proceed cannot fail, unless clients have got the life-cycle - of a ChannelRequest seriously wrong (e.g. a client calls this - method twice, or a client that did not create the ChannelRequest - calls this method). If it fails, clients SHOULD assume that the - whole ChannelRequest has become useless.</p> - </tp:docstring> - - <tp:possible-errors> - <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. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Cancel" tp:name-for-bindings="Cancel"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Cancel the channel request. The precise effect depends on the - current progress of the request.</p> - - <p>If the connection manager has not already been asked to create - a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted - immediately, and the channel request is removed.</p> - - <p>If the connection manager has already been asked to create a - channel but has not produced one yet (e.g. if <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - has been called, but has not yet returned), then the - ChannelDispatcher will remember that the request has been cancelled. - When the channel appears, it will be closed (if it was newly - created and can be closed), and will not be dispatched to a - handler.</p> - - <p>If the connection manager has already returned a channel, but the - channel has not yet been dispatched to a handler - then the channel dispatcher will not dispatch that - channel to a handler. If the channel was newly created for this - request, the channel dispatcher will close it with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>; - otherwise, the channel dispatcher will ignore it. In either case, - <tp:member-ref>Failed</tp:member-ref> will be emitted when processing - has been completed.</p> - - <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to - this method, the error SHOULD be - <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 - no longer exist.</p> - </tp:docstring> - </method> - - <signal name="Failed" tp:name-for-bindings="Failed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel request has failed. It is no longer present, - and further methods must not be called on it.</p> - </tp:docstring> - - <arg name="Error" type="s" tp:type="DBus_Error_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of a D-Bus error. This can come from various sources, - including the error raised by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, - or an error generated - to represent failure to establish the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.</p> - </tp:docstring> - </arg> - - <arg name="Message" type="s"> - <tp:docstring> - If the first argument of the D-Bus error message was a string, - that string. Otherwise, an empty string. - </tp:docstring> - </arg> - </signal> - - <signal name="Succeeded" tp:name-for-bindings="Succeeded"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel request has succeeded. It is no longer present, - and further methods must not be called on it.</p> - </tp:docstring> - </signal> - - <property name="Hints" tp:name-for-bindings="Hints" - type="a{sv}" access="read"> - <tp:added version="0.21.5"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary of metadata provided by the channel - requester, which the handler and other clients MAY choose to - interpret. Currently no standard keys are defined; clients MAY - choose to use platform-specific keys for their own purposes, but MUST - ignore unknown keys and MUST cope with expected keys being - missing. Clients SHOULD namespace hint names by having them - start with a reversed domain name, in the same way as D-Bus - interface names.</p> - - <tp:rationale>This property might be used to pass a contact ID for a - telephone number shared between two contacts from the address book to - the call UI, so that if you try to call “Mum”, the call UI knows this - rather than having to guess or show “Calling Mum or Dad”. The format - of these contact IDs would be platform-specific, so we leave the - definition of the dictionary entry up to the platform in question. - But third-party channel requesters might not include the contact ID, - so the call UI has to be able to deal with it not being - there.</tp:rationale> - - <p>The channel dispatcher does not currently interpret any of these - hints: they are solely for communication between cooperating - clients. If hints that do affect the channel dispatcher are added in - future, their names will start with an appropriate reversed domain - name (e.g. <code>org.freedesktop.Telepathy</code> for hints defined - by this specification, or an appropriate vendor name for third-party - plugins).</p> - - <p>This property may be set when the channel request is created, and - can never change. Since it is immutable, it SHOULD be included in the - dictionary of properties passed to <tp:dbus-ref - namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref> - by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p> - </tp:docstring> - </property> - - <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel"> - <tp:added version="0.21.5"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Variant of the <tp:dbus-ref - namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal - allowing to get the channel which has been created.</p> - - <p>This signal MUST be emitted if the - <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>'s - <tp:dbus-ref - namespace="ofdT.ChannelDispatcher">SupportsRequestHints</tp:dbus-ref> - property is true. If supported, it MUST be emitted before - the <tp:member-ref>Succeeded</tp:member-ref> signal.</p> - </tp:docstring> - - <arg name="Connection" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The Connection owning the channel.</p> - </tp:docstring> - </arg> - - <arg name="Connection_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A subset of the Connection's properties, currently unused. - This parameter may be used in future.</p> - </tp:docstring> - </arg> - - <arg name="Channel" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel which has been created.</p> - </tp:docstring> - </arg> - - <arg name="Channel_Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same immutable properties of the Channel that would appear - in a <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests" - >NewChannels</tp:dbus-ref> signal.</p> - </tp:docstring> - </arg> - - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Request_Future.xml b/qt4/spec/Channel_Request_Future.xml deleted file mode 100644 index d75c7e0ce..000000000 --- a/qt4/spec/Channel_Request_Future.xml +++ /dev/null @@ -1,98 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Request_Future" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2010 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.ChannelRequest.FUTURE" - tp:causes-havoc="a staging area for future Channel functionality"> - - <tp:requires interface="org.freedesktop.Telepathy.ChannelRequest"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains functionality which we intend to incorporate - into the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - interface in future. It should be considered to - be conceptually part of the core ChannelRequest interface, but without - API or ABI guarantees.</p> - </tp:docstring> - - <property name="Hints" tp:name-for-bindings="Hints" - type="a{sv}" access="read"> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary of metadata provided by the channel - requester, which the handler and other clients MAY choose to - interpret. Currently no standard keys are defined; clients MAY - choose to use platform-specific keys for their own purposes, but MUST - ignore unknown keys and MUST cope with expected keys being - missing.</p> - - <tp:rationale>This property might be used to pass a contact ID for a - telephone number shared between two contacts from the address book to - the call UI, so that if you try to call “Mum”, the call UI knows this - rather than having to guess or show “Calling Mum or Dad”. The format - of these contact IDs would be platform-specific, so we leave the - definition of the dictionary entry up to the platform in question. - But third-party channel requesters might not include the contact ID, - so the call UI has to be able to deal with it not being - there.</tp:rationale> - - <p>The channel dispatcher will not interpret these hints: they are - solely for communication between cooperating clients.</p> - - <tp:rationale> - <p>Any extra parameters that do affect the channel dispatcher should - be designed separately.</p> - </tp:rationale> - - <p>This property may be set when the channel request is created, and - can never change. Since it is immutable, it SHOULD be included in the - dictionary of properties passed to <tp:dbus-ref - namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref> - by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p> - </tp:docstring> - </property> - - <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel"> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Variant of the <tp:dbus-ref - namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal - allowing to get the channel which has been created.</p> - </tp:docstring> - - <arg name="Connection" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The Connection owning the channel.</p> - </tp:docstring> - </arg> - - <arg name="Channel" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The channel which has been created.</p> - </tp:docstring> - </arg> - - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Call.xml b/qt4/spec/Channel_Type_Call.xml deleted file mode 100644 index 045d41693..000000000 --- a/qt4/spec/Channel_Type_Call.xml +++ /dev/null @@ -1,1429 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for making audio and video calls. Call - channels supersede the old <tp:dbus-ref - namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref> - channel type. Call channels are much more flexible than its - predecessor and allow more than two participants.</p> - - <p>Handlers are advised against executing all the media - signalling, codec and candidate negotiation themselves but - instead use a helper library such as <a - href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a> - which when given a new Call channel will set up the - transports and codecs and create GStreamer pads which - can be added to the handler UI. This is useful as it means - the handler does not have to worry how exactly the - connection between the call participants is being made.</p> - - <p>The <tp:dbus-ref - namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> - properties in a Call channel refer to the contact that the - user initially called, or which contact initially called the - user. Even in a conference call, where there are multiple - contacts in the call, these properties refer to the - initial contact, who might have left the conference since - then. As a result, handlers should not rely on these - properties.</p> - - <h4>Contents</h4> - - <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> - objects represent the actual media that forms the Call (for - example an audio content and a video content). Calls always - have one or more Content objects associated with them. As a - result, a new Call channel request MUST have either - <tp:member-ref>InitialAudio</tp:member-ref>=True, or - <tp:member-ref>InitialVideo</tp:member-ref>=True, or both, - as the Requestable Channel Classes will document.</p> - - <p><tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have - one or more stream associated with them. More information on - these streams and how to maniuplate them can be found on the - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> - interface page.</p> - - <h4>Outgoing calls</h4> - - <p>To make an audio-only call to a contact <tt>foo@example.com</tt> - handlers should call:</p> - - <blockquote> - <pre> -<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ - ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', - ...<tp:member-ref>InitialAudio</tp:member-ref>: True, -})</pre></blockquote> - - <p>As always, <tp:dbus-ref - namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used - in place of - <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> - if the contact's handle is already known. To make an audio - and video call, the handler should also specify - <tp:member-ref>InitialVideo</tp:member-ref> The - connection manager SHOULD return a channel whose immutable - properties contain the local user as the <tp:dbus-ref - namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the - remote contact as the <tp:dbus-ref - namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>, - <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> = - <code>True</code> (indicating the call is outgoing).</p> - - <p>After a new Call channel is requested, the - <tp:member-ref>CallState</tp:member-ref> property will be - <tp:type>Call_State</tp:type>_Pending_Initiator. As the local - user is the initiator, the call must be accepted by the handler - by calling the <tp:member-ref>Accept</tp:member-ref> method. - At this point, <tp:member-ref>CallState</tp:member-ref> changes - to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies - that the call is ringing, waiting for the remote contact to - accept the call. All changes to - <tp:member-ref>CallState</tp:member-ref> property are signalled - using the <tp:member-ref>CallStateChanged</tp:member-ref> - signal.</p> - - <p>When the call is accepted by the remote contact, the - <tp:member-ref>CallStateChanged</tp:member-ref> signal fires - again to show that <tp:member-ref>CallState</tp:member-ref> = - <tp:type>Call_State</tp:type>_Accepted.</p> - - <p>At this point <a - href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a> - will signal that a pad is available for the handler to show - in the user interface.</p> - - <h5>Missed calls</h5> - - <p>If the remote contact does not accept the call in time, then - the call can be terminated by the server. Note that this only - happens in some protocols. Most XMPP clients, for example, do - not do this and rely on the call initiator terminating the call. - A missed call is shown in a Call channel by the - <tp:member-ref>CallState</tp:member-ref> property changing to - <tp:type>Call_State</tp:type>_Ended, and the - <tp:member-ref>CallStateReason</tp:member-ref> property changing - to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p> - - <h5>Rejected calls</h5> - - <p>If the remote contact decides he or she does not feel like - talking to the local user, he or she can reject his or her - incoming call. This will be shown in the Call channel by - <tp:member-ref>CallState</tp:member-ref> changing to - <tp:type>Call_State</tp:type>_Ended and the - <tp:member-ref>CallStateReason</tp:member-ref> property - changing to (remote contact, - <tp:type>Call_State</tp:type>_Change_Reason_User_Requested, - "org.freedesktop.Telepathy.Error.Rejected").</p> - - <h4>Incoming calls</h4> - - <p>When an incoming call occurs, something like the following - <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> - signal will occur:</p> - - <blockquote> - <pre> -<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([ - /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel, - { - ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42, - ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False, - ...<tp:member-ref>InitialAudio</tp:member-ref>: True, - ...<tp:member-ref>InitialVideo</tp:member-ref>: True, - ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio", - ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video", - ...<tp:member-ref>MutableContents</tp:member-ref>: True, - }])</pre></blockquote> - - <p>The <tp:member-ref>InitialAudio</tp:member-ref> and - <tp:member-ref>InitialVideo</tp:member-ref> properties show that - the call has been started with two contents: one for audio - streaming and one for video streaming. The - <tp:member-ref>InitialAudioName</tp:member-ref> and - <tp:member-ref>InitialVideoName</tp:member-ref> properties also - show that the aforementioned audio and video contents have names - "audio" and "video".</p> - - <p>Once the handler has notified the local user that there is an - incoming call waiting for acceptance, the handler should call - <tp:member-ref>SetRinging</tp:member-ref> to let the CM know. - The new channel should also be given to telepathy-farstream to - work out how the two participants will connect together. - telepathy-farstream will call the appropriate methods on the call's - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s - to negotiate codecs and transports.</p> - - <p>To pick up the call, the handler should call - <tp:member-ref>Accept</tp:member-ref>. The - <tp:member-ref>CallState</tp:member-ref> property changes to - <tp:type>Call_State</tp:type>_Accepted and once media is - being transferred, telepathy-farstream will notify the - handler of a new pad to be shown to the local user in the - UI</p> - - <p>To reject the call, the handler should call the - <tp:member-ref>Hangup</tp:member-ref> method. The - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and the - <tp:member-ref>CallStateReason</tp:member-ref> property will - change to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Rejected").</p> - - <h4>Ongoing calls</h4> - - <h5>Adding and removing contents</h5> - - <p>When a call is open, new contents can be added as long as the - CM supports it. The - <tp:member-ref>MutableContents</tp:member-ref> property will let - the handler know whether further contents can be added or - existing contents removed. An example of this is starting a - voice call between a contact and then adding a video content. - To do this, the should call - <tp:member-ref>AddContent</tp:member-ref> like this:</p> - - <blockquote> - <pre><tp:member-ref>AddContent</tp:member-ref>("video", - <tp:type>Media_Stream_Type</tp:type>_Video)</pre> - </blockquote> - - <p>Assuming no errors, the new video content will be added to - the call. telepathy-farstream will pick up the new content and - perform the transport and codec negotiation automatically. - telpathy-farstream will signal when the video is ready to - show in the handler's user interface.</p> - - <p>A similar method is used for removing contents from a call, - except that the <tp:dbus-ref - namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method - is on the <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p> - - <h5>Ending the call</h5> - - <p>To end the call, the handler should call the - <tp:member-ref>Hangup</tp:member-ref> method. The - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and - <tp:member-ref>CallStateReason</tp:member-ref> will change - to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Cancelled").</p> - - <p>If the other participant hangs up first then the - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and - <tp:member-ref>CallStateReason</tp:member-ref> will change - to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Terminated").</p> - - <h4>Multi-party calls</h4> - - [TODO] - - <h4>Call states</h4> - - <p>There are many combinations of the - <tp:member-ref>CallState</tp:member-ref> and - <tp:member-ref>CallStateReason</tp:member-ref> properties which - mean different things. Here is a table to try to make these - meanings clearer:</p> - - <table> - <tr> - <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th> - <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th> - <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th> - <th rowspan="2">Meaning</th> - </tr> - <tr> - <th>Actor</th> - <th>Reason</th> - <th>DBus_Reason</th> - </tr> - <!-- Pending_Initiator --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Initiator</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td> - </tr> - <!-- Pending_Receiver --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call is waiting for the remote contact to pick up the call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>0</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td> - <td>""</td> - <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td> - </tr> - <!-- Accepted --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The remote contact accepted the outgoing call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The local user accepted the incoming call.</td> - </tr> - <!-- Ended --> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Cancelled</tp:error-ref></td> - <td>The local user hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Terminated</tp:error-ref></td> - <td>The remote contact hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td> - <td>""</td> - <td>The outgoing call was not picked up and the call ended.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td> - <td>The incoming call was ended because it was picked up elsewhere.</td> - </tr> - </table> - - <h4>Requestable channel classes</h4> - - <p>The <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> - for <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels - can be:</p> - - <blockquote> - <pre> -[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:member-ref>InitialVideo</tp:member-ref>: True - }, - Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>, - ...<tp:member-ref>InitialAudio</tp:member-ref>, - ...<tp:member-ref>InitialAudioName</tp:member-ref> - ] -), -( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:member-ref>InitialAudio</tp:member-ref>: True - }, - Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>, - ...<tp:member-ref>InitialVideo</tp:member-ref>, - ...<tp:member-ref>InitialVideoName</tp:member-ref> - ] -)]</pre></blockquote> - - <p>Clients aren't allowed to make outgoing calls that have - neither initial audio nor initial video. Clearly, CMs - which don't support video should leave out the first class and - omit <tp:member-ref>InitialVideo</tp:member-ref> from the second - class, and vice versa for CMs without audio support.</p> - - <p>Handlers should not close <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels - without first calling <tp:member-ref>Hangup</tp:member-ref> on - the channel. If a Call handler crashes, the <tp:dbus-ref - namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call - <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the - channel which SHOULD also imply a call to - <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Terminated", "") before - actually closing the channel.</p> - - </tp:docstring> - - <method name="SetRinging" tp:name-for-bindings="Set_Ringing"> - <tp:changed version="0.21.2">renamed from Ringing</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Indicate that the local user has been alerted about the incoming - call.</p> - - <p>This method is only useful if the - channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> - property is False, and - the <tp:member-ref>CallState</tp:member-ref> is - <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming - call waiting on the local user to pick up). While this is - the case, this method SHOULD change the - <tp:member-ref>CallFlags</tp:member-ref> to include - <tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the - remote contact that the local user has been alerted (if the - protocol implements this); repeated calls to this method - SHOULD succeed, but have no further effect.</p> - - <p>In all other states, this method SHOULD fail with the error - NotAvailable.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The call was <tp:dbus-ref namespace="ofdT.Channel" - >Requested</tp:dbus-ref>, so ringing does not make sense. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call is no longer in state - <tp:type>Call_State</tp:type>_Pending_Receiver. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Accept" tp:name-for-bindings="Accept"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For incoming calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, accept the - incoming call; this changes the - <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Accepted.</p> - - <p>For outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Initiator, actually - call the remote contact; this changes the - <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Pending_Receiver.</p> - - <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> - - <p>This method should be called exactly once per Call, by whatever - client (user interface) is handling the channel.</p> - - <p>When this method is called, for each <tp:dbus-ref - namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose - <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" - >Disposition</tp:dbus-ref> is - <tp:type>Call_Content_Disposition</tp:type>_Initial, any - streams where the <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> - is <tp:type>Sending_State</tp:type>_Pending_Send will be - moved to <tp:type>Sending_State</tp:type>_Sending as if - <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" - >SetSending</tp:dbus-ref>(True) had been called.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call is not in one of the states where this method makes sense. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Hangup" tp:name-for-bindings="Hangup"> - <tp:docstring> - Request that the call is ended. All contents will be removed - from the Call so that the - <tp:member-ref>Contents</tp:member-ref> property will be the - empty list. - </tp:docstring> - - <arg direction="in" name="Reason" - type="u" tp:type="Call_State_Change_Reason"> - <tp:docstring> - A generic hangup reason. - </tp:docstring> - </arg> - - <arg direction="in" name="Detailed_Hangup_Reason" - type="s" tp:type="DBus_Error_Name"> - <tp:docstring> - A more specific reason for the call hangup, if one is available, or - an empty string otherwise. - </tp:docstring> - </arg> - - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A human-readable message to be sent to the remote contact(s). - - <tp:rationale> - XMPP Jingle allows calls to be terminated with a human-readable - message. - </tp:rationale> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call has already been ended. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="AddContent" tp:name-for-bindings="Add_Content"> - <tp:docstring> - Request that a new <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type - Content_Type is added to the Call. Handlers should check the - value of the <tp:member-ref>MutableContents</tp:member-ref> - property before trying to add another content as it might not - be allowed. - </tp:docstring> - <arg direction="in" name="Content_Name" type="s"> - <tp:docstring> - <p>The suggested name of the content to add.</p> - - <tp:rationale> - The content name property should be meaningful, so should - be given a name which is significant to the user. The name - could be a localized "audio", "video" or perhaps include - some string identifying the source, such as a webcam - identifier. - </tp:rationale> - - <p>If there is already a content with the same name as this - property then a sensible suffix should be added. For example, - if this argument is "audio" but a content of the same name - already exists, a sensible suffix such as " (1)" is appended - to name the new content "audio (1)". A further content with the - name "audio" would then be named "audio (2)".</p> - - </tp:docstring> - </arg> - <arg direction="in" name="Content_Type" type="u" - tp:type="Media_Stream_Type"> - <tp:docstring> - The media stream type of the content to be added to the - call. - </tp:docstring> - </arg> - <arg direction="out" name="Content" type="o"> - <tp:docstring> - Path to the newly-created <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Call.Content.DRAFT</tp:dbus-ref> object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The media stream type given is invalid. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The media stream type requested is not implemented by the - CM. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> - <tp:docstring> - The content type requested cannot be added to this - call. Examples of why this might be the case include - because a second video stream cannot be added, or a - content cannot be added when the content set isn't - mutable. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="ContentAdded" - tp:name-for-bindings="Content_Added"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is added to the call.</p> - </tp:docstring> - <arg name="Content" type="o"> - <tp:docstring> - Path to the newly-created <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> object. - </tp:docstring> - </arg> - </signal> - - <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> - </tp:docstring> - <arg name="Content" type="o"> - <tp:docstring> - The <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> which was removed. - </tp:docstring> - </arg> - </signal> - - <property name="Contents" type="ao" access="read" - tp:name-for-bindings="Contents"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The list of <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that - are part of this call. Change notification is via the - <tp:member-ref>ContentAdded</tp:member-ref> and - <tp:member-ref>ContentRemoved</tp:member-ref> signals. - </p> - </tp:docstring> - </property> - - <tp:enum type="u" name="Call_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The state of a call, as a whole.</p> - - <p>The allowed transitions are:</p> - - <ul> - <li>Pending_Initiator → Pending_Receiver (for outgoing calls, - when <tp:member-ref>Accept</tp:member-ref> is called)</li> - <li>Pending_Receiver → Accepted (for incoming calls, when - <tp:member-ref>Accept</tp:member-ref> is called; for outgoing - calls to a contact, when the remote contact accepts the call; - for joining a conference call, when the local user successfully - joins the conference)</li> - <li>Accepted → Pending_Receiver (when transferred to another - contact)</li> - <li>any state → Ended (when the call is terminated normally, or - when an error occurs)</li> - </ul> - - <p>Clients MAY consider unknown values from this enum to be an - error - additional values will not be defined after the Call - specification is declared to be stable.</p> - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value = "0"> - <tp:docstring> - The call state is not known. This call state MUST NOT appear as a - value of the <tp:member-ref>CallState</tp:member-ref> property, but - MAY be used by client code to represent calls whose state is as yet - unknown. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Pending_Initiator" value = "1"> - <tp:docstring> - The initiator of the call hasn't accepted the call yet. This state - only makes sense for outgoing calls, where it means that the local - user has not yet sent any signalling messages to the remote user(s), - and will not do so until <tp:member-ref>Accept</tp:member-ref> is - called. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Pending_Receiver" value = "2"> - <tp:docstring> - The receiver (the contact being called) hasn't accepted the call yet. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Accepted" value = "3"> - <tp:docstring> - The contact being called has accepted the call. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Ended" value = "4"> - <tp:docstring> - The call has ended, either via normal termination or an error. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u"> - <tp:docstring> - A set of flags representing the status of the call as a whole, - providing more specific information than the - <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make - sense in a particular state. - </tp:docstring> - - <tp:flag suffix="Locally_Ringing" value="1"> - <tp:docstring> - The local contact has been alerted about the call but has not - responded; if possible, the remote contact(s) have been informed of - this fact. This flag only makes sense on incoming calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD - be set when <tp:member-ref>SetRinging</tp:member-ref> is - called successfully, and unset when the state changes. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Queued" value="2"> - <tp:docstring> - The contact is temporarily unavailable, and the call has been placed - in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). - This flag only makes sense on outgoing 1-1 calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be - set or unset according to informational messages from other - contacts. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Locally_Held" value="4"> - <tp:docstring> - The call has been put on hold by the local user, e.g. using - the <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Hold</tp:dbus-ref> interface. This flag SHOULD only be set - if there is at least one Content, and all Contents are - locally held; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver - or <tp:type>Call_State</tp:type>_Accepted. - - <tp:rationale> - Otherwise, in transient situations where some but not all contents - are on hold, UIs would falsely indicate that the call as a whole - is on hold, which could lead to the user saying something they'll - regret, while under the impression that the other contacts can't - hear them! - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Forwarded" value="8"> - <tp:docstring> - The initiator of the call originally called a contact other than the - current recipient of the call, but the call was then forwarded or - diverted. This flag only makes sense on outgoing calls, in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset - according to informational messages from other contacts. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="In_Progress" value="16"> - <tp:docstring> - Progress has been made in placing the outgoing call, but the - contact may not have been made aware of the call yet - (so the Ringing state is not appropriate). This corresponds to SIP's - status code 183 Session Progress, and could be used when the - outgoing call has reached a gateway, for instance. - This flag only makes sense on outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set - or unset according to informational messages from servers, gateways - and other infrastructure. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Clearing" value="32"> - <tp:docstring> - This flag only occurs when the CallState is Ended. The call with - this flag set has ended, but not all resources corresponding to the - call have been freed yet. - - Depending on the protocol there might be some audible feedback while - the clearing flag is set. - - <tp:rationale> - In calls following the ITU-T Q.931 standard there is a period of - time between the call ending and the underlying channel being - completely free for re-use. - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Muted" value="64"> - <tp:docstring> - The call has been muted by the local user, e.g. using the - <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only - be set if there is at least one Content, and all Contents - are locally muted; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="CallStateDetails" - tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map used to provide optional extensible details for the - <tp:member-ref>CallState</tp:member-ref>, - <tp:member-ref>CallFlags</tp:member-ref> and/or - <tp:member-ref>CallStateReason</tp:member-ref>.</p> - - <p>Well-known keys and their corresponding value types include:</p> - - <dl> - <dt>hangup-message - s</dt> - <dd>An optional human-readable message sent when the call was ended, - corresponding to the Message argument to the - <tp:member-ref>Hangup</tp:member-ref> method. This is only - applicable when the call state is <tp:type>Call_State</tp:type>_Ended. - <tp:rationale> - XMPP Jingle can send such messages. - </tp:rationale> - </dd> - - <dt>queue-message - s</dt> - <dd>An optional human-readable message sent when the local contact - is being held in a queue. This is only applicable when - <tp:type>Call_Flags</tp:type>_Queued is in the call flags. - <tp:rationale> - SIP 182 notifications can have human-readable messages attached. - </tp:rationale> - </dd> - - <dt>debug-message - s</dt> - <dd>A message giving further details of any error indicated by the - <tp:member-ref>CallStateReason</tp:member-ref>. This will not - normally be localized or suitable for display to users, and is only - applicable when the call state is - <tp:type>Call_State</tp:type>_Ended.</dd> - </dl> - </tp:docstring> - </property> - - <property name="CallState" type="u" access="read" - tp:name-for-bindings="Call_State" tp:type="Call_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The current high-level state of this call. The - <tp:member-ref>CallFlags</tp:member-ref> provide additional - information, and the <tp:member-ref>CallStateReason</tp:member-ref> - and <tp:member-ref>CallStateDetails</tp:member-ref> explain the - reason for the current values for those properties.</p> - - <p>Note that when in a conference call, this property is - purely to show your state in joining the call. The receiver - (or remote contact) in this context is the conference server - itself. The property does not change when other call members' - states change.</p> - - <p>Clients MAY consider unknown values in this property to be an - error.</p> - </tp:docstring> - </property> - - <property name="CallFlags" type="u" access="read" - tp:name-for-bindings="Call_Flags" tp:type="Call_Flags"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Flags representing the status of the call as a whole, - providing more specific information than the - <tp:member-ref>CallState</tp:member-ref>.</p> - - <p>Clients are expected to ignore unknown flags in this property, - without error.</p> - - <p>When an ongoing call is active and not on hold or has any - other problems, this property will be 0.</p> - </tp:docstring> - </property> - - <tp:enum name="Call_State_Change_Reason" type="u"> - <tp:docstring> - A simple representation of the reason for a change in the call's - state, which may be used by simple clients, or used as a fallback - when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type> - struct is not understood. - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - We just don't know. Unknown values of this enum SHOULD also be - treated like this. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="User_Requested" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change was requested by the contact indicated by the Actor - member of a <tp:type>Call_State_Reason</tp:type> struct.</p> - - <p>If the Actor is the local user, the DBus_Reason SHOULD be the - empty string.</p> - - <p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty - string if the call was terminated normally, but MAY be a non-empty - error name to indicate error-like call termination reasons (call - rejected as busy, kicked from a conference by a moderator, etc.).</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Forwarded" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call was forwarded. If known, the handle of the contact - the call was forwarded to will be indicated by the Actor member - of a <tp:type>Call_State_Reason</tp:type> struct.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="No_Answer" value="3"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:member-ref>CallState</tp:member-ref> changed from - <tp:type>Call_State</tp:type>_Pending_Receiver to - <tp:type>Call_State</tp:type>_Ended because the initiator - ended the call before the receiver accepted it. With an - incoming call this state change reason signifies a missed - call.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Call_State_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A description of the reason for a change to the - <tp:member-ref>CallState</tp:member-ref> and/or - <tp:member-ref>CallFlags</tp:member-ref>.</p> - </tp:docstring> - - <tp:member type="u" tp:type="Contact_Handle" name="Actor"> - <tp:docstring> - The contact responsible for the change, or 0 if no contact was - responsible. - </tp:docstring> - </tp:member> - - <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason"> - <tp:docstring> - The reason, chosen from a limited set of possibilities defined by - the Telepathy specification. If - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then - the Actor member will dictate whether it was the local user or - a remote contact responsible. - </tp:docstring> - </tp:member> - - <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specific reason for the change, which may be a D-Bus error in - the Telepathy namespace, a D-Bus error in any other namespace - (for implementation-specific errors), or the empty string to - indicate that the state change was not an error.</p> - - <p>This SHOULD be an empty string for changes to any state other - than Ended.</p> - - <p>The errors Cancelled and Terminated SHOULD NOT be used here; - an empty string SHOULD be used instead.</p> - - <tp:rationale> - <p>Those error names are used to indicate normal call - termination by the local user or another user, respectively, - in contexts where a D-Bus error name must appear.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason" - type="(uus)" access="read" tp:type="Call_State_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The reason for the last change to the - <tp:member-ref>CallState</tp:member-ref> and/or - <tp:member-ref>CallFlags</tp:member-ref>. The - <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional - information.</p> - </tp:docstring> - </property> - - <signal name="CallStateChanged" - tp:name-for-bindings="Call_State_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the state of the call as a whole changes.</p> - - <p>This signal is emitted for any change in the properties - corresponding to its arguments, even if the other properties - referenced remain unchanged.</p> - </tp:docstring> - - <arg name="Call_State" type="u" tp:type="Call_State"> - <tp:docstring> - The new value of the <tp:member-ref>CallState</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_Flags" type="u" tp:type="Call_Flags"> - <tp:docstring> - The new value of the <tp:member-ref>CallFlags</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason"> - <tp:docstring> - The new value of the <tp:member-ref>CallStateReason</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_State_Details" type="a{sv}"> - <tp:docstring> - The new value of the <tp:member-ref>CallStateDetails</tp:member-ref> - property. - </tp:docstring> - </arg> - </signal> - - <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If this property is True, all of the media streaming is done by some - mechanism outside the scope of Telepathy.</p> - - <tp:rationale> - <p>A connection manager might be intended for a specialized hardware - device, which will take care of the audio streaming (e.g. - telepathy-yafono, which uses GSM hardware which does the actual - audio streaming for the call).</p> - </tp:rationale> - - <p>If this is False, the handler is responsible for doing the actual - media streaming for at least some contents itself. Those contents - will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary - information to a streaming implementation. Connection managers SHOULD - operate like this, if possible.</p> - - <tp:rationale> - <p>Many connection managers (such as telepathy-gabble) only do the - call signalling, and expect the client to do the actual streaming - using something like - <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve - latency and allow better UI integration.</p> - </tp:rationale> - </tp:docstring> - </property> - - <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A set of flags representing the status of a remote contact in a - call.</p> - - <p>It is protocol- and client-specific whether a particular contact - will ever have a particular flag set on them, and Telepathy clients - SHOULD NOT assume that a flag will ever be set.</p> - - <tp:rationale> - <p>180 Ringing in SIP, and its equivalent in XMPP, are optional - informational messages, and implementations are not required - to send them. The same applies to the messages used to indicate - hold state.</p> - </tp:rationale> - </tp:docstring> - - <tp:flag suffix="Ringing" value = "1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The remote contact's client has told us that the contact has been - alerted about the call but has not responded.</p> - - <tp:rationale> - <p>This is a flag per member, not a flag for the call as a whole, - because in Muji conference calls, you could invite someone and - have their state be "ringing" for a while.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Held" value = "2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call member has put this call on hold.</p> - - <tp:rationale> - <p>This is a flag per member, not a flag for the call as a whole, - because in conference calls, any member could put the conference - on hold.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Conference_Host" value="4"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This contact has merged this call into a conference. Note that GSM - provides a notification when the remote party merges a call into a - conference, but not when it is split out again; thus, this flag can - only indicate that the call has been part of a conference at some - point. If a GSM connection manager receives a notification that a - call has been merged into a conference a second time, it SHOULD - represent this by clearing and immediately re-setting this flag on - the remote contact. - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List"> - <tp:docstring>A mapping from handles to their current state in the call. - </tp:docstring> - <tp:member type="u" tp:type="Handle" name="key"/> - <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/> - </tp:mapping> - - <signal name="CallMembersChanged" - tp:name-for-bindings="Call_Members_Changed"> - <tp:docstring> - Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property - changes in any way, either because contacts have been added to the - call, contacts have been removed from the call, or contacts' flags - have changed. - </tp:docstring> - - <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map"> - <tp:docstring> - A map from members of the call to their new call member flags, - including at least the members who have been added to - <tp:member-ref>CallMembers</tp:member-ref>, and the members whose - flags have changed. - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who have left the call, i.e. keys to be removed - from <tp:member-ref>CallMembers</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <property name="CallMembers" tp:name-for-bindings="Call_Members" - type="a{uu}" access="read" tp:type="Call_Member_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from the remote contacts that are part of this call to flags - describing their status. This mapping never has the local user's handle - as a key.</p> - - <p>When the call ends, this property should be an empty list, - and notified with - <tp:member-ref>CallMembersChanged</tp:member-ref></p> - - <p>If the Call implements - <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Group</tp:dbus-ref> and the Group members are - channel-specific handles, then this call SHOULD also use - channel-specific handles.</p> - - <p>Anonymous members are exposed as channel-specific handles - with no owner.</p> - </tp:docstring> - </property> - - <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" - type="u" tp:type="Stream_Transport_Type" access="read" - tp:requestable="yes" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If set on a requested channel, this indicates the transport that - should be used for this call. Where not applicable, this property - is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown, - in particular, on CMs with hardware streaming.</p> - - <tp:rationale> - When implementing a voip gateway one wants the outgoing leg of the - gatewayed to have the same transport as the incoming leg. This - property allows the gateway to request a Call with the right - transport from the CM. - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" - type="b" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If set to True in a channel request that will create a new channel, - the connection manager should immediately attempt to establish an - audio stream to the remote contact, making it unnecessary for the - client to call <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.</p> - - <p>If this property, or InitialVideo, 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> - - <p>If True on a requested channel, this indicates that the audio - stream has already been requested and the client does not need to - call RequestStreams, although it MAY still do so.</p> - - <p>If True on an unrequested (incoming) channel, this indicates that - the remote contact initially requested an audio stream; this does - not imply that that audio stream is still active (as indicated by - <tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT" - >Contents</tp:dbus-ref>).</p> - - <p>The name of this new content can be decided by using the - <tp:member-ref>InitialAudioName</tp:member-ref> property.</p> - - <p>Connection managers that support the <tp:dbus-ref - namespace="ofdT.Connection.Interface">ContactCapabilities</tp:dbus-ref> - interface SHOULD represent the capabilities of receiving audio - and/or video calls by including a channel class in - a contact's capabilities with ChannelType = Call - in the fixed properties dictionary, and InitialAudio and/or - InitialVideo in the allowed properties list. Clients wishing to - discover whether a particular contact is likely to be able to - receive audio and/or video calls SHOULD use this information.</p> - - <tp:rationale> - <p>Not all clients support video calls, and it would also be - possible (although unlikely) to have a client which could only - stream video, not audio.</p> - </tp:rationale> - - <p>Clients that are willing to receive audio and/or video calls - SHOULD include the following among their channel classes if - calling <tp:dbus-ref - namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> - (clients of a <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="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - properties):</p> - - <ul> - <li>{ ChannelType = Call }</li> - <li>{ ChannelType = Call, InitialAudio = True } - if receiving calls with audio is supported</li> - <li>{ ChannelType = Call, InitialVideo = True } - if receiving calls with video is supported</li> - </ul> - - <tp:rationale> - <p>Connection managers for protocols with capability discovery, - like XMPP, need this information to advertise the appropriate - capabilities for their protocol.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialVideo" tp:name-for-bindings="Initial_Video" - type="b" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for - a video stream. This property is immutable (cannot change).</p> - - <p>In particular, note that if this property is False, this does not - imply that an active video stream has not been added, only that no - video stream was active at the time the channel appeared.</p> - - <p>This property is the correct way to discover whether connection - managers, contacts etc. support video calls; it appears in - capabilities structures in the same way as InitialAudio.</p> - </tp:docstring> - </property> - - <property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name" - type="s" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to - True, then this property will name the intial audio content - with the value of this property.</p> - - <tp:rationale> - <p>Content names are meant to be significant, but if no name - can be given to initial audio content, then its name cannot - be meaningful or even localized.</p> - </tp:rationale> - - <p>If this property is empty or missing from the channel - request and InitialAudio is True, then the CM must come up - with a sensible for the content, such as "audio".</p> - - <p>If the protocol has no concept of stream names then this - property will not show up in the allowed properties list of - the Requestable Channel Classes for call channels.</p> - </tp:docstring> - </property> - - <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name" - type="s" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same as - <tp:member-ref>InitialAudioName</tp:member-ref>, but for a - video stream created by setting - <tp:member-ref>InitialVideo</tp:member-ref> to True. This - property is immutable and so cannot change.</p> - </tp:docstring> - </property> - - <property name="MutableContents" tp:name-for-bindings="Mutable_Contents" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If True, a stream of a different content type can be added - after the Channel has been requested </p> - - <p>If this property is missing, clients SHOULD assume that it is False, - and thus that the channel's streams cannot be changed once the call - has started.</p> - - <p>If this property isn't present in the "allowed" set in any of the - Call entries contact capabilities, then user interfaces MAY choose to - show a separate "call" option for each class of call.</p> - - <tp:rationale> - <p>For example, once an audio-only Google Talk call has started, - it is not possible to add a video stream; both audio and video - must be requested at the start of the call if video is desired. - User interfaces may use this pseudo-capability as a hint to - display separate "Audio call" and "Video call" buttons, rather - than a single "Call" button with the option to add and remove - video once the call has started for contacts without this flag. - </p> - </tp:rationale> - </tp:docstring> - </property> - - <tp:hct name="audio"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This client supports audio calls.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="video"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This client supports video calls.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="gtalk-p2p"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="ice"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="wlm-2009"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="shm"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="video/h264" is-family="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client supports media streaming with H264 (etc.).</p> - - <p>This handler capability token is a one of a family - of similar tokens: for any other audio or video codec whose MIME - type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler - capability token of this form may exist (the subtype MUST appear - in lower case in this context). Clients MAY support more - codecs than they explicitly advertise support for; clients SHOULD - explicitly advertise support for their preferred codec(s), and - for codecs like H264 that are, in practice, significant in codec - negotiation.</p> - - <tp:rationale> - <p>For instance, the XMPP capability used by the Google Video - Chat web client to determine whether a client is compatible - with it requires support for H264 video, so an XMPP - connection manager that supports this version of Jingle should - not advertise the Google Video Chat capability unless there - is at least one installed client that declares that it supports - <code>video/h264</code> on Call channels.</p> - </tp:rationale> - - <p>For example, a client could advertise support for audio and video - calls using Speex, Theora and H264 by having five handler capability - tokens in its <tp:dbus-ref - namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref> - property:</p> - - <ul> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li> - </ul> - - <p>Clients MAY have media signalling abilities without explicitly - supporting any particular codec, and connection managers SHOULD - support this usage.</p> - - <tp:rationale> - <p>This is necessary to support gatewaying between two Telepathy - connections, in which case the available codecs might not be - known to the gatewaying process.</p> - </tp:rationale> - </tp:docstring> - </tp:hct> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Contact_List.xml b/qt4/spec/Channel_Type_Contact_List.xml deleted file mode 100644 index 5a0d33362..000000000 --- a/qt4/spec/Channel_Type_Contact_List.xml +++ /dev/null @@ -1,104 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Contact_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:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.ContactList"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for representing a list of people on the server which is - not used for communication. This is intended for use with the interface - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> - for managing buddy lists and privacy lists - on the server. This channel type has no methods because all of the - functionality it represents is available via the group interface.</p> - - <p>There are currently two types of contact list: - HANDLE_TYPE_LIST is a "magic" server-defined list, and - HANDLE_TYPE_GROUP is a user-defined contact group.</p> - - <p>For server-defined lists like the subscribe list, singleton instances - of this channel type should be created by the connection manager at - connection time if the list exists on the server, or may be requested - by using the appropriate handle. These handles can be obtained using - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> - with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_LIST and one of the - following identifiers:</p> - - <ul> - <li>subscribe - the group of contacts for whom you receive presence</li> - <li>publish - the group of contacts who may receive your presence</li> - <li>hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence</li> - <li>allow - a group of contacts who may send you messages</li> - <li>deny - a group of contacts who may not send you messages</li> - <li>stored - on protocols where the user's contacts are stored, this - contact list contains all stored contacts regardless of subscription - status.</li> - </ul> - - <p>A contact can be in several server-defined lists. All lists are optional - to implement. If <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> - for a particular contact list raises an error, this indicates that the - connection manager makes no particular statement about the list's contents; - clients MUST NOT consider this to be fatal.</p> - - <p>If a client wants to list all of a user's contacts, it is appropriate to - use the union of the subscribe, publish and stored lists, including the - local and remote pending members.</p> - - <p>For example in XMPP, contacts who have the subscription type "none", - "from", "to" and "both" can be respectively in the lists:</p> - - <ul> - <li>"none": stored</li> - <li>"from": stored and publish</li> - <li>"to": stored and subscribe</li> - <li>"both": stored, publish and subscribe</li> - </ul> - - <p>These contact list channels may not be closed.</p> - - <p>For user-defined contact groups, instances of this channel type should - be created by the connection manager at connection time for each group - that exists on the server. New, empty groups can be created by calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> - with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_GROUP and with the - name set to the human-readable UTF-8 name of the group.</p> - - <p>User-defined groups may be deleted by calling <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> on the - channel, but only if - the group is already empty. Closing a channel to a non-empty group is - not allowed; its members must be set to the empty set first.</p> - - <p>On some protocols (e.g. XMPP) empty groups are not represented on the - server, so disconnecting from the server and reconnecting might cause - empty groups to vanish.</p> - </tp:docstring> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Contact_Search.xml b/qt4/spec/Channel_Type_Contact_Search.xml deleted file mode 100644 index fefa77a26..000000000 --- a/qt4/spec/Channel_Type_Contact_Search.xml +++ /dev/null @@ -1,462 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:added version="0.19.10"> - as stable API. Changes from draft 2: - <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers - rather than handles; consequently, the values need not include - <tt>x-telepathy-identifier</tt>. - </tp:added> - - <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. Channels of this type should have <tp:dbus-ref - namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> - <code>None</code> (and hence <tp:dbus-ref - namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and - <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref> - <code>""</code>). Requests for channels of this type need only - optionally specify the <tp:member-ref>Server</tp:member-ref> property - (if it is an allowed property in the connection's <tp:dbus-ref - namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p> - - <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.</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> - - <tp:enum name="Channel_Contact_Search_State" type="u"> - <tp:enumvalue suffix="Not_Started" value="0"> - <tp:docstring>The search has not started</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="In_Progress" value="1"> - <tp:docstring>The search is in progress</tp:docstring> - </tp:enumvalue> - <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> - - <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:immutable='yes' tp:requestable='sometimes'> - <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 SHOULD be requestable 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:immutable='yes'> - <tp:docstring> - 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). - - <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> - </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. 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.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: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.Error.<tp:error-ref>Cancelled</tp:error-ref></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> - - <tp:mapping name="Contact_Search_Result_Map"> - <tp:docstring>A map from contact identifier to search result, emitted in - the <tp:member-ref>SearchResultReceived</tp:member-ref> - signal.</tp:docstring> - - <tp:member name="Contact_Identifier" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The identifier of a contact matching the search terms. - - <tp:rationale> - This is an identifier rather than a handle in case we make handles - immortal; see <a - href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a> - and <a - href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347 - comment 5</a>. - </tp:rationale> - </tp:docstring> - </tp:member> - - <tp:member 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</tp:dbus-ref> - interface. It is possible that a separate call to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref> - would return more information than this signal provides.</p> - </tp:docstring> - </tp:member> - </tp:mapping> - - <signal name="SearchResultReceived" - tp:name-for-bindings="Search_Result_Received"> - <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map"> - <tp:docstring>A mapping from contact identifier to an array of fields - representing information about this contact.</tp:docstring> - </arg> - - <tp:docstring> - Emitted when a some search results are received from the server. - This signal can be fired arbitrarily many times so clients MUST NOT - assume they'll get only one signal. - </tp:docstring> - </signal> - - <property name="Server" tp:name-for-bindings="Server" - type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'> - <tp:docstring> - <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 SHOULD be requestable 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> - </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 deleted file mode 100644 index 961576319..000000000 --- a/qt4/spec/Channel_Type_DBus_Tube.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus - traffic.</p> - - <p>For each D-Bus tube, the connection manager listens on a D-Bus - server address, as detailed in the D-Bus specification. On this - address, it emulates a bus upon which each tube participant appears - as an endpoint.</p> - - <p>The objects and interfaces which are expected to exist on the - emulated bus depend on the well-known name; typically, either the - participant who initiated the tube is expected to export the same - objects/interfaces that would be exported by a service of that name - on a bus, or all participants are expected to export those - objects/interfaces.</p> - - <p>In a multi-user context (Handle_Type_Room) the tube behaves - like the D-Bus bus daemon, so participants can send each other - private messages, or can send broadcast messages which are - received by everyone in the tube (including themselves). - Each participant has a D-Bus unique name; connection managers - MUST prevent participants from sending messages with the wrong - sender unique name, and SHOULD attempt to avoid participants - receiving messages not intended for them.</p> - - <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like - a peer-to-peer D-Bus connection - arbitrary D-Bus messages with - any sender and/or destination can be sent by each participant, - and each participant receives all messages sent by the other - participant.</p> - - </tp:docstring> - - <method name="Offer" tp:name-for-bindings="Offer"> - <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">Parameters</tp:dbus-ref> - to send with the tube offer. - </tp:docstring> - </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The access control the connection manager applies to the D-Bus socket. - </tp:docstring> - </arg> - <arg direction="out" name="address" type="s"> - <tp:docstring> - The string describing the address of the private bus. The client - SHOULD NOT attempt to connect to the address until the tube is open. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact associated with this channel doesn't have tubes - capabilities. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Accept" tp:name-for-bindings="Accept"> - <tp:docstring> - Accept a D-Bus tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref> - signal is emitted. - </tp:docstring> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The access control the connection manager applies to the D-Bus socket. - </tp:docstring> - </arg> - <arg direction="out" name="address" type="s"> - <tp:docstring> - The string describing the address of the private bus. The client - SHOULD NOT attempt to connect to the address until the tube is open. - </tp:docstring> - </arg> - </method> - - <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed"> - <tp:docstring> - Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a - participant opens or closes the tube. This provides change - notification for the <tp:member-ref>DBusNames</tp:member-ref> property. - </tp:docstring> - <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants"> - <tp:docstring> - Array of handles and D-Bus names of new participants. - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - Array of handles of former participants. - </tp:docstring> - </arg> - </signal> - - <property name="ServiceName" type="s" access="read" - tp:name-for-bindings="Service_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A string representing the service name that will be used over the - tube. It SHOULD be a well-known D-Bus service name, of the form - <tt>com.example.ServiceName</tt>.</p> - <p>When the tube is offered, the service name is transmitted to the - other end.</p> - <p>When requesting a channel with - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, - this property MUST be included in the request.</p> - </tp:docstring> - </property> - - <property name="DBusNames" tp:name-for-bindings="DBus_Names" - access="read" type="a{us}" tp:type="DBus_Tube_Participants"> - <tp:docstring> - For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping - between contact handles and their unique bus names on this tube. - For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty - dictionary. Change notification is via - <tp:member-ref>DBusNamesChanged</tp:member-ref>. - </tp:docstring> - </property> - - <tp:mapping name="DBus_Tube_Participants"> - <tp:docstring>Represents the participants in a multi-user D-Bus tube, as - used by the <tp:member-ref>DBusNames</tp:member-ref> property and the - <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"> - <tp:docstring> - The handle of a participant in this D-Bus tube. - </tp:docstring> - </tp:member> - <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> - <tp:docstring> - That participant's unique name. - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="SupportedAccessControls" type="au" - tp:type="Socket_Access_Control[]" access="read" - tp:name-for-bindings="Supported_Access_Controls"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the access control types that are supported with this channel. - Note that only Socket_Access_Control_Localhost and - Socket_Access_Control_Credentials can be used with D-Bus tubes.</p> - - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request.</p> - - </tp:docstring> - </property> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_File_Transfer.xml b/qt4/spec/Channel_Type_File_Transfer.xml deleted file mode 100644 index 6963d2133..000000000 --- a/qt4/spec/Channel_Type_File_Transfer.xml +++ /dev/null @@ -1,580 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> - 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 -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:added version="0.17.18">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for transferring files. The - transmission of data between contacts is achieved by reading from - or writing to a socket. The type of the socket (local Unix, IPv4, - etc.) is decided on when the file transfer is offered or accepted.</p> - - <p>A socket approach is used to make the transfer less dependent on both - client and connection manager knowing the same protocols. As an example, - when browsing an SMB share in a file manager, one selects "Send file" - and chooses a contact. Instead of passing a URL which would then require - the connection manager to connect to the SMB share itself, the client - passes a stream from which the connection manager reads, requiring no - further connection to the share. It also allows connection managers to - be more restricted in their access to the system, allowing tighter - security policies with eg SELinux, or more flexible deployments which - cross user or system boundaries.</p> - - <p>The Telepathy client should connect to the socket or address that - the connection manager has set up and provided back to the clients - through the two methods.</p> - - <ul><li>In order to send a file, one should request a FileTransfer - channel for a contact, including at least the mandatory properties - (<tp:member-ref>Filename</tp:member-ref>, - <tp:member-ref>Size</tp:member-ref> and <tp:member-ref>ContentType</tp:member-ref>). - Then, one should - call <tp:member-ref>ProvideFile</tp:member-ref> to configure the socket that - will be used to transfer the file.</li> - - <li>In order to receive an incoming file transfer, one should call - <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state - changes to Open. When the receiver wants to resume a transfer, the Offset - argument should be should be set to a non-zero value when calling - <tp:member-ref>AcceptFile</tp:member-ref>.</li> - - <li>Once the offset has been negotiated, the - <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal - is emitted and the <tp:member-ref>InitialOffset</tp:member-ref> property - is defined. The <tp:member-ref>InitialOffsetDefined</tp:member-ref> - signal is emitted before channel becomes Open. - The receiver MUST check the value of - <tp:member-ref>InitialOffset</tp:member-ref> for a difference in offset - from the requested value in AcceptFile.</li> - - <li>When the state changes to Open, Clients can start the transfer of the - file using the offset previously announced. - </li></ul> - - <p>If something goes wrong with the transfer, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> - should be called on the channel.</p> - - <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">UpdateCapabilities</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" - access="read" tp:name-for-bindings="State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The state of the file transfer as described by the - File_Transfer_State enum.</p> - </tp:docstring> - </property> - - <property name="ContentType" type="s" access="read" - tp:name-for-bindings="Content_Type"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The file's MIME type. This cannot change once the channel has - been created.</p> - - <p>This property is mandatory when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. Protocols which do not have a content-type property with file - transfers should set this value to application/octet-stream.</p> - </tp:docstring> - </property> - - <property name="Filename" type="s" access="read" - tp:name-for-bindings="Filename"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of the file on the sender's side. This is therefore given - as a suggested filename for the receiver. This cannot change - once the channel has been created.</p> - - <p>This property should be the basename of the file being sent. For example, - if the sender sends the file /home/user/monkey.pdf then this property should - be set to monkey.pdf.</p> - - <p>This property is mandatory when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. This property cannot be empty and MUST be set to a sensible value.</p> - </tp:docstring> - </property> - - <property name="Size" type="t" access="read" - tp:name-for-bindings="Size"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The size of the file. If this property is set, then the file - transfer is guaranteed to be this size. This cannot change once - the channel has been created.</p> - - <p>When you are creating a channel with this property, its value - MUST be accurate and in bytes. However, when receiving a file, this - property still MUST be in bytes but might not be entirely accurate - to the byte.</p> - - <p>This property is mandatory when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. If this information isn't provided in the protocol, connection managers MUST set it - to UINT64_MAX.</p> - </tp:docstring> - </property> - - <property name="ContentHashType" type="u" tp:type="File_Hash_Type" - access="read" tp:name-for-bindings="Content_Hash_Type"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p> - - <p>This property is optional when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref> - 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> - - <property name="ContentHash" type="s" access="read" - tp:name-for-bindings="Content_Hash"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Hash of the contents of the file transfer, of type described - in the value of the <tp:member-ref>ContentHashType</tp:member-ref> - property.</p> - - <p>This property is optional when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. Its value MUST correspond to the appropriate type of the - <tp:member-ref>ContentHashType</tp:member-ref> property. If the - ContentHashType property is not set, or set to File_Hash_Type_None, - then this property will not even be looked at.</p> - </tp:docstring> - </property> - - <property name="Description" type="s" access="read" - tp:name-for-bindings="Description"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Description of the file transfer. This cannot change once the - channel has been created.</p> - - <p>This property is optional when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method. If this property was not provided by the remote party, connection managers MUST set it to - the empty string.</p> - </tp:docstring> - </property> - - <property name="Date" type="x" access="read" - tp:type="Unix_Timestamp64" tp:name-for-bindings="Date"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The last modification time of the file being transferred. This - cannot change once the channel has been created</p> - - <p>This property is optional when requesting the channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> - method.</p> - </tp:docstring> - </property> - - <property name="AvailableSocketTypes" type="a{uau}" - tp:type="Supported_Socket_Map" access="read" - tp:name-for-bindings="Available_Socket_Types"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from address types (members of Socket_Address_Type) to - arrays of access-control type (members of Socket_Access_Control) - that the connection manager supports for sockets with that - address type. For simplicity, if a CM supports offering a - particular type of file transfer, it is assumed to support accepting - it. Connection Managers MUST support at least Socket_Address_Type_IPv4.</p> - - <p>A typical value for a host without IPv6 support:</p> - - <pre> - { - Socket_Address_Type_IPv4: - [Socket_Access_Control_Localhost, Socket_Access_Control_Port, - Socket_Access_Control_Netmask], - Socket_Address_Type_Unix: - [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] - } - </pre> - </tp:docstring> - </property> - - <property name="TransferredBytes" type="t" access="read" - tp:name-for-bindings="Transferred_Bytes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The number of bytes that have been transferred at the time of - requesting the property. This will be updated as the file transfer - continues.</p> - </tp:docstring> - </property> - - <property name="InitialOffset" type="t" access="read" - tp:name-for-bindings="Initial_Offset"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The offset in bytes from where the file should be sent. This MUST - be respected by both the receiver and the sender after the state - becomes Open, but before any data is sent or received. Until the - <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal - is emitted, this property is undefined.</p> - - <p>Before setting the <tp:member-ref>State</tp:member-ref> property to - Open, the connection manager MUST set the InitialOffset property, - possibly to 0.</p> - - <p>This property MUST NOT change after the state of the transfer has - changed to Open.</p> - </tp:docstring> - </property> - - <property name="URI" type="s" access="readwrite" - tp:name-for-bindings="URI" tp:immutable="sometimes" tp:requestable="yes"> - <tp:added version="0.21.9"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For outgoing file transfers, this requestable property allows the channel - requester to inform observers (and the handler, if it is not the requester - itself) of the URI of the file being transferred. Note that the - connection manager SHOULD NOT read this file directly; the handler - streams the file into the CM through the socket negotiated using - <tp:member-ref>ProvideFile</tp:member-ref>.</p> - - <p>On outgoing file transfers, this property MUST NOT change after the channel - is requested.</p> - - <p>For incoming file transfers, this property MAY be set by the channel - handler before calling <tp:member-ref>AcceptFile</tp:member-ref> to - inform observers where the incoming file will be saved. - Setting this property once <tp:member-ref>AcceptFile</tp:member-ref> - has been called MUST fail. Once this property has been set - <tp:member-ref>URIDefined</tp:member-ref> is emitted.</p> - - <p>If set, this URI SHOULD generally point to a file on the local system, as - defined by <a href='http://www.apps.ietf.org/rfc/rfc1738.html#sec-3.10'> - RFC 1738 §3.10</a>; that is, it should be of the form - <tt>file:///path/to/file</tt> or <tt>file://localhost/path/to/file</tt>. - For outgoing files, this URI MAY use a different scheme, such as - <tt>http:</tt>, if a remote resource is being transferred - to a contact.</p> - - </tp:docstring> - </property> - - <tp:enum name="File_Transfer_State" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - An invalid state type used as a null value. This value MUST NOT - appear in the State property. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Pending" value="1"> - <tp:docstring> - The file transfer is waiting to be accepted/closed by the receiver. - The receiver has to call <tp:member-ref>AcceptFile</tp:member-ref>, - then wait for the state to change to Open and check the offset value. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Accepted" value="2"> - <tp:docstring> - The receiver has accepted the transfer. The sender now has to - call <tp:member-ref>ProvideFile</tp:member-ref> to actually start the transfer. - The receiver should now wait for the state to change to Open - and check the offset value. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="3"> - <tp:docstring> - The file transfer is open for traffic. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Completed" value="4"> - <tp:docstring> - The file transfer has been completed successfully. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Cancelled" value="5"> - <tp:docstring> - The file transfer has been cancelled. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="File_Transfer_State_Change_Reason" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - No reason was specified. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Requested" value="1"> - <tp:docstring> - The change in state was requested. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Local_Stopped" value="2"> - <tp:docstring> - The file transfer was cancelled by the local user. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Stopped" value="3"> - <tp:docstring> - The file transfer was cancelled by the remote user. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Local_Error" value="4"> - <tp:docstring> - The file transfer was cancelled because of a local error. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Error" value="5"> - <tp:docstring> - The file transfer was cancelled because of a remote error. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="File_Hash_Type" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - No hash. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="MD5" value="1"> - <tp:docstring> - MD5 digest as a string of 32 ASCII hex digits. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="SHA1" value="2"> - <tp:docstring> - SHA1 digest as a string of ASCII hex digits. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="SHA256" value="3"> - <tp:docstring> - SHA256 digest as a string of ASCII hex digits. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <method name="AcceptFile" tp:name-for-bindings="Accept_File"> - <tp:docstring> - Accept a file transfer that's in the Pending state. The file - transfer's state becomes Accepted after this method is called. - At this point the client can connect to the socket. CM MUST emit - <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change - the state to Open before writing to the socket. - Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case - its value differs from the offset that was specified as an argument - to AcceptFile. - </tp:docstring> - <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of address the connection manager should listen on. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The type of access control the connection manager should apply to - the socket. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control_Param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="in" name="Offset" type="t"> - <tp:docstring> - The desired offset in bytes where the file transfer should start. - The offset is taken from the beginning of the file. Specifying an - offset of zero will start the transfer from the beginning of the - file. The offset that is actually given in the - <tp:member-ref>InitialOffset</tp:member-ref> property can differ - from this argument where the requested offset is not supported. - (For example, some protocols do not support offsets at all so - the InitialOffset property will always be 0.) - </tp:docstring> - </arg> - <arg direction="out" name="Address" type="v"> - <tp:docstring> - The address on which the connection manager will listen for - connections for this file transfer. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given address type or access-control mechanism is not supported. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:docstring> - Your address type, access control, access control parameter, - offset, or a combination of all four is invalid. - </tp:docstring> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The file transfer is not in the Pending state, there isn't - or there is a local error with acquiring a socket. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="ProvideFile" tp:name-for-bindings="Provide_File"> - <tp:docstring> - Provide the file for an outgoing file transfer which has been offered. - Opens a socket that the client can use to provide a file to the connection manager. - The channel MUST have been requested, and will change state - to Open when this method is called if its state was Accepted. - </tp:docstring> - <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of address the connection manager should listen on. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The type of access control the connection manager should apply to - the socket. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control_Param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="out" name="Address" type="v"> - <tp:docstring> - The address on which the connection manager will listen for - connections for this file transfer. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given address type or access-control mechanism is not supported. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:docstring> - Your address type, access control, access control parameter, or - a combination of all three is invalid. - </tp:docstring> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Channel is not an outgoing transfer, ProvideFile has already been called, - or there was a local error acquiring the socket. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="FileTransferStateChanged" - tp:name-for-bindings="File_Transfer_State_Changed"> - <tp:docstring> - Emitted when the state of a file transfer changes. - </tp:docstring> - <arg name="State" type="u" tp:type="File_Transfer_State"> - <tp:docstring> - The new state of the file transfer; see the File_Transfer_State enumeration. - </tp:docstring> - </arg> - <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason"> - <tp:docstring> - The reason for the state change; see the File_Transfer_State_Change_Reason - enumeration. - The value will always be File_Transfer_State_Change_Reason_None, except - when changing state to cancelled. - </tp:docstring> - </arg> - </signal> - - <signal name="TransferredBytesChanged" - tp:name-for-bindings="Transferred_Bytes_Changed"> - <tp:docstring> - Emitted when the number of transferred bytes changes. This will not be - signalled with every single byte change. Instead, the most frequent - this signal will be emitted is once a second. This should be - sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref> - property SHOULD NOT be polled. - </tp:docstring> - <arg name="Count" type="t"> - <tp:docstring> - The number of already transferred bytes. - </tp:docstring> - </arg> - </signal> - - <signal name="InitialOffsetDefined" - tp:name-for-bindings="Initial_Offset_Defined"> - <tp:docstring> - Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref> - property has been negotiated. This signal MUST be emitted before the channel - becomes Open and clients have to use this offset when transferring the - file. - </tp:docstring> - <arg name="InitialOffset" type="t"> - <tp:docstring> - The value of the <tp:member-ref>InitialOffset</tp:member-ref> property. - </tp:docstring> - </arg> - </signal> - - <signal name="URIDefined" - tp:name-for-bindings="URI_Defined"> - <tp:added version="0.21.9"/> - <tp:docstring> - Emitted when the value of the <tp:member-ref>URI</tp:member-ref> - property has been set. This signal MUST only be emitted on - incoming file transfers, and only if the handler sets the - <tp:member-ref>URI</tp:member-ref> property before - accepting the file. - </tp:docstring> - <arg name="URI" type="s"> - <tp:docstring> - The value of the <tp:member-ref>URI</tp:member-ref> property. - </tp:docstring> - </arg> - </signal> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Room_List.xml b/qt4/spec/Channel_Type_Room_List.xml deleted file mode 100644 index 98f745822..000000000 --- a/qt4/spec/Channel_Type_Room_List.xml +++ /dev/null @@ -1,166 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.RoomList"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:struct name="Room_Info" array-name="Room_Info_List"> - <tp:member type="u" tp:type="Room_Handle" name="Handle"/> - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> - <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/> - </tp:struct> - - <property name="Server" tp:name-for-bindings="Server" - type="s" access="read"> - <tp:docstring> - <p>For protocols with a concept of chatrooms on multiple servers - with different DNS names (like XMPP), the DNS name of the server - whose rooms are listed by this channel, e.g. "conference.jabber.org". - Otherwise, the empty string.</p> - - <p>This property cannot change during the lifetime of the channel.</p> - </tp:docstring> - </property> - - <method name="GetListingRooms" tp:name-for-bindings="Get_Listing_Rooms"> - <arg direction="out" type="b" name="In_Progress"> - <tp:docstring> - A boolean indicating if room listing is in progress - </tp:docstring> - </arg> - <tp:docstring> - Check to see if there is already a room list request in progress - on this channel. - </tp:docstring> - </method> - - <signal name="GotRooms" tp:name-for-bindings="Got_Rooms"> - <arg name="Rooms" type="a(usa{sv})" tp:type="Room_Info[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs containing: - <ul> - <li>an integer room handle</li> - <li>a string representing the D-Bus interface name of the channel type</li> - <li>a dictionary mapping string keys to variant boxed information</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when information about rooms on the server becomes available. - The array contains the room handle (as can be passed to the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> - method with HANDLE_TYPE_ROOM), the channel - type, and a dictionary containing further information about the - room as available. The following well-known keys and types are - recommended for use where appropriate:</p> - - <dl> - <dt>handle-name (s)</dt> - <dd>The identifier of the room (as would be returned by - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd> - - <dt>name (s)</dt> - <dd>The human-readable name of the room if different from the handle</dd> - - <dt>description (s)</dt> - <dd>A description of the room's overall purpose</dd> - - <dt>subject (s)</dt> - <dd>The current subject of conversation in the room (as would - be returned by getting the string part of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property)</dd> - - <dt>members (u)</dt> - <dd>The number of members in the room</dd> - - <dt>password (b)</dt> - <dd>True if the room requires a password to enter</dd> - - <dt>invite-only (b)</dt> - <dd>True if you cannot join the room, but must be invited</dd> - - <dt>room-id (s)</dt> - <dd>The human-readable identifier of a chat room (as would be - returned by getting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >RoomID</tp:dbus-ref> property)</dd> - - <dt>server (s)</dt> - <dd>The DNS name of the server hosting these channels (as would be - returned by getting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Server</tp:dbus-ref> property)</dd> - </dl> - </tp:docstring> - </signal> - <method name="ListRooms" tp:name-for-bindings="List_Rooms"> - <tp:docstring> - Request the list of rooms from the server. The - <tp:member-ref>ListingRooms</tp:member-ref> (True) signal should be - emitted when this request is being processed, - <tp:member-ref>GotRooms</tp:member-ref> when any room information is - received, and <tp:member-ref>ListingRooms</tp:member-ref> (False) when - the request is complete. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - <method name="StopListing" tp:name-for-bindings="Stop_Listing"> - <tp:docstring> - Stop the room listing if it's in progress, but don't close the channel. - The <tp:member-ref>ListingRooms</tp:member-ref> (False) signal should - be emitted when the listing stops. - </tp:docstring> - </method> - <signal name="ListingRooms" tp:name-for-bindings="Listing_Rooms"> - <arg name="Listing" type="b"> - <tp:docstring>A boolean indicating if room listing is in progress</tp:docstring> - </arg> - <tp:docstring> - Emitted to indicate whether or not room listing request is currently - in progress. - </tp:docstring> - </signal> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for listing named channels available on the server. Once the - <tp:member-ref>ListRooms</tp:member-ref> method is called, it emits signals for rooms present on the - server, until you <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> this - channel. In some cases, it may not be possible - to stop the deluge of information from the server. This channel should be - closed when the room information is no longer being displayed, so that the - room handles can be freed.</p> - - <p>This channel type may be implemented as a singleton on some protocols, so - clients should be prepared for the eventuality that they are given a - channel that is already in the middle of listing channels. The - <tp:member-ref>ListingRooms</tp:member-ref> signal, or - <tp:member-ref>GetListingRooms</tp:member-ref> method, can be used to check - this.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Server_Authentication.xml b/qt4/spec/Channel_Type_Server_Authentication.xml deleted file mode 100644 index 76599aa35..000000000 --- a/qt4/spec/Channel_Type_Server_Authentication.xml +++ /dev/null @@ -1,121 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Server_Authentication" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.ServerAuthentication"> - <tp:added version="0.21.5">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The type for a channel representing an authentication step with the - server. The actual authentication functionality is implemented by - the additional interface named in - <tp:member-ref>AuthenticationMethod</tp:member-ref>, - such as <tp:dbus-ref namespace="ofdT" - >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> - - <p>Future authentication steps also supported by this channel type might - include solving a captcha and/or agreeing to an EULA or terms-of-use - document; each of these would be represented by a channel with this - type, but a different - <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p> - - <p>Channels of this type will normally be be signalled and dispatched - while the <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref> - owning them is in the CONNECTING state. They MAY also appear on a - Connection in the CONNECTED state, for instance if periodic - re-authentication is required.</p> - - <p>Normally, only one channel of this type will - exist on a given Connection; if there is more than one, the handler - must complete authentication with each of them in turn.</p> - - <p>Channels of this type cannot be requested with methods such as - <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. - They always have <tp:dbus-ref - namespace="ofdT.Channel">Requested</tp:dbus-ref> = False, - <tp:dbus-ref - namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> = None - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - = 0.</p> - - <p>While it is CONNECTING, the Connection MUST NOT proceed with - connection, or signal - <tp:dbus-ref namespace="ofdT.Connection">StatusChanged</tp:dbus-ref> - to the CONNECTED state, until each channel of this type has either - been accepted as having a positive result (for instance, on SASL - channels this is done with the <tp:dbus-ref - namespace="ofdT.Channel.Interface.SASLAuthentication" - >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref - namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p> - - <tp:rationale> - <p>ServerAuthentication channels normally represent the client - authenticating itself to the server, but can also be used for the - server to authenticate itself to the client (i.e. prove that it is - in fact the desired server and not an imposter). Until the - authentication handler has confirmed this, connection should not - continue.</p> - </tp:rationale> - - <p>If a channel of this type is closed with the <tp:dbus-ref - namespace="ofdT.Channel">Close</tp:dbus-ref> method before - authentication has succeeded, this indicates that the Handler has - given up its attempts to authenticate or that no Handler is - available.</p> - - <p>If this occurs, the connection manager MAY attempt to continue - connection (for instance, performing SASL authentication by using any - credentials passed to <tp:dbus-ref - namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>, - for instance from the <tp:dbus-ref - namespace="ofdT">Account.Parameters</tp:dbus-ref>). If this fails - or has already been tried, the <tp:dbus-ref - namespace="ofdT">Connection</tp:dbus-ref> will - disconnect.</p> - - <tp:rationale> - <p>In particular, the <tp:dbus-ref - namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will close the - channel if it cannot find a handler.</p> - </tp:rationale> - - <p>When the connection is done with the channel and it is no - longer needed, it is left open until either the connection state - turns to DISCONNECTED or the handler closes the channel. The - channel SHOULD NOT close itself once finished with.</p> - </tp:docstring> - - <property name="AuthenticationMethod" - tp:name-for-bindings="Authentication_Method" - type="s" tp:type="DBus_Interface" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This property defines the method used for the authentication step - represented by this channel, which MUST be one of this channel's - <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref>.</p> - - <p>The initially-defined interface that can be used here is - <tp:dbus-ref namespace="ofdT" - >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Server_TLS_Connection.xml b/qt4/spec/Channel_Type_Server_TLS_Connection.xml deleted file mode 100644 index 97efd1b36..000000000 --- a/qt4/spec/Channel_Type_Server_TLS_Connection.xml +++ /dev/null @@ -1,117 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Server_TLS_Connection" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2010 Collabora Limited </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 - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - 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. - - 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. - </tp:license> - - <interface name="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection"> - <tp:added version="0.19.13">(as stable API)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type that carries a TLS certificate between a server - and a client connecting to it.</p> - <p>Channels of this kind always have <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False, - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - = 0, and cannot be requested with methods such as <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. - Also, they SHOULD be dispatched while the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - owning them is in the CONNECTING state.</p> - <p>In this case, handlers SHOULD accept or reject the certificate, using - the relevant methods on the provided object, or MAY just <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall - back to a non-interactive verification process done inside the CM.</p> - <p>For example, channels of this kind can pop up while a client is - connecting to an XMPP server.</p> - </tp:docstring> - - <property name="ServerCertificate" type="o" access="read" - tp:name-for-bindings="Server_Certificate" - tp:immutable='yeah'> - <tp:docstring> - <p>A <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref> - containing the certificate chain as sent by the server, - and other relevant information.</p> - </tp:docstring> - </property> - - <property name="Hostname" type="s" access="read" - tp:name-for-bindings="Hostname" - tp:immutable='sharks'> - <tp:added version="0.19.12"/> - <tp:docstring> - <p>The hostname or domain that the user expects to connect to. Clients - SHOULD use the <tp:member-ref>ReferenceIdentities</tp:member-ref> - property to verify the identity of the certificate. Clients MAY display - this hostname to the user as the expected identity. Clients SHOULD use - this property to lookup pinned certificates or other user preferences - for the connection.</p> - </tp:docstring> - </property> - - <property name="ReferenceIdentities" type="as" access="read" - tp:name-for-bindings="Reference_Identities" - tp:immutable='plz'> - <tp:added version="0.21.10"> - If this property is not present, clients SHOULD use the - <tp:member-ref>Hostname</tp:member-ref> property as the reference - identity to validate server certificates against. - </tp:added> - - <tp:docstring> - <p>The identities of the server we expect - <tp:member-ref>ServerCertificate</tp:member-ref> to certify; clients - SHOULD verify that <tp:member-ref>ServerCertificate</tp:member-ref> - matches one of these identities when checking its validity.</p> - - <p>This property MUST NOT be the empty list; it MUST - contain the value of the <tp:member-ref>Hostname</tp:member-ref> - property. All other identities included in this property MUST be derived from - explicit user input or choices, such as <tp:dbus-ref - namespace='ofdT.Account'>Parameters</tp:dbus-ref> passed to - <tp:dbus-ref - namespace='ofdT.ConnectionManager'>RequestConnection</tp:dbus-ref>.</p> - - <tp:rationale> - <p>The primary use for this property is for XMPP services hosted by - <a href='http://www.google.com/apps/intl/en/business/gmail.html'>Google - Apps</a>. When connecting to Google Talk using an - <tt>@gmail.com</tt> JID, the server correctly presents a - certificate for <tt>gmail.com</tt>; however, for domains hosted via - Google Apps, a certificate for <tt>talk.google.com</tt> is - offered, due to unresolved technical limitations.</p> - - <p>If the user has explicitly chosen to create a <q>Google Talk</q> - account, then trusting a certificate for <tt>talk.google.com</tt> - is reasonable. To handle this case, the connection manager may add - the values of any or all of the <tt>server</tt>, - <tt>fallback-server</tt> and <tt>extra-identities</tt> parameters; - the Google Talk account creation user interface may set these - parameters appropriately, or the user may set them for accounts - with other services.</p> - </tp:rationale> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Stream_Tube.xml b/qt4/spec/Channel_Type_Stream_Tube.xml deleted file mode 100644 index 63e7b2f50..000000000 --- a/qt4/spec/Channel_Type_Stream_Tube.xml +++ /dev/null @@ -1,292 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A stream tube is a transport for ordered, reliable data transfer, - similar to SOCK_STREAM sockets.</p> - - <p>When offering a stream tube, the initiating client creates a local - listening socket and offers it to the recipient client using the - <tp:member-ref>Offer</tp:member-ref> method. When a - recipient accepts a stream tube using the - <tp:member-ref>Accept</tp:member-ref> method, the - recipient's connection manager creates a new local listening socket. - Each time the recipient's client connects to this socket, the - initiator's connection manager proxies this connection to the - originally offered socket.</p> - - </tp:docstring> - - <method name="Offer" tp:name-for-bindings="Offer"> - <tp:docstring> - Offer a stream tube exporting the local socket specified. - </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of the listening address of the local service, as a member of - Socket_Address_Type. - </tp:docstring> - </arg> - <arg direction="in" name="address" type="v"> - <tp:docstring> - The listening address of the local service, as indicated by the - address_type. - </tp:docstring> - </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The access control the local service applies to the local socket, - specified so the connection manager can behave appropriately - when it connects. - </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">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"> - <tp:docstring> - The contact associated with this channel doesn't have tube - capabilities. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support the given address type - or access-control type. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Accept" tp:name-for-bindings="Accept"> - <tp:docstring> - Accept a stream tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref> - signal is emitted. - </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of address the connection manager should listen on. - </tp:docstring> - </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The type of access control the connection manager should apply to - the socket.</p> - - <p>Note that if you plan to establish more than one connection - through the tube, the Socket_Access_Control_Port access control - can't be used as you can't connect more than once from the same - port.</p> - </tp:docstring> - </arg> - <arg direction="in" name="access_control_param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="out" name="address" type="v"> - <tp:docstring> - The address on which the connection manager will listen for - connections to this tube. The client should not attempt to connect - to the address until the tube is open. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The access_control_param is invalid with the given access_control. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given address type or access-control mechanism is not supported. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="NewRemoteConnection" - tp:name-for-bindings="New_Remote_Connection"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted each time a participant opens a new connection to its - socket.</p> - - <p>This signal is only fired on the offering side.</p> - </tp:docstring> - <arg name="Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the participant who opened the new connection - </tp:docstring> - </arg> - <arg name="Connection_Param" type="v"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A parameter which can be used by the listening process to identify - the connection. Note that this parameter has a meaningful value - only in the Socket_Access_Control_Port and - Socket_Access_Control_Credentials cases. If a different - Socket_Access_Control has been chosen when offering the tube, this - parameter should be ignored.</p> - - <p>In the Socket_Access_Control_Port case, the variant - contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) - containing the address from which the CM is connected to the client - application.</p> - - <p>In the Socket_Access_Control_Credentials case, the variant - contains the byte (D-Bus signature 'y') that has been sent with - the credentials.</p> - </tp:docstring> - </arg> - <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> - <tp:docstring> - The unique ID associated with this connection. This ID will be used - to identifiy the connection when reporting errors with - <tp:member-ref>ConnectionClosed</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <signal name="NewLocalConnection" - tp:name-for-bindings="New_Local_Connection"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the tube application connects to the CM's socket.</p> - - <p>This signal is only fired on the accepting side.</p> - </tp:docstring> - <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> - <tp:docstring> - The unique ID associated with this connection. This ID will be used - to identifiy the connection when reporting errors with - <tp:member-ref>ConnectionClosed</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <signal name="ConnectionClosed" - tp:name-for-bindings="Connection_Closed" - tp:type="Stream_Tube_Connection_Closed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a connection has been closed.</p> - </tp:docstring> - <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> - <tp:docstring> - The ID of the connection. - </tp:docstring> - </arg> - <arg name="Error" type="s" tp:type="DBus_Error_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of a D-Bus error describing the error that occurred.</p> - - <p>The following errors can be used:</p> - <ul> - <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>: - user closed the socket or the tube.</li> - <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>: - the bytestream relaying connection's data has been broken.</li> - <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>: - the tube offer refused the connection.</li> - </ul> - </tp:docstring> - </arg> - <arg name="Message" type="s"> - <tp:docstring> - A debug message. - </tp:docstring> - </arg> - </signal> - - <property name="Service" type="s" access="read" - tp:name-for-bindings="Service"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> A string representing the service name that will be used over the - tube. It should be a well-known TCP service name as defined by - <a href="http://www.iana.org/assignments/port-numbers"> - http://www.iana.org/assignments/port-numbers</a> or - <a href="http://www.dns-sd.org/ServiceTypes.html"> - http://www.dns-sd.org/ServiceTypes.html</a>, for instance - "rsync" or "daap".</p> - <p>When the tube is offered, the service name is transmitted to the - other end.</p> - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST be included in the request.</p> - </tp:docstring> - </property> - - <property name="SupportedSocketTypes" type="a{uau}" - tp:type="Supported_Socket_Map" access="read" - tp:name-for-bindings="Supported_Socket_Types"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from address types (members of Socket_Address_Type) to - arrays of access-control type (members of Socket_Access_Control) - that the connection manager supports for stream tubes with that - address type. For simplicity, if a CM supports offering a - particular type of tube, it is assumed to support accepting it.</p> - - <p>A typical value for a host without IPv6 support:</p> - - <pre> - { - Socket_Address_Type_IPv4: - [Socket_Access_Control_Localhost, Socket_Access_Control_Port, - Socket_Access_Control_Netmask], - Socket_Address_Type_Unix: - [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] - } - </pre> - - <p>Connection Managers MUST support at least IPv4 with the localhost - access control.</p> - - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request.</p> - - </tp:docstring> - </property> - - <tp:simple-type name="Stream_Tube_Connection_ID" type="u"> - <tp:docstring>An identifier for a stream tube connection. - These are defined with the - <tp:member-ref>NewLocalConnection</tp:member-ref> or - <tp:member-ref>NewRemoteConnection</tp:member-ref> signals - and are used by <tp:member-ref>ConnectionClosed</tp:member-ref> - to identify the closed connection. - </tp:docstring> - </tp:simple-type> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Streamed_Media.xml b/qt4/spec/Channel_Type_Streamed_Media.xml deleted file mode 100644 index aa2b90345..000000000 --- a/qt4/spec/Channel_Type_Streamed_Media.xml +++ /dev/null @@ -1,853 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> - - <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> - <tp:enumvalue suffix="Video" value="1"> - <tp:docstring>A video stream</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Media_Stream_State" type="u"> - <tp:enumvalue suffix="Disconnected" value="0"> - <tp:docstring>The stream is disconnected.</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Connecting" value="1"> - <tp:docstring>The stream is trying to connect.</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Connected" value="2"> - <tp:docstring>The stream is connected.</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Media_Stream_Direction" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring>Media are not being sent or received</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Send" value="1"> - <tp:docstring>Media are being sent, but not received</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Receive" value="2"> - <tp:docstring>Media are being received, but not sent</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Bidirectional" value="3"> - <tp:docstring>Media are being sent and received</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:flags name="Media_Stream_Pending_Send" value-prefix="Media_Stream_Pending" type="u"> - <tp:flag suffix="Local_Send" value="1"> - <tp:docstring> - The local user has been asked to send media by the remote user. - Call <tp:member-ref>RequestStreamDirection</tp:member-ref> to - indicate whether or not this is acceptable. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Remote_Send" value="2"> - <tp:docstring> - The remote user has been asked to send media by the local user. - The <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal - will be emitted when the remote user accepts or rejects this - change. - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> - <tp:member type="u" tp:type="Stream_ID" name="Identifier"/> - <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> - <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> - <tp:member type="u" tp:type="Media_Stream_State" name="State"/> - <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> - <tp:member type="u" tp:type="Media_Stream_Pending_Send" - name="Pending_Send_Flags"/> - </tp:struct> - - <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[]" - name="Streams"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs containing: - <ul> - <li>the stream identifier</li> - <li>the contact handle who the stream is with (or 0 if the stream - represents more than a single member)</li> - <li>the type of the stream</li> - <li>the current stream state</li> - <li>the current direction of the stream</li> - <li>the current pending send flags</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - Returns an array of structs representing the streams currently active - within this channel. Each stream is identified by an unsigned integer - which is unique for each stream within the channel. - </tp:docstring> - </method> - - <method name="RemoveStreams" tp:name-for-bindings="Remove_Streams"> - <arg direction="in" name="Streams" type="au" tp:type="Stream_ID[]"> - <tp:docstring> - An array of stream identifiers (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - - <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"> - <tp:docstring> - A stream identifier is unknown - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="RequestStreamDirection" - tp:name-for-bindings="Request_Stream_Direction"> - <arg direction="in" name="Stream_ID" type="u"> - <tp:docstring> - The stream identifier (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <arg direction="in" name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> - <tp:docstring> - The desired stream direction (a value of MediaStreamDirection) - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request a change in the direction of an existing stream. In particular, - this might be useful to stop sending media of a particular type, - or inform the peer that you are no longer using media that is being - sent to you.</p> - - <p>Depending on the protocol, streams which are no longer sending in - either direction should be removed and a - <tp:member-ref>StreamRemoved</tp:member-ref> signal emitted. - Some direction changes can be enforced locally (for example, - BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending), - others may not be possible on some protocols, and some need agreement - from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND - flag will be set in the - <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal, and the - signal - emitted again without the flag to indicate the resulting direction when - the remote end has accepted or rejected the change.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - A stream identifier is unknown - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The requested direction is not available on this stream - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="RequestStreams" tp:name-for-bindings="Request_Streams"> - <arg direction="in" name="Contact_Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - A contact handle with whom to establish the streams - </tp:docstring> - </arg> - <arg direction="in" name="Types" type="au" tp:type="Media_Stream_Type[]"> - <tp:docstring> - An array of stream types (values of MediaStreamType) - </tp:docstring> - </arg> - <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" - name="Streams"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs (in the same order as the given stream types) - containing: - <ul> - <li>the stream identifier</li> - <li>the contact handle who the stream is with (or 0 if the stream - represents more than a single member)</li> - <li>the type of the stream</li> - <li>the current stream state</li> - <li>the current direction of the stream</li> - <li>the current pending send flags</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that streams be established to exchange the given types of - media with the given member. In general this will try and establish a - bidirectional stream, but on some protocols it may not be possible to - indicate to the peer that you would like to receive media, so a - send-only stream will be created initially. In the cases where the - stream requires remote agreement (eg you wish to receive media from - them), the <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal - will be emitted with the - 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 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 - a current nor pending member in this channel's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> - interface. If - so, that handle will be added to the remote-pending set only when - an attempt has actually been made to contact them. For further - call-state notification, use the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref> - interface, if - supported. This usage was not allowed in spec versions below - 0.17.2.</p> - </tp:changed> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <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"> - <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> - - <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> - <arg name="Stream_ID" type="u"> - <tp:docstring> - The stream identifier (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <arg name="Contact_Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact handle who the stream is with (or 0 if it - represents more than a single member) - </tp:docstring> - </arg> - <arg name="Stream_Type" type="u" tp:type="Media_Stream_Type"> - <tp:docstring> - The stream type (a value from MediaStreamType) - </tp:docstring> - </arg> - <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> - - <signal name="StreamDirectionChanged" - tp:name-for-bindings="Stream_Direction_Changed"> - <arg name="Stream_ID" type="u"> - <tp:docstring> - The stream identifier (as defined in <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <arg name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> - <tp:docstring> - The new stream direction (as defined in ListStreams) - </tp:docstring> - </arg> - <arg name="Pending_Flags" type="u" tp:type="Media_Stream_Pending_Send"> - <tp:docstring> - The new pending send flags (as defined in ListStreams) - </tp:docstring> - </arg> - <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> - - <signal name="StreamError" tp:name-for-bindings="Stream_Error"> - <arg name="Stream_ID" type="u"> - <tp:docstring> - The stream identifier (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <arg name="Error_Code" type="u" tp:type="Media_Stream_Error"> - <tp:docstring> - A stream error number, one of the values of MediaStreamError - </tp:docstring> - </arg> - <arg name="Message" type="s"> - <tp:docstring> - A string describing the error (for debugging purposes only) - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a stream encounters an error. - </tp:docstring> - </signal> - - <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed"> - <arg name="Stream_ID" type="u"> - <tp:docstring> - stream_id - the stream identifier (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a stream has been removed from this channel. - </tp:docstring> - </signal> - - <signal name="StreamStateChanged" - tp:name-for-bindings="Stream_State_Changed"> - <arg name="Stream_ID" type="u"> - <tp:docstring> - The stream identifier (as defined in - <tp:member-ref>ListStreams</tp:member-ref>) - </tp:docstring> - </arg> - <arg name="Stream_State" type="u" tp:type="Media_Stream_State"> - <tp:docstring> - The new stream state (as defined in ListStreams) - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a member's stream's state changes. - </tp:docstring> - </signal> - - <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If set to true in a channel request that will create a new channel, - the connection manager should immediately attempt to establish an - audio stream to the remote contact, making it unnecessary for the - client to call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p> - - <p>If this property, or InitialVideo, 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> - - <p>If true on a requested channel, this indicates that the audio - stream has already been requested and the client does not need to - call RequestStreams, although it MAY still do so.</p> - - <p>If true on an unrequested (incoming) channel, this indicates that - the remote contact initially requested an audio stream; this does - not imply that that audio stream is still active (as indicated by - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p> - - <p>This property is immutable (cannot change), and therefore SHOULD - appear wherever immutable properties are reported, e.g. <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> - signals.</p> - - <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale> - - <p>Connection managers capable of signalling audio calls to contacts - SHOULD include a channel class in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> - with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref> - = <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = Contact in the fixed properties dictionary, and InitialAudio - (and also InitialVideo, if applicable) in the allowed properties - list. Clients wishing to discover whether a connection manager - can signal audio and/or video calls SHOULD use this information.</p> - - <tp:rationale> - <p>Not all protocols support signalling video calls, and it would be - possible (although unlikely) to have a protocol where only video, - and not audio, could be signalled.</p> - </tp:rationale> - - <p>Connection managers that support the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> - interface SHOULD represent the capabilities of receiving audio - and/or video calls by including a channel class in - a contact's capabilities with ChannelType = StreamedMedia - in the fixed properties dictionary, and InitialAudio and/or - InitialVideo in the allowed properties list. Clients wishing to - discover whether a particular contact is likely to be able to - receive audio and/or video calls SHOULD use this information.</p> - - <tp:rationale> - <p>Not all clients support video calls, and it would also be - possible (although unlikely) to have a client which could only - stream video, not audio.</p> - </tp:rationale> - - <p>Clients that are willing to receive audio and/or video calls - SHOULD include the following among their channel classes if - calling <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> - (clients of a <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">HandlerChannelFilter</tp:dbus-ref> - properties):</p> - - <ul> - <li>{ ChannelType = StreamedMedia }</li> - <li>{ ChannelType = StreamedMedia, InitialAudio = true } - if receiving calls with audio is supported</li> - <li>{ ChannelType = StreamedMedia, InitialVideo = true } - if receiving calls with video is supported</li> - </ul> - - <tp:rationale> - <p>Connection managers for protocols with capability discovery, - like XMPP, need this information to advertise the appropriate - capabilities for their protocol.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialVideo" tp:name-for-bindings="Initial_Video" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for - a video stream. This property is immutable (cannot change).</p> - - <p>In particular, note that if this property is false, this does not - imply that an active video stream has not been added, only that no - video stream was active at the time the channel appeared.</p> - - <p>This property is the correct way to discover whether connection - managers, contacts etc. support video calls; it appears in - capabilities structures in the same way as InitialAudio.</p> - </tp:docstring> - </property> - - <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tt>True</tt>, once streams have been requested for this channel - (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or - <tp:member-ref>InitialVideo</tp:member-ref> when the channel is - requested, or by calling - <tp:member-ref>RequestStreams</tp:member-ref> on a channel with no - streams), a stream of a different content type cannot be added; - subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref> - that attempt to do so will fail.</p> - - <p>If this property is missing, clients SHOULD assume that it is false, - and thus that the channel's streams can be changed once the call has - started.</p> - - <p>If this property is present in the "allowed" set in all of the - StreamedMedia entries in a contact's capabilities, then user - interfaces MAY choose to show a separate "call" option for each - class of call.</p> - - <tp:rationale> - <p>For example, once an audio-only Google Talk call has started, - it is not possible to add a video stream; both audio and video - must be requested at the start of the call if video is desired. - User interfaces may use this pseudo-capability as a hint to - display separate "Audio call" and "Video call" buttons, rather - than a single "Call" button with the option to add and remove - video once the call has started for contacts without this flag. - </p> - </tp:rationale> - - <p>This property is immutable, and therefore SHOULD be announced - in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>, - etc.</p> - </tp:docstring> - </property> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel that can send and receive streamed media such as audio or - video. Provides a number of methods for listing and requesting new - streams, and signals to indicate when streams have been added, removed - and changed status. The state of the call (ringing remotely, ringing - locally, answered, missed, etc.) are represented using the properties - and signals of the Group interface.</p> - - <p>In general this should be used in conjunction with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface to exchange connection candidates and codec choices with - whichever component is responsible for the streams. However, in certain - applications where no candidate exchange is necessary (eg the streams - are handled by specialised hardware which is controlled directly by the - connection manager), the signalling interface can be omitted and this - channel type used simply to control the streams.</p> - - <h4>Outgoing calls</h4> - - <p>To make an audio-only call to a contact <tt>foo@example.com</tt>, - clients should call:</p> - - <blockquote> - <pre> -<tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Contact, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', - <tp:member-ref>InitialAudio</tp:member-ref>: True, -)</pre></blockquote> - - <p>As always, <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - may be used in place of TargetID if the contact's handle is already - known. To make an audio-and-video call, the client should also specify - <tp:member-ref>InitialVideo</tp:member-ref>. The connection manager - SHOULD return a channel whose immutable properties contain the local - user as the <tp:dbus-ref namespace='ofdT.Channel'>InitiatorHandle</tp:dbus-ref>, - the remote contact as the <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, - <tp:dbus-ref namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>True</code> - (indicating that the call is outgoing); the <tp:dbus-ref - namespace='ofdT.Channel.Interface'>Group</tp:dbus-ref> interface should - initially have the local user in <tp:dbus-ref - namespace='ofdT.Channel.Interface.Group'>Members</tp:dbus-ref> and the remote - contact in <tp:dbus-ref - namespace='ofdT.Channel.Interface.Group'>RemotePendingMembers</tp:dbus-ref>, to - indicate that we are awaiting their response.</p> - - <p>The contact answering the call is represented by the CM signalling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, - moving the remote contact to Members, with the remote contact as the - <var>Actor</var> and <var>Reason</var> <code>None</code>. The contact - rejecting the call is represented by both contacts being removed from - the group, with the remote contact as the <var>Actor</var> and - <var>Reason</var> set appropriately. The local user may hang up at any - time by calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> - to remove themself, with an appropriate reason; the CM SHOULD relay the - reason to the remote contact, and emit MembersChanged removing both - contacts from the group with the self handle as the <var>Actor</var>.</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> - - <h4>Incoming calls</h4> - - <p>Incoming calls' immutable properties should contain <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = Contact, both <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">InitiatorHandle</tp:dbus-ref> - set to the remote contact, <tp:dbus-ref - namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>False</code> - (indicating that this is an incoming call), and appropriate values of - <tp:member-ref>InitialAudio</tp:member-ref> and - <tp:member-ref>InitialVideo</tp:member-ref>; the Group interface should - initially have the local user in <tp:dbus-ref - namespace="ofdT.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref> - and the remote contact in <tp:dbus-ref - namespace="ofdT.Channel.Interface.Group">Members</tp:dbus-ref>, - indicating that the contact is awaiting our response.</p> - - <p>To accept the call, use <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> - to move the local user to the group's members. To reject the call, use - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> - to remove the local member from the group, with an appropriate reason. - If the remote user ends the call before it is answered, this is - represented by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> - removing both parties from the group with the remote contact as the - <var>Actor</var>, and <var>Reason</var> set appropriately.</p> - - <p>Note that the call may end with the self handle as the - <var>Actor</var> without the user having chosen to reject the call, as - indicated by the nature of the <var>Reason</var>. Specifically, some - local component may time out the call (indicating this with reason - <code>No_Answer</code>; for example, the CM may have forwarded the call - to another number, as configured using <tp:dbus-ref - namespace='ofdT.Connection.Interface'>Forwarding.DRAFT</tp:dbus-ref>), - or something may have gone wrong with the call - (indicated by reason <code>Error</code>). Such calls SHOULD be - considered missed, just as if the remote contact had hung up before the - local user answered the call.</p> - - <tp:rationale> - <p>This is a bit awkward, but these are the best ways we can represent - these situations. It's important to document which calls should be - considered missed, to ensure that the user can be notified.</p> - </tp:rationale> - - <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> - - <h4>During a call</h4> - - <p>If <tp:member-ref>ImmutableStreams</tp:member-ref> is - <code>False</code>, new streams may be requested using - <tp:member-ref>RequestStreams</tp:member-ref> (to add video to an - audio-only call, for instance), and existing streams may be removed using - <tp:member-ref>RemoveStreams</tp:member-ref> (for example, to downgrade - an audio-video call to audio-only). The call may be ended by calling - <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>; the call ending is signalled by the CM emitting <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, - removing both parties from the group.</p> - - <h4>Handler filters</h4> - - <p>For historical reasons, handlers must specify more than one filter if - they want to correctly advertise support for audio and/or video calls. If - they can handle channels using the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface, they should also advertise various - <tp:type>Handler_Capability_Token</tp:type>s to indicate which codecs and - transports they support. See <tp:member-ref>InitialAudio</tp:member-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling/video/h264</tp:dbus-ref> - for the gory details. In summary:</p> - - <dl> - <dt>To advertise support for streamed media in general, include the - following filter in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>:</dt> - <dd><pre> -{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , - '...Channel.TargetHandleType': Contact, -}</pre></dd> - - <dt>To advertise support for audio calls, also include the following - filter:</dt> - <dd><pre> -{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , - '...Channel.TargetHandleType': Contact, - '...Channel.Type.StreamedMedia.InitialAudio': True, -}</pre></dd> - - <dt>To advertise support for video calls, also include the following - filter:</dt> - <dd><pre> -{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , - '...Channel.TargetHandleType': Contact, - '...Channel.Type.StreamedMedia.InitialVideo': True, -}</pre></dd> - - <dt>If you use telepathy-farsight, and have H.264 support, you probably - want these <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>:</dt> - <dd><pre> -[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp", - "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p", - "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264", -]</pre></dd> - </dl> - </tp:docstring> - - <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u"> - <tp:docstring> - The channel-type-specific capability flags used for - Channel.Type.StreamedMedia in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref> - interface. See the <tp:member-ref>InitialAudio</tp:member-ref> - property for details of the mechanisms that will replace this. - </tp:docstring> - <tp:flag suffix="Audio" value="1"> - <tp:docstring> - The handle is capable of using audio streams within a media channel. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Video" value="2"> - <tp:docstring> - The handle is capable of using video streams within a media channel. - </tp:docstring> - </tp:flag> - <tp:flag suffix="NAT_Traversal_STUN" value="4"> - <tp:docstring> - The handle is capable of performing STUN to traverse NATs. - </tp:docstring> - </tp:flag> - <tp:flag suffix="NAT_Traversal_GTalk_P2P" value="8"> - <tp:docstring> - The handle is capable of establishing Google Talk peer-to-peer - 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:flag suffix="Immutable_Streams" value="32"> - <tp:docstring> - Channels whose target handle is this contact will have - <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>. - </tp:docstring> - </tp:flag> - - </tp:flags> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Text.xml b/qt4/spec/Channel_Type_Text.xml deleted file mode 100644 index 0cd4d5bb2..000000000 --- a/qt4/spec/Channel_Type_Text.xml +++ /dev/null @@ -1,669 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> - <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires - interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> - <tp:changed version="0.21.5">The Messages interface is now - mandatory</tp:changed> - - <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, - message IDs SHOULD NOT be re-used until all of the 32-bit integer - space has already been used). - </tp:docstring> - </tp:simple-type> - - <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> - <tp:deprecated version="0.21.5">New APIs should use - an array of <tp:type>Message_Part</tp:type> instead.</tp:deprecated> - <tp:docstring>A struct (message ID, timestamp in seconds since - 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) - representing a pending text message, as returned by - <tp:member-ref>ListPendingMessages</tp:member-ref>. The arguments of - the <tp:member-ref>Received</tp:member-ref> signal also match this - struct's signature.</tp:docstring> - <tp:member type="u" tp:type="Message_ID" name="Identifier"/> - <tp:member type="u" tp:type="Unix_Timestamp" name="Unix_Timestamp"/> - <tp:member type="u" tp:type="Contact_Handle" name="Sender"/> - <tp:member type="u" tp:type="Channel_Text_Message_Type" - name="Message_Type"/> - <tp:member type="u" tp:type="Channel_Text_Message_Flags" name="Flags"/> - <tp:member type="s" name="Text"/> - </tp:struct> - - <method name="AcknowledgePendingMessages" - tp:name-for-bindings="Acknowledge_Pending_Messages"> - <arg direction="in" name="IDs" type="au" tp:type="Message_ID[]"> - <tp:docstring> - The IDs of the messages to acknowledge - </tp:docstring> - </arg> - <tp:docstring> - Inform the channel that you have handled messages by displaying them to - the user (or equivalent), so they can be removed from the pending queue. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - A given message ID was not found, so no action was taken - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetMessageTypes" tp:name-for-bindings="Get_Message_Types"> - <tp:deprecated version="0.21.5">Consulting - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >MessageTypes</tp:dbus-ref> is preferred. - </tp:deprecated> - <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]" - name="Available_Types"> - <tp:docstring> - An array of integer message types (ChannelTextMessageType) - </tp:docstring> - </arg> - <tp:docstring> - Return an array indicating which types of message may be sent on this - channel. - </tp:docstring> - </method> - - <method name="ListPendingMessages" - tp:name-for-bindings="List_Pending_Messages"> - <tp:deprecated version="0.21.5">Consulting - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >PendingMessages</tp:dbus-ref> is preferred. - </tp:deprecated> - <arg direction="in" name="Clear" type="b"> - <tp:docstring> - If true, behave as if - <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also - been called. - </tp:docstring> - <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 - impossible if this flag is true.</tp:deprecated> - </arg> - <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]" - name="Pending_Messages"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs representing the pending queue. Each contains: - <ul> - <li>a numeric identifier</li> - <li>a Unix timestamp indicating when the message was received</li> - <li>the contact handle for the contact who sent the message</li> - <li>the message type, taken from ChannelTextMessageType</li> - <li>the bitwise-OR of the message flags from ChannelTextMessageFlags</li> - <li>the text of the message</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - List the messages currently in the pending queue, and optionally - remove then all. - </tp:docstring> - </method> - - <signal name="LostMessage" tp:name-for-bindings="Lost_Message"> - <tp:deprecated version="0.21.5">In practice, this signal - was not emitted, and does not have useful semantics.</tp:deprecated> - <tp:docstring> - This signal is emitted to indicate that an incoming message was - not able to be stored and forwarded by the connection manager - due to lack of memory. - </tp:docstring> - </signal> - - <signal name="Received" tp:name-for-bindings="Received"> - <tp:deprecated version="0.21.5">The - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >MessageReceived</tp:dbus-ref> signal is more informative. - </tp:deprecated> - <arg name="ID" type="u"> - <tp:docstring> - A numeric identifier for acknowledging the message - </tp:docstring> - </arg> - <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - A Unix timestamp indicating when the message was received - </tp:docstring> - </arg> - <arg name="Sender" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the contact who sent the message - </tp:docstring> - </arg> - <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> - <tp:docstring> - The type of the message (normal, action, notice, etc.) - </tp:docstring> - </arg> - <arg name="Flags" type="u" tp:type="Channel_Text_Message_Flags"> - <tp:docstring> - A bitwise OR of the message flags - </tp:docstring> - </arg> - <arg name="Text" type="s"> - <tp:docstring> - The text of the message - </tp:docstring> - </arg> - <tp:docstring> - Signals that a message with the given id, timestamp, sender, type - and text has been received on this channel. Applications that catch - this signal and reliably inform the user of the message should - acknowledge that they have dealt with the message with the - <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method. - </tp:docstring> - </signal> - - <method name="Send" tp:name-for-bindings="Send"> - <tp:deprecated version="0.21.5">The - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >SendMessage</tp:dbus-ref> method is more flexible. - </tp:deprecated> - <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type"> - <tp:docstring> - An integer indicating the type of the message - </tp:docstring> - </arg> - <arg direction="in" name="Text" type="s"> - <tp:docstring> - The message to send - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that a message be sent on this channel. When the message has - been submitted for delivery, this method will return and the - <tp:member-ref>Sent</tp:member-ref> signal will be emitted. If the - message cannot be submitted for delivery, the method returns an error - and no signal is emitted.</p> - - <p>This method SHOULD return before the Sent signal is - emitted.</p> - - <tp:rationale> - <p>When a Text channel implements the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> - interface, that "SHOULD" becomes a "MUST".</p> - </tp:rationale> - </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.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <tp:enum name="Channel_Text_Send_Error" type="u"> - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - An unknown error occurred - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Offline" value="1"> - <tp:docstring> - The requested contact was offline - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invalid_Contact" value="2"> - <tp:docstring> - The requested contact is not valid - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Permission_Denied" value="3"> - <tp:docstring> - The user does not have permission to speak on this channel - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Too_Long" value="4"> - <tp:docstring> - The outgoing message was too long and was rejected by the server - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Not_Implemented" value="5"> - <tp:docstring> - The channel doesn't support sending text messages to the requested - contact - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="SendError" tp:name-for-bindings="Send_Error"> - <tp:deprecated version="0.21.5">Delivery reporting is now - provided by the <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Messages</tp:dbus-ref> interface. - </tp:deprecated> - <arg name="Error" type="u" tp:type="Channel_Text_Send_Error"> - <tp:docstring> - The error that occurred - </tp:docstring> - </arg> - <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - The Unix timestamp indicating when the message was sent - </tp:docstring> - </arg> - <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> - <tp:docstring> - The message type - </tp:docstring> - </arg> - <arg name="Text" type="s"> - <tp:docstring> - The text of the message - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Signals that an outgoing message has failed to send. The error - will be one of the values from ChannelTextSendError.</p> - - <p>This signal should only be emitted for messages for which - <tp:member-ref>Sent</tp:member-ref> has already been emitted and - <tp:member-ref>Send</tp:member-ref> has already returned success.</p> - </tp:docstring> - <tp:changed version="0.17.3">older spec versions claimed that SendError - was emitted <em>instead of</em> Sent, rather than <em>in addition - to</em> Sent. However, the 0.17.3+ semantics were what we'd always - actually implemented.</tp:changed> - </signal> - - <signal name="Sent" tp:name-for-bindings="Sent"> - <tp:deprecated version="0.21.5">The - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >MessageSent</tp:dbus-ref> signal is more informative. - </tp:deprecated> - <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - Unix timestamp indicating when the message was sent - </tp:docstring> - </arg> - <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> - <tp:docstring> - The message type (normal, action, notice, etc) from - ChannelTextMessageType - </tp:docstring> - </arg> - <arg name="Text" type="s"> - <tp:docstring> - The text of the message. If the message was, or will be, altered - during transmission, this argument SHOULD reflect what other - contacts will receive rather than being a copy of the argument - to <tp:member-ref>Send</tp:member-ref>. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Signals that a message has been submitted for sending.</p> - </tp:docstring> - </signal> - - <tp:enum name="Channel_Text_Message_Type" type="u" - array-name="Channel_Text_Message_Type_List"> - <tp:docstring> - The type of message. - </tp:docstring> - - <tp:enumvalue suffix="Normal" value="0"> - <tp:docstring> - An ordinary chat message. Unknown types SHOULD be treated like this. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Action" value="1"> - <tp:docstring> - An action which might be presented to the user as - "* <sender> <action>", such as an IRC CTCP - ACTION (typically selected by the "/me" command). For example, the - text of the message might be "drinks more coffee". - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Notice" value="2"> - <tp:docstring> - A one-off or automated message not necessarily expecting a reply - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Auto_Reply" value="3"> - <tp:docstring> - An automatically-generated reply message. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Delivery_Report" value="4"> - <tp:docstring> - A delivery report. This message type MUST NOT appear unless the - channel supports the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> - interface; see <tp:type>Message_Part</tp:type> for the format that - delivery reports must take. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u"> - <tp:deprecated version="0.21.5">The - <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Messages</tp:dbus-ref> interface has an extensible data structure - including separate booleans for most of these flags. - </tp:deprecated> - <tp:flag suffix="Truncated" value="1"> - <tp:docstring> - The incoming message was truncated to a shorter length by the - server or the connection manager. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Non_Text_Content" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The incoming message contained non-text content which cannot be - represented by this interface, but has been signalled - in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> - interface.</p> - - <p>Connection managers SHOULD only set this flag if the non-text - content appears to be relatively significant (exactly how - significant is up to the implementor). The intention is that - if this flag is set, clients using this interface SHOULD inform - the user that part of the message was not understood.</p> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Scrollback" value="4"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The incoming message was part of a replay of message history.</p> - - <tp:rationale> - <p>In XMPP multi-user chat, a few past messages are replayed - when you join a chatroom. A sufficiently capable IRC connection - manager could also set this flag on historical messages when - connected to a proxy like bip or irssi-proxy. The existence - of this flag allows loggers and UIs to use better heuristics - when eliminating duplicates (a simple implementation made - possible by this flag would be to avoid logging scrollback - at all).</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Rescued" value="8"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The incoming message has been seen in a previous channel during - the lifetime of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, but - had not been acknowledged - when that channel closed, causing an identical channel (the - channel in which the message now appears) to open.</p> - - <tp:rationale> - <p>This means that a logger (which should already have seen the - message in the previous channel) is able to recognise and ignore - these replayed messages.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:property name="anonymous" type="b"> - <tp:docstring> - True if people may join the channel without other members being made - aware of their identity. - </tp:docstring> - </tp:property> - <tp:property name="invite-only" type="b"> - <tp:docstring> - True if people may not join the channel until they have been invited. - </tp:docstring> - </tp:property> - <tp:property name="limit" type="u"> - <tp:docstring> - The limit to the number of members, if limited is true. - </tp:docstring> - </tp:property> - <tp:property name="limited" type="b"> - <tp:docstring> - True if there is a limit to the number of channel members. - </tp:docstring> - </tp:property> - <tp:property name="moderated" type="b"> - <tp:docstring> - True if channel membership is not sufficient to allow participation. - </tp:docstring> - </tp:property> - <tp:property name="name" type="s"> - <tp:docstring> - A human-visible name for the channel, if it differs from the channel's - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>. - </tp:docstring> - </tp:property> - <tp:property name="description" type="s"> - <tp:docstring> - A human-readable description of the channel's overall purpose. - </tp:docstring> - </tp:property> - <tp:property name="password" type="s"> - <tp:docstring> - The password required to enter the channel if password-required is true. - </tp:docstring> - </tp:property> - <tp:property name="password-required" type="b"> - <tp:docstring> - True if a password must be provided to enter the channel. - </tp:docstring> - </tp:property> - <tp:property name="persistent" type="b"> - <tp:docstring> - True if the channel will remain in existence on the server after all - members have left it. - </tp:docstring> - </tp:property> - <tp:property name="private" type="b"> - <tp:docstring> - True if the channel is not visible to non-members. - </tp:docstring> - </tp:property> - <tp:property name="subject" type="s"> - <tp:docstring> - A human-readable description of the current subject of conversation in - the channel, similar to /topic in IRC. This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - <tp:property name="subject-contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - A contact handle representing who last modified the subject, or 0 - if it isn't known. This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - A unix timestamp indicating when the subject was last modified. - This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for sending and receiving messages. This channel type - is primarily used for textual messages, but can also be used for - formatted text, text with "attachments", or binary messages on some - protocols.</p> - - <p>Most of the methods and signals on this interface are deprecated, - since they only support plain-text messages with limited metadata. - See the mandatory <tp:dbus-ref - namespace="ofdT.Channel.Interface">Messages</tp:dbus-ref> - interface for the modern equivalents.</p> - - <p>When a message is received, an identifier is assigned and a - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >MessageReceived</tp:dbus-ref> signal emitted, and the message - is placed in a pending queue represented by the - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >PendingMessages</tp:dbus-ref> property. - When the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> - for a channel has handled the message by showing it to the user - (or equivalent), it should acknowledge the receipt of that message - using the <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> - method, and the message will then be removed from the pending queue. - Numeric identifiers for received messages may be reused over the - lifetime of the channel.</p> - - <p>Sending messages can be requested using the - <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" - >SendMessage</tp:dbus-ref> method, which will return - successfully when the message has been submitted for sending, or - return an error with no signal emission if there is an immediate - failure. If a message is submitted for sending but delivery of the - message later fails, this is indicated by a delivery report, which - is received in the same way as an incoming message.</p> - - <p>Simple one-to-one chats (such as streams of private messages in - XMPP or IRC) should be represented by a Text channel whose - <tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> - is <tp:type>Handle_Type</tp:type>_Contact. The expected way to - request such a channel is to set the ChannelType, TargetHandleType, - and either TargetHandle or TargetID in a call to EnsureChannel.</p> - - <p>Named chat rooms whose identity can be saved and used again later - (IRC channels, Jabber MUCs) are expected to be represented by Text - channels with <tp:type>Handle_Type</tp:type>_Room and the <tp:dbus-ref - namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> - interface. In protocols where a chatroom can be used as a continuation - of one or more one-to-one chats, these channels should also have the - <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> - interface.</p> - - <p>Unnamed, transient chat rooms which cannot be rejoined by their - unique identifier (e.g. a conversation on MSN which has, or once had, - three or more participants) are expected to be represented by Text - channels with Handle_Type_None (and hence TargetHandle 0), the - <tp:dbus-ref namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> - interface, and optionally the - <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> - interface.</p> - - <p>On protocols like MSN where a conversation with a user is actually - just a nameless chat room starting with exactly two members, to which - more members can be invited, the initial one-to-one conversation - SHOULD be represented with Handle_Type_Contact. If a third participant - joins or is invited, this SHOULD be represented by signalling - a new <tp:dbus-ref - namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> channel - with the one-to-one channel in its <tp:dbus-ref - namespace="ofdT.Channel.Interface.Conference" - >InitialChannels</tp:dbus-ref>, migrating the underlying protocol - object from the one-to-one channel to the Conference channel, - and creating a new protocol-level conversation if the one-to-one - channel is re-used. See the Conference interface for more details.</p> - - <tp:rationale> - <p>This keeps the presentation of all one-to-one conversations - uniform, and makes it easier to hand over a conversation from a - 1-1-specific UI to a more elaborate multi-user UI; while it does - require UIs to understand Conference to follow the - upgrade, UIs that will deal with XMPP need to understand Conference - anyway.</p> - </tp:rationale> - - <p>If a channel of type Text is closed while it has pending messages, - the connection manager MUST allow this, but SHOULD open a new channel - to deliver those messages, signalling it as a new channel with the - <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> - signal. The new channel should resemble the old channel, but have - Requested = FALSE regardless of its previous value; the InitiatorHandle - and InitiatorID should correspond to the sender of one of the pending - messages.</p> - - <tp:rationale> - <p>In effect, this turns this situation, in which a client - is likely to lose messages:</p> - - <ul> - <li>UI window is closed</li> - <li>message arrives</li> - <li>text channel emits Received</li> - <li>UI calls Close on text channel before it has seen the - Received signal</li> - <li>text channel emits Closed and closes</li> - </ul> - - <p>into something nearly equivalent to this situation, which is - fine:</p> - - <ul> - <li>UI window is closed</li> - <li>UI calls Close on text channel</li> - <li>text channel emits Closed and closes</li> - <li>message arrives</li> - <li>new text channel is created, connection emits NewChannels</li> - <li>(the same or a different) UI handles it</li> - </ul> - - <p>Requested must be set to FALSE so the replacement channel - will be handled by something.</p> - - <p>In practice, connection managers usually implement this by keeping - the same internal object that represented the old channel, adjusting - its properties, signalling that it was closed, then immediately - re-signalling it as a new channel.</p> - </tp:rationale> - - <p>As a result, Text channels SHOULD implement <tp:dbus-ref - namespace="ofdT">Channel.Interface.Destroyable</tp:dbus-ref>.</p> - - <tp:rationale> - <p>This "respawning" behaviour becomes problematic if there is no - suitable handler for Text channels, or if a particular message - repeatedly crashes the Text channel handler; a channel dispatcher - can't just Close() the channel in these situations, because - it will come back.</p> - - <p>In these situations, the channel dispatcher needs a last-resort - way to destroy the channel and stop it respawning. It could either - acknowledge the messages itself, or use the Destroyable interface; - the Destroyable interface has the advantage that it's not - channel-type-dependent, so the channel dispatcher only has to - understand one extra interface, however many channel types - eventually need a distinction between Close and Destroy.</p> - </tp:rationale> - - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Tubes.xml b/qt4/spec/Channel_Type_Tubes.xml deleted file mode 100644 index c0a973faa..000000000 --- a/qt4/spec/Channel_Type_Tubes.xml +++ /dev/null @@ -1,615 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> - Copyright © 2007-2009 Collabora Limited - </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 -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -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. - -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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes"> - - <tp:deprecated version="0.17.25">Client implementations - SHOULD use <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref> - instead.</tp:deprecated> - - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A "tube" is a mechanism for arbitrary data transfer. Two types of - data transfer are currently specified: D-Bus messages, and streams of - bytes. Each tube has a service name, which is a string specifying the - kind of communication that takes place over it, and a dictionary of - arbitrary parameters. Tube parameters are commonly used for bootstrap - information such as usernames and passwords. Each tube is identified - by a locally unique identifier.</p> - - <p>The Tubes channel type may be requested for handles of type - HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p> - - <p>Stream tubes specify listening addresses using pairs of parameters - with signature 'u', 'v', where the integer 'u' is a member of - Socket_Address_Type and the v is dependent on the type of address.</p> - </tp:docstring> - - <tp:simple-type name="Tube_ID" type="u"> - <tp:docstring>An identifier for a tube. These are local to a Tubes - channel, and may not be assumed to be the same as the other - participants' idea of the tube identifier.</tp:docstring> - </tp:simple-type> - - <tp:struct name="Tube_Info" array-name="Tube_Info_List"> - <tp:docstring>A struct (tube ID, initiator handle, tube type, - service name, parameters, state) representing a tube, as returned - by ListTubes on the Tubes channel type.</tp:docstring> - <tp:member type="u" tp:type="Tube_ID" name="Identifier"/> - <tp:member type="u" tp:type="Contact_Handle" name="Initiator"/> - <tp:member type="u" tp:type="Tube_Type" name="Type"/> - <tp:member type="s" name="Service"/> - <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> - <tp:member type="u" tp:type="Tube_State" name="State"/> - </tp:struct> - - <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List"> - <tp:docstring>Represents a participant in a multi-user D-Bus tube, as - returned by <tp:member-ref>GetDBusNames</tp:member-ref> and seen in the - <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"> - <tp:docstring> - The handle of a participant in this D-Bus tube. - </tp:docstring> - </tp:member> - <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> - <tp:docstring> - That participant's unique name. - </tp:docstring> - </tp:member> - </tp:struct> - - <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 - org.freedesktop.Telepathy.Channel.Type.DBusTube interface.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Stream" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The tube is stream tube as described by the - org.freedesktop.Telepathy.Channel.Type.StreamTube interface.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Tube_State" type="u"> - <tp:enumvalue suffix="Local_Pending" value="0"> - <tp:docstring> - The tube is waiting to be accepted/closed locally. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Pending" value="1"> - <tp:docstring> - The tube is waiting to be accepted/closed remotely. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="2"> - <tp:docstring> - The tube is open for traffic. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:mapping name="Supported_Socket_Map"> - <tp:docstring>The supported socket address and access-control types - for tubes. See GetAvailableStreamTubeTypes.</tp:docstring> - <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/> - <tp:member name="Access_Control" type="au" - tp:type="Socket_Access_Control[]"/> - </tp:mapping> - - <method name="GetAvailableStreamTubeTypes" - tp:name-for-bindings="Get_Available_Stream_Tube_Types"> - <tp:docstring>List the available address types and access-control types - for stream tubes.</tp:docstring> - <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map" - name="Available_Stream_Tube_Types"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from address types (members of Socket_Address_Type) to - arrays of access-control type (members of Socket_Access_Control) - that the connection manager supports for stream tubes with that - address type. For simplicity, if a CM supports offering a - particular type of tube, it is assumed to support accepting it.</p> - - <p>A typical value for a host without IPv6 support:</p> - - <pre> - { - Socket_Address_Type_IPv4: - [Socket_Access_Control_Localhost, Socket_Access_Control_Port, - Socket_Access_Control_Netmask], - Socket_Address_Type_Unix: - [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] - } - </pre> - - <p>If stream tubes are not supported, this will be an empty - dictionary.</p> - </tp:docstring> - </arg> - </method> - - <method name="GetAvailableTubeTypes" - tp:name-for-bindings="Get_Available_Tube_Types"> - <arg direction="out" type="au" tp:type="Tube_Type[]" - name="Available_Tube_Types"> - <tp:docstring> - An array of the available tube types, as defined by the Tube_Type - enum. - </tp:docstring> - </arg> - </method> - - <method name="ListTubes" tp:name-for-bindings="List_Tubes"> - <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]" - name="Tubes"> - <tp:docstring> - Return an array of tuples, each representing a tube, with the - following members: - - <ul> - <li>the tube's ID</li> - <li>the tube's initiator</li> - <li>the tube's type</li> - <li>the tube's service</li> - <li>the tube's parameters</li> - <li>the tube's state</li> - </ul> - </tp:docstring> - </arg> - </method> - - <!-- this tp:name-for-bindings is ugly, but compatible with - the code generation in telepathy-glib versions that did not use - tp:name-for-bindings --> - <method name="OfferDBusTube" tp:name-for-bindings="Offer_D_Bus_Tube"> - <tp:docstring> - Offers a D-Bus tube providing the service specified. - </tp:docstring> - <arg direction="in" name="Service" type="s"> - <tp:docstring> - A string representing the service name that will be used over the - tube. - It should be a well-known D-Bus service name, of the form - com.example.ServiceName. - </tp:docstring> - </arg> - <arg direction="in" name="Parameters" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring> - A dictionary of properties for the new tube; the allowable keys, - types and values are defined by the service. Connection managers - must support the value being any primitive (non-container) - D-Bus type, or a byte array 'ay'. - </tp:docstring> - </arg> - <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> - <tp:docstring> - The ID of the new tube. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact associated with this channel doesn't have tubes - capabilities. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support D-Bus tubes. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube"> - <tp:docstring> - Offer a stream tube exporting the local socket specified. - </tp:docstring> - <arg direction="in" name="Service" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A string representing the service name that will be used over the - tube. - It should be a well-known TCP service name as defined by - <a href="http://www.iana.org/assignments/port-numbers"> - http://www.iana.org/assignments/port-numbers</a> or - <a href="http://www.dns-sd.org/ServiceTypes.html"> - http://www.dns-sd.org/ServiceTypes.html</a>, for instance - "rsync" or "daap". - </tp:docstring> - </arg> - <arg direction="in" name="Parameters" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary of properties for the new tube; the allowable keys, - types and values are defined by the service. Connection managers - must support the value being any primitive (non-container) - D-Bus type, or a byte array 'ay'.</p> - <p>These should usually be the same key-value pairs specified for - use in the DNS-SD TXT record for that service.</p> - </tp:docstring> - </arg> - <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of the listening address of the local service, as a member of - Socket_Address_Type. - </tp:docstring> - </arg> - <arg direction="in" name="Address" type="v"> - <tp:docstring> - The listening address of the local service, as indicated by the - address_type. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The access control the local service applies to the local socket, - specified so the connection manager can behave appropriately - when it connects. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control_Param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> - <tp:docstring> - The ID of the new tube. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact associated with this channel doesn't have tube - capabilities. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support stream tubes, or - does not support the given address type or access-control type. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="NewTube" tp:name-for-bindings="New_Tube"> - <tp:docstring> - Emitted when a tube is created. - </tp:docstring> - <arg name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the new tube. - </tp:docstring> - </arg> - <arg name="Initiator" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the contact who initiated the tube. - </tp:docstring> - </arg> - <arg name="Type" type="u" tp:type="Tube_Type"> - <tp:docstring> - The tube type, as defined by the Tube_Type enum. - </tp:docstring> - </arg> - <arg name="Service" type="s"> - <tp:docstring> - A string representing the service that will be used over the tube. - </tp:docstring> - </arg> - <arg name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring> - The new tube's properties. - </tp:docstring> - </arg> - <arg name="State" type="u" tp:type="Tube_State"> - <tp:docstring> - The new tube's state. - </tp:docstring> - </arg> - </signal> - - <!-- this tp:name-for-bindings is ugly, but compatible with - the code generation in telepathy-glib versions that did not use - tp:name-for-bindings --> - <method name="AcceptDBusTube" tp:name-for-bindings="Accept_D_Bus_Tube"> - <tp:docstring> - Accept a D-Bus tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the TubeStateChanged signal is - emitted. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube to accept. - </tp:docstring> - </arg> - <arg direction="out" name="Address" type="s"> - <tp:docstring> - The string describing the address of the private bus. The client - should not attempt to connect to the address until the tube is open. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given tube ID is invalid or does not refer to a D-Bus - tube. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube"> - <tp:docstring> - Accept a stream tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the TubeStateChanged signal is - emitted. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube to accept. - </tp:docstring> - </arg> - <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of address the connection manager should listen on. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The type of access control the connection manager should apply to - the socket. - </tp:docstring> - </arg> - <arg direction="in" name="Access_Control_Param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="out" name="Address" type="v"> - <tp:docstring> - The address on which the connection manager will listen for - connections to this tube. The client should not attempt to connect - to the address until the tube is open. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given tube ID is invalid or does not refer to a stream - tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given address type or access-control mechanism is not supported. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="TubeStateChanged" tp:name-for-bindings="Tube_State_Changed"> - <tp:docstring> - Emitted when the state of a tube changes. - </tp:docstring> - <arg name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube that changed state. - </tp:docstring> - </arg> - <arg name="State" type="u" tp:type="Tube_State"> - <tp:docstring> - The new state of the tube; see the Tube_State enumeration. - </tp:docstring> - </arg> - </signal> - - <method name="CloseTube" tp:name-for-bindings="Close_Tube"> - <tp:docstring> - Close a tube. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube to close. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" /> - </tp:possible-errors> - </method> - - <signal name="TubeClosed" tp:name-for-bindings="Tube_Closed"> - <tp:docstring> - Emitted when a tube has been closed. The ID of a closed tube is no - longer valid. The ID may later be reused for a new tube. - </tp:docstring> - <arg name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube that was closed. - </tp:docstring> - </arg> - </signal> - - <!-- this tp:name-for-bindings is ugly, but compatible with - the code generation in telepathy-glib versions that did not use - tp:name-for-bindings --> - <method name="GetDBusTubeAddress" - tp:name-for-bindings="Get_D_Bus_Tube_Address"> - <tp:docstring> - For a D-Bus tube, return a string describing the address of the - private bus. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube to get an address for. - </tp:docstring> - </arg> - <arg direction="out" type="s" name="Address"> - <tp:docstring> - The bus address. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <!-- this tp:name-for-bindings is ugly, but compatible with - the code generation in telepathy-glib versions that did not use - tp:name-for-bindings --> - <method name="GetDBusNames" tp:name-for-bindings="Get_D_Bus_Names"> - <tp:docstring> - For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping - between contact handles and their unique bus names on this tube. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube to get names for. - </tp:docstring> - </arg> - <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]" - name="DBus_Names"> - <tp:docstring> - An array of structures, each containing a contact handle and a D-Bus - bus name. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a multi-user D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <!-- this tp:name-for-bindings is ugly, but compatible with - the code generation in telepathy-glib versions that did not use - tp:name-for-bindings --> - <signal name="DBusNamesChanged" tp:name-for-bindings="D_Bus_Names_Changed"> - <tp:docstring> - Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a - participant opens or closes the tube. - </tp:docstring> - <arg name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube whose names have changed. - </tp:docstring> - </arg> - <arg name="Added" type="a(us)" tp:type="DBus_Tube_Member[]"> - <tp:docstring> - Array of handles and D-Bus names of new participants. - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - Array of handles of former participants. - </tp:docstring> - </arg> - </signal> - - <method name="GetStreamTubeSocketAddress" - tp:name-for-bindings="Get_Stream_Tube_Socket_Address"> - <tp:docstring> - For a stream tube, obtain the address of the socket used to - communicate over this tube. - </tp:docstring> - <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the stream tube to get the socket for. - </tp:docstring> - </arg> - <arg direction="out" name="Address_Type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of the listening address of the socket, as a member of - Socket_Address_Type. - </tp:docstring> - </arg> - <arg direction="out" name="Address" type="v"> - <tp:docstring> - The listening address of the socket, as indicated by the - address_type. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a stream tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="StreamTubeNewConnection" - tp:name-for-bindings="Stream_Tube_New_Connection"> - <tp:docstring> - Emitted on a stream tube when a participant opens a new connection - to its socket. - </tp:docstring> - <arg name="ID" type="u" tp:type="Tube_ID"> - <tp:docstring> - The ID of the tube - </tp:docstring> - </arg> - <arg name="Handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the participant who opened the new connection - </tp:docstring> - </arg> - </signal> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client.xml b/qt4/spec/Client.xml deleted file mode 100644 index 19f691495..000000000 --- a/qt4/spec/Client.xml +++ /dev/null @@ -1,122 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client" - 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"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Telepathy clients use connection managers, the channel dispatcher - and optionally the account manager to provide useful - functionality.</p> - - <p>User interface processes are the obvious example of Telepathy - clients, but they can provide other functionality, such as - address-book synchronization.</p> - - <p>Every running or activatable process with a well-known - name of the form org.freedesktop.Telepathy.Client.<em>clientname</em> - should be probed by the channel dispatcher to discover its - capabilities. Each client is either an <em>observer</em>, an - <em>approver</em>, a <em>channel handler</em>, or some combination - of these.</p> - - <tp:rationale> - <p>Activatable services (those with a D-Bus <code>.service</code> - file) must be supported so that we can run clients - in response to channel creation.</p> - - <p>Non-activatable services (those that do not register a D-Bus - <code>.service</code> file for their well-known name, but do - request it at runtime) must be supported so that we can have - programs that process channels, but only if they are already - running - for instance, a full-screen media centre - application might do this.</p> - </tp:rationale> - - <p>The client name, <em>clientname</em>, MUST be a non-empty string of - ASCII digits, letters, dots and/or underscores, starting with a - letter, and without sets of two consecutive dots or a dot - followed by a digit. For non-activatable services, it MAY contain a - part that is generated per instance at runtime.</p> - - <tp:rationale> - <p>If each of a client Foo's instances should be able to manipulate - channels separately, the instance with unique name - <code>:1.25</code> might request a well-known name like - <code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p> - - <p>(Note that well-known bus-name components may not start with a - digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p> - </tp:rationale> - - <p>Each Client MUST export an object whose object path may be - determined by replacing '.' with '/' in the well-known name and - prepending '/'. This object represents its API as a Telepathy - client; the channel dispatcher will call its methods and read - its properties when appropriate.</p> - - <p>As an optimization, activatable clients SHOULD install a file - <code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code> - containing a cached version of its immutable properties, - so that for most clients, the channel dispatcher can - just read a file to discover capabilities, instead of - having to service-activate the client immediately in order to fetch - its read-only properties. However, the D-Bus API is canonical, and - the channel dispatcher MUST support clients without such a file.</p> - - <p>Non-activatable clients MAY install a <code>.client</code> file, - but there's not much point in them doing so.</p> - - <p>The .client files MUST contain UTF-8 text with the same syntax - as - <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry files</a> (although the allowed groups, keys and values differ). - Every <code>.client</code> file MUST contain a group whose name is - the name of this interface.</p> - - <p>The groups, keys and values in the <code>.client</code> file are - defined by individual interfaces. Each interface that can usefully - cache information in the <code>.client</code> file SHOULD correspond - to a group with the same name.</p> - </tp:docstring> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" access="read" tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the extra interfaces provided by this client. - This SHOULD include at least one of - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p> - - <p>In the <code>.client</code> file, this is represented by key - "<code>Interfaces</code>" in the group named after this interface. - The value of the key is a list of interface names each followed by - a semicolon (so it always ends with a semicolon unless it is empty), - i.e. a key of type "strings" as described in the Desktop Entry - specification.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Approver.xml b/qt4/spec/Client_Approver.xml deleted file mode 100644 index 12cbc76ac..000000000 --- a/qt4/spec/Client_Approver.xml +++ /dev/null @@ -1,201 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Approver" - 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.Approver"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Client"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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. - However, the Channel Dispatcher must be able to prioritize - possible handlers on its own using some reasonable heuristic, - probably based on user configuration.</p> - - <p>It is possible (and useful) to have an approver and - a channel handler in the same process; this is particularly useful - if a channel handler wants to claim responsibility for particular - channels itself.</p> - - <p>All approvers are notified simultaneously. For instance, in a - desktop system, there might be one approver that displays a - notification-area icon, one that is part of a contact list - 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 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 - straight away.</p> - - <p>Non-interactive approvers can also be implemented as - <tp:dbus-ref namespace="ofdT.Client">Observer</tp:dbus-ref>s as - described in the interface description.</p> - </tp:docstring> - - <property name="ApproverChannelFilter" - tp:name-for-bindings="Approver_Channel_Filter" - type="aa{sv}" access="read" tp:type="Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specification of the channels in which this approver is - interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> - 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.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> - </tp:docstring> - </property> - - <method name="AddDispatchOperation" - tp:name-for-bindings="Add_Dispatch_Operation"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when a ChannelDispatchOperation - in which the approver has registered an interest is created, - or when the approver starts up while such channel dispatch - operations already exist.</p> - - <p>The channel dispatcher SHOULD call this method on all approvers - 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 (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 - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> - to be processed.</p> - </tp:docstring> - </arg> - - <arg name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map" direction="in"> - <tp:docstring> - <p>Properties of the channel dispatch operation. The keys MUST be - fully qualified D-Bus property names. 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> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Handler.xml b/qt4/spec/Client_Handler.xml deleted file mode 100644 index 3a922e8cc..000000000 --- a/qt4/spec/Client_Handler.xml +++ /dev/null @@ -1,337 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Handler" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - - <interface name="org.freedesktop.Telepathy.Client.Handler"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Client"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Handlers are the user interface for a channel. They turn an abstract - Telepathy channel into something the user wants to see, like a text - message stream or an audio and/or video call.</p> - - <p>For its entire lifetime, each channel on a connection known to the - channel dispatcher is either being processed by the channel dispatcher, - or being handled by precisely one Handler.</p> - - <p>Because each channel is only handled by one Handler, handlers may - perform actions that only make sense to do once, such as acknowledging - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - messages, doing the actual streaming for <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - channels with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface, or transferring the file in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">FileTransfer</tp:dbus-ref> - channels.</p> - - <p>When a new incoming channel (one with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> - = FALSE) is offered to - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s - by the channel dispatcher, it also offers the Approvers a list of all - the running or activatable handlers whose - <tp:member-ref>HandlerChannelFilter</tp:member-ref> property - (possibly as cached in the .client file) indicates that they - are able to handle the channel. The Approvers can choose one of - those channel handlers to handle the channel.</p> - - <p>When a new outgoing channel (one with - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> - = TRUE) appears, the channel dispatcher passes it to an appropriate - channel handler automatically. - </p> - - </tp:docstring> - - <property name="HandlerChannelFilter" - tp:name-for-bindings="Handler_Channel_Filter" - type="aa{sv}" access="read" tp:type="Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specification of the channels that this channel handler can - deal with. It will be offered to approvers as a potential - channel handler for bundles that contain only suitable channels, - or for suitable channels that must be handled separately.</p> - - <p>This property works in exactly the same way as the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> - property. In particular, it cannot change while the handler process - continues to own the corresponding Client bus name.</p> - - <p>In the .client file, it is represented in the - same way as ObserverChannelFilter, but the group has the same - name as this interface and the keys start with - HandlerChannelFilter instead of ObserverChannelFilter.</p> - </tp:docstring> - </property> - - <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, channels destined for this handler are automatically - handled, without invoking approvers.</p> - - <tp:rationale> - <p>The intended usage is to allow a client handling one channel to - pick up closely related channels. Suppose a client capable of - handling both Text and StreamedMedia, - <code>org.freedesktop.Telepathy.Client.Empathy</code>, is - handling a StreamedMedia channel. That client can take a second - well-known bus name, say - <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>, - and configure an object at - <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code> - with BypassApproval = TRUE, - whose <tp:member-ref>HandlerChannelFilter</tp:member-ref> - matches closely related Text channels by their Bundle property.</p> - </tp:rationale> - - <p>For service-activatable handlers, this property should be specified - in the handler's <tt>.client</tt> file as follows:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Handler] -BypassApproval=true -</pre> - </tp:docstring> - </property> - - <tp:simple-type name="Handler_Capability_Token" type="s" - array-name="Handler_Capability_Token_List"> - <tp:docstring> - A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character - and an identifier for a capability defined by that interface. The - capability identifier SHOULD be in lower case. If an interface - references an external specification which is case-insensitive (such - as MIME), then names from that specification MUST be normalized to - lower-case before providing them to this Telepathy API, so that - implementations can safely rely on simple byte-by-byte comparison. - - <tp:rationale> - These aren't D-Bus core Properties, and we want them to look visibly - different. - </tp:rationale> - - <p>So far, all client capabilities are defined by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface.</p> - </tp:docstring> - </tp:simple-type> - - <property name="Capabilities" tp:name-for-bindings="Capabilities" - type="as" tp:type="Handler_Capability_Token[]" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The set of additional capabilities supported by this handler. - This describes things like support for streamed media codecs and - NAT traversal mechanisms: see the Contact Capabilities - interface for more details.</p> - - <p>For handlers that have a <code>.client</code> file, the - channel dispatcher may discover this property from the - <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code> - group; for each capability, that group contains a key - whose name is the capability, with value <code>true</code>. - Keys with other values SHOULD NOT appear in this group.</p> - - <p>For instance, the <code>.client</code> file for a streamed media - handler that supports ICE-UDP NAT traversal, Speex audio, - and Theora and H264 video might contain this group:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Handler.Capabilities] -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true -org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true -</pre> - - <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref> - property, this property cannot change while the Handler owns its - Client bus name. However, the <code>.client</code> file, if any, - can change (due to upgrades or installation of pluggable codecs), - and the capabilities really supported by the handler might not - exactly match what is cached in the <code>.client</code> file.</p> - - <tp:rationale> - <p>The client file is installed statically and is intended to list - codecs etc. that the handler guarantees it can support (e.g. by - having a hard dependency on them), whereas the running handler - process might be able to find additional codecs.</p> - </tp:rationale> - </tp:docstring> - </property> - - <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when this client should handle these - channels, or when this client should present channels that it is already - handling to the user (e.g. bring them into the foreground).</p> - - <tp:rationale> - <p>Clients are expected to know what channels they're already handling, - and which channel object path corresponds to which window or tab. - This can easily be done using a hash table keyed by channels' object - paths.</p> - </tp:rationale> - - <p>This method can raise any D-Bus error. If it does, the - handler is assumed to have failed or crashed, and the channel - dispatcher MUST recover in an implementation-specific way; it MAY - attempt to dispatch the channels to another handler, or close the - channels.</p> - - <p>If closing the channels, it is RECOMMENDED that the channel - dispatcher attempts to close the channels using - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, - but resorts to calling - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> - (if available) or ignoring the channel (if not) if the same handler - repeatedly fails to handle channels.</p> - - <p>After HandleChannels returns successfully, the client process is - considered to be responsible for the channel until it its unique - name disappears from the bus.</p> - - <tp:rationale> - <p>If a process has multiple Client bus names - some temporary and - some long-lived - and drops one of the temporary bus names in order - to reduce the set of channels that it will handle, any channels - that it is already handling should remain unaffected.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o" direction="in"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - with which the channels are associated. The - well-known bus name to use is that of the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Connection" type="o" direction="in"> - <tp:docstring> - The Connection with which the channels are associated. The - well-known bus name to use can be derived from this object - path by removing the leading '/' and replacing all subsequent - '/' by '.'. - </tp:docstring> - </arg> - - <arg name="Channels" type="a(oa{sv})" direction="in" - tp:type="Channel_Details[]"> - <tp:docstring> - The channels and their immutable properties. Their well-known - bus name is the same as that of the Connection. - </tp:docstring> - </arg> - - <arg name="Requests_Satisfied" type="ao" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The requests satisfied by these channels.</p> - - <tp:rationale> - <p>If the handler implements Requests, this tells it - that these channels match previous <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> - calls that it may have received.</p> - - <p>There can be more than one, if they were EnsureChannel - requests.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="User_Action_Time" type="t" direction="in"> - <tp:docstring> - The time at which user action occurred, or 0 if this channel - is to be handled for some reason not involving user action. - Handlers SHOULD use this for focus-stealing prevention, - if applicable. - This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> - but is unsigned for historical reasons. - </tp:docstring> - </arg> - - <arg name="Handler_Info" type="a{sv}" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. Currently defined - keys are:</p> - - <dl> - <dt><code>request-properties</code> - a{oa{sv}}</dt> - <dd>A map from <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - paths listed in <var>Requests_Satisfied</var> to - <tp:type>Qualified_Property_Value_Map</tp:type>s containing - namespaced immutable properties of each request.</dd> - </dl> - - <p>When more keys are defined for this dictionary, all will be - optional; handlers MAY safely ignore any entry in this - dictionary.</p> - </tp:docstring> - </arg> - - <!-- FIXME: invent a way to say "any error is possible" in spec markup --> - </method> - - <property name="HandledChannels" tp:name-for-bindings="Handled_Channels" - type="ao" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the channels that this process is currently handling.</p> - - <p>There is no change notification.</p> - - <tp:rationale> - <p>This property exists for state recovery - it makes it possible - for channel handling to survive a ChannelDispatcher crash.</p> - - <p>If the channel dispatcher is automatically replaced, the - replacement can discover all Handlers by looking for the Client - well-known bus names, and discover which channels they are - currently handling. Once this has been done, all unhandled - channels can be re-dispatched, and the only issue visible to - the user is that unhandled channels that they have already - approved might be sent back to Approvers.</p> - </tp:rationale> - - <p>The value of this property SHOULD be the same for all Client - instances that share a unique bus name, and SHOULD include all - channels that are being handled, even if they were conceptually - handled by a different Client instance.</p> - - <tp:rationale> - <p>Otherwise, when a process released a temporary Client name, - channels that it handled because of that Client name would no - longer be state-recoverable.</p> - </tp:rationale> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Handler_Future.xml b/qt4/spec/Client_Handler_Future.xml deleted file mode 100644 index 4c1a8b761..000000000 --- a/qt4/spec/Client_Handler_Future.xml +++ /dev/null @@ -1,88 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Handler_Future" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009 Collabora Ltd.</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 - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - - <interface name="org.freedesktop.Telepathy.Client.Handler.FUTURE" - tp:causes-havoc="a staging area for future Handler functionality"> - <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains functionality which we intend to incorporate - into the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> - interface in future. It should be considered to - be conceptually part of the core Handler interface, but without - API or ABI guarantees.</p> - </tp:docstring> - - <property name="BypassObservers" tp:name-for-bindings="Bypass_Observers" - type="b" access="read"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, channels destined for this handler are not passed to - observers for observing.</p> - - <tp:rationale> - <p>This is useful in use-cases where the handler doesn't want anyone - observing the channel - for example, because channels it handles - shouldn't be logged.</p> - </tp:rationale> - - <p>For service-activatable handlers, this property should be specified - in the handler's <tt>.client</tt> file as follows:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Handler] -BypassObservers=true -</pre> - </tp:docstring> - </property> - - <property name="RelatedConferencesBypassApproval" - tp:name-for-bindings="Related_Conferences_Bypass_Approval" - type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, channels destined for this handler that have the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" - >Conference</tp:dbus-ref> interface, with a channel that - was previously handled by the same client process in their - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Conference" - >InitialChannels</tp:dbus-ref> property, should bypass the - approval stage. In effect, this is a weaker form of - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler" - >BypassApproval</tp:dbus-ref>.</p> - - <tp:rationale> - <p>It would be reasonable for a user interface to accept - invitations to continuations of an existing channel automatically, - or not; this is a matter of UI policy.</p> - - <p>It's somewhat complex for an Approver to keep track of which - channels are being handled by a particular Handler, but - the Channel Dispatcher already has to track this, so it's - useful for the channel dispatcher to assist here.</p> - </tp:rationale> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Interface_Requests.xml b/qt4/spec/Client_Interface_Requests.xml deleted file mode 100644 index 3cecfce49..000000000 --- a/qt4/spec/Client_Interface_Requests.xml +++ /dev/null @@ -1,175 +0,0 @@ -<?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:added version="0.17.26">(as a stable interface)</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>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref> - MUST be included, and <tp:dbus-ref - namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> - MUST be included if implemented.</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 deleted file mode 100644 index b42b3b1df..000000000 --- a/qt4/spec/Client_Observer.xml +++ /dev/null @@ -1,447 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Observer" - 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.Observer"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Client"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Observers monitor the creation of new channels. This - functionality can be used for things like message logging. - All observers are notified simultaneously.</p> - - <p>Observers SHOULD NOT modify the state of a channel except - via user interaction.</p> - - <tp:rationale> - <p>We want Observer UIs for file transfer channels (a progress - bar for the transfer) to be able to have a Cancel button.</p> - </tp:rationale> - - <p>Observers MUST NOT carry out actions that exactly one process - must take responsibility for (e.g. acknowledging Text - messages, or carrying out the actual transfer in a file transfer - channel).</p> - - <tp:rationale> - <p>Since arbitrarily many observers can be activated for - each channel, it would not make sense for observers to do things - that can only be done by one process (acknowledging - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - messages, carrying out streaming for - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - channels, doing the actual data transfer for file transfers, - setting up the out-of-band connection for Tubes). The - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> - is responsible for such tasks.</p> - - <p>Handlers MAY, of course, delegate responsibility for these - tasks to other processes (including those run as observers), - but this MUST be done explicitly via a request from the Handler - to the Observer.</p> - </tp:rationale> - - <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 some of the channels.</p> - - <p>Observers are activated for all channels in which they have - registered an interest - incoming, outgoing or automatically created - - although of course the ObserverChannelFilter property can be set - to filter on the - <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> - - <p>Non-interactive approvers (for instance, to shoot down spam - IM channels before the tray icon blinks at the user, or to grab - a SASL channel before the user is prompted for a password) can - be implemented as observers by following these steps:</p> - - <ol> - <li><tp:member-ref>ObserveChannels</tp:member-ref>() is called - on the observer.</li> - <li>The observer calls <tp:dbus-ref - namespace="ofdT.ChannelDispatchOperation">Claim</tp:dbus-ref>() - on the CDO.</li> - <li>The observer then returns from - <tp:member-ref>ObserveChannels</tp:member-ref>().</li> - <li><tp:dbus-ref - namespace="ofdT.ChannelDispatchOperation">Claim</tp:dbus-ref> - will return successfully if the channels were successfully - claimed, or failure if someone else got there first.</li> - </ol> - - <p>Non-interactive approvers implemented as observers SHOULD - also set <tp:member-ref>DelayApprovers</tp:member-ref> to TRUE - so that other Approvers are not called on until all observers - return from <tp:member-ref>ObserveChannels</tp:member-ref>. - This gives non-interactive approvers a chance to claim the - channels before Approvers are called.</p> - </tp:docstring> - - <property name="ObserverChannelFilter" - tp:name-for-bindings="Observer_Channel_Filter" - type="aa{sv}" access="read" tp:type="Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specification of the channels 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 <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> - - <dl> - <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt> - <dd>Matched by numeric value, regardless of type (e.g. 42 as a - 16-bit signed integer 'n' is considered equal to 42 as a 32-bit - unsigned integer 'u')</dd> - - <dt>Booleans (b)</dt> - <dd>Matched by equality in the obvious way; not considered equal to any - other type</dd> - - <dt>Strings (s)</dt> - <dd>Matched by equality in the obvious way; not considered equal to any - other type</dd> - - <dt>Object paths (o)</dt> - <dd>Matched by equality in the obvious way; not considered equal to any - other type</dd> - - </dl> - - <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 - "<code><em>propertyname</em> <em>type</em></code>", - in groups in the .client file whose name is the name of this - interface followed by <code>.ObserverChannelFilter</code>, - a space and an ASCII decimal number starting from 0.</p> - - <p>Values in the .client file are encoded in exactly the same way as - the <code>default-<em>p</em></code> keys in .manager files, as - described in the <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >ConnectionManager</tp:dbus-ref> interface (but note that not all - types supported in .manager files can appear in .client files).</p> - - <p>For instance, a .client file for an observer that is only interested - in Text channels, with CONTACT or ROOM handles, that were requested by - a local client:</p> - -<pre> -[org.freedesktop.Telepathy.Client] -Interfaces=org.freedesktop.Telepathy.Client.Observer; - -[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0] -org.freedesktop.Telepathy.Channel.ChannelType 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.ObserverChannelFilter 1] -org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text -org.freedesktop.Telepathy.Channel.TargetHandleType u=2 -org.freedesktop.Telepathy.Channel.Requested b=true -</pre> - - </tp:docstring> - </property> - - <property name="Recover" tp:name-for-bindings="Recover" type="b" - access="read"> - <tp:added version="0.19.4"> - When using telepathy-mission-control, version 5.4.0 or later is - needed for this property to be useful. - </tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, upon the startup of this observer, <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref> - will be called for every already existing channel matching - its <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p> - - <p>When an activatable client having this property disappears from the - bus and there are channels matching its ObserverChannelFilter, - ObserveChannels will be called immediately to reactivate it - again. Such clients should specify this property in their - <tt>.client</tt> file as follows:</p> - -<pre> -[org.freedesktop.Telepathy.Client.Observer] -Recover=true -</pre> - - <tp:rationale> - <p>This means that if an activatable Observer crashes, it will - be restarted as soon as possible; while there is an unavoidable - possibility that it will miss some events during this process - (particularly <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - messages), this window of event loss is kept to a minimum.</p> - - <p>Non-activatable observers can't take advantage of this - mechanism, but setting this property on a non-activatable - observer does allow it to "catch up" on channels that are - currently active at the time that it starts up.</p> - </tp:rationale> - - <p>When the ObserveChannels method is called due to observer recovery, - the <var>Observer_Info</var> dictionary will contain one extra item - mapping the key <code>"recovering"</code> to <code>True</code>.</p> - </tp:docstring> - </property> - - <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 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 - state).</p> - - <tp:rationale> - <p>The channel dispatcher must wait for observers to start up, - to avoid the following race: text channel logger (observer) gets - ObserveChannels, text channel handler gets - <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"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> - with which the channels are associated. The - well-known bus name to use is that of the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Connection" type="o" direction="in"> - <tp:docstring> - The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - with which the channels are associated. The - well-known bus name to use can be derived from this object - path by removing the leading '/' and replacing all subsequent - '/' by '.'. - </tp:docstring> - </arg> - - <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" - direction="in"> - <tp:docstring> - The <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s - and their properties. Their well-known bus names are all the same as - that of the Connection. - </tp:docstring> - </arg> - - <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 <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>s - satisfied by these channels. - - <tp:rationale> - 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> - - <arg name="Observer_Info" type="a{sv}" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. Currently defined - keys are:</p> - - <dl> - <dt><code>recovering</code> - b</dt> - <dd><code>True</code> if ObserveChannels was called for an existing - channel (due to the <tp:member-ref>Recover</tp:member-ref> - property being <code>True</code>); <code>False</code> or omitted - otherwise. - - <tp:rationale> - This allows observers to distinguish between new channels (the normal - case), and existing channels that were given to the observer in order - to catch up on previous events (perhaps after a previous instance of - the same observer crashed). - </tp:rationale> - </dd> - - <dt><code>request-properties</code> - a{oa{sv}}</dt> - <dd>A map from <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - paths listed in <var>Requests_Satisfied</var> to - <tp:type>Qualified_Property_Value_Map</tp:type>s containing - namespaced immutable properties of each request.</dd> - </dl> - - <p>All defined keys for this dictionary are optional; - observers MAY safely ignore any entry in this dictionary.</p> - </tp:docstring> - </arg> - - </method> - - <property name="DelayApprovers" type="b" access="read" - tp:name-for-bindings="Delay_Approvers"> - <tp:added version="0.21.11"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, the channel dispatcher will wait for - <tp:member-ref>ObserveChannels</tp:member-ref> to return - before calling <tp:dbus-ref - namespace="ofdT.Client">Approver.AddDispatchOperation</tp:dbus-ref> - on appropriate Approvers.</p> - - <p>This property SHOULD be false unless there is a reason - why a channel should not be given to approvers. An example - of this is if an Observer is also a Handler and wants to - <tp:dbus-ref - namespace="ofdT.ChannelDispatchOperation">Claim</tp:dbus-ref> - a channel so that it becomes its handler and doesn't want - any approver to be called, this property should be true.</p> - - <p>Observers and Approvers should be called at the same time - in normal operation (with this property set to false) to - improve responsiveness. For example, if an incoming call - appears, the approver should get the channel as fast as - possible to show a dialog, but if an approver has to make - round-trips to set itself up, then the approval of the - channel is delayed. As a result, it is recommended for this - property to remain false unless absolutely necessary.</p> - - <p>For service-activatable clients, this property should be - specified in the observer's <tt>.client</tt> file as - follows:</p> - - <p>If this property is not implemented (telepathy-mission-control - 5.7.5 and older), the channel dispatcher SHOULD consider it as - being false.</p> - -<pre> -[org.freedesktop.Telepathy.Client.Observer] -DelayApprovers=true -</pre> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection.xml b/qt4/spec/Connection.xml deleted file mode 100644 index 0ba095a9e..000000000 --- a/qt4/spec/Connection.xml +++ /dev/null @@ -1,1299 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection" - 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: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.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"> - <tp:docstring>The object path of the channel, which is on the - same bus name as the connection</tp:docstring> - </tp:member> - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"> - <tp:docstring>The channel's type</tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Handle_Type" name="Handle_Type"> - <tp:docstring>The type of the handle that the channel communicates - with, or Handle_Type_None if there is no associated - handle</tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Handle" name="Handle"> - <tp:docstring>The handle that the channel communicates with, - or 0 if there is no associated handle</tp:docstring> - </tp:member> - </tp:struct> - - <method name="Connect" tp:name-for-bindings="Connect"> - <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> - - <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"> - <tp:docstring> - Request that the connection be closed. This closes the connection if - it's not already in DISCONNECTED state, and destroys the connection - object. - </tp:docstring> - </method> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - access="read" type="as" tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The set of optional interfaces supported by this connection. - Before the connection status changes to CONNECTED, - this property may change at any time, but it is guaranteed that - interfaces will only be added, not removed. After the connection - status changes to CONNECTED, this property cannot - change further.</p> - - <p>There is no explicit change notification; reasonable behaviour - for a client would be to retrieve the interfaces list once - initially, and once more when it becomes CONNECTED.</p> - - <tp:rationale> - <p>In some connection managers, certain capabilities of a connection - are known to be implemented for all connections (e.g. support - for SimplePresence), and some interfaces (like SimplePresence) can - even be used before connecting. Other capabilities may - or may not exist, depending on server functionality; by the time - the connection goes CONNECTED, the connection manager is expected - to have evaluated the server's functionality and enabled any extra - interfaces for the remainder of the Connection's lifetime.</p> - </tp:rationale> - </tp:docstring> - <tp:added version="0.19.2">Clients SHOULD fall back - to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this - property is not supported.</tp:added> - </property> - - <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> - <arg direction="out" type="as" tp:type="DBus_Interface[]" - name="Interfaces"> - <tp:docstring> - The value of the <tp:member-ref>Interfaces</tp:member-ref> property - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Returns the set of optional interfaces supported by this - connection. See <tp:member-ref>Interfaces</tp:member-ref> for more - details.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"> - <tp:docstring> - Before version 0.17.8 calling GetInterfaces while - on a connection that is not yet CONNECTED wasn't allowed. If a - CM returns this error, its list of interfaces should be regarded - as empty until it becomes CONNECTED. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetProtocol" tp:name-for-bindings="Get_Protocol"> - <arg direction="out" type="s" tp:type="Protocol" name="Protocol"> - <tp:docstring> - A string identifier for the protocol - </tp:docstring> - </arg> - - <tp:docstring> - Get the protocol this connection is using. - </tp:docstring> - </method> - - <signal name="SelfHandleChanged" - tp:name-for-bindings="Self_Handle_Changed"> - <tp:docstring> - Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property - changes. If the connection - is not yet in the CONNECTED state, this signal is not guaranteed - to be emitted. - </tp:docstring> - <tp:added version="0.17.10">Clients MAY assume that if the - SelfHandle property exists, this signal will be emitted when - necessary.</tp:added> - - <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> - <tp:docstring> - The new value of the SelfHandle property. - </tp:docstring> - </arg> - </signal> - - <property name="SelfHandle" tp:name-for-bindings="Self_Handle" - type="u" tp:type="Contact_Handle" access="read"> - <tp:docstring> - The handle which represents the user on this connection, which will - remain valid for the lifetime of this connection, or until a change - in the user's identifier is signalled by the - <tp:member-ref>SelfHandleChanged</tp:member-ref> signal. - If the connection is not yet in the CONNECTED state, the value of - this property MAY be zero. - </tp:docstring> - <tp:added version="0.17.10">For compatibility with older - versions, clients should fall back to calling the - <tp:member-ref>GetSelfHandle</tp:member-ref> - method.</tp:added> - </property> - - <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle" - name="Self_Handle"> - <tp:docstring> - The value of the <tp:member-ref>SelfHandle</tp:member-ref> property - </tp:docstring> - </arg> - - <tp:docstring> - Returns the value of the SelfHandle property. Change notification - is via the SelfHandleChanged signal. - </tp:docstring> - <tp:deprecated version="0.17.10">Use GetAll to get the - SelfHandle property (and all other Connection properties) - instead.</tp:deprecated> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - - <property name="Status" tp:name-for-bindings="Status" - access="read" type="u" tp:type="Connection_Status"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The current status of the connection. Change notification is via - the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p> - - <p>If retrieval of property succeeds and yields the value Disconnected, - this indicates that the connection has not yet been established. - If connection has been attempted and failed, the Connection object - SHOULD be removed from the bus entirely, meaning that retrieval of - this property SHOULD fail.</p> - </tp:docstring> - <tp:added version="0.19.2">Clients SHOULD fall back - to calling <tp:member-ref>GetStatus</tp:member-ref> if this - property is not supported.</tp:added> - </property> - - <method name="GetStatus" tp:name-for-bindings="Get_Status"> - <arg direction="out" type="u" tp:type="Connection_Status" - name="Status"> - <tp:docstring> - The value of the <tp:member-ref>Status</tp:member-ref> property - </tp:docstring> - </arg> - - <tp:docstring> - Get the current status as defined in the - <tp:member-ref>StatusChanged</tp:member-ref> signal. - </tp:docstring> - </method> - - <method name="HoldHandles" tp:name-for-bindings="Hold_Handles"> - <tp:changed version="0.21.6">If - <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - this method no longer does anything.</tp:changed> - <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - The type of handle to be held - </tp:docstring> - </arg> - - <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> - <tp:docstring> - A array of integer handles to hold - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - which SHOULD always be the case in this version of telepathy-spec, - this method does nothing and returns successfully, unless - the given handle type or any of the given handles is invalid.</p> - - <p>In older connection managers, this method - notifies the connection manger that your client is holding a copy - of handles which may not be in use in any existing channel or - list, and were not obtained by using the - <tp:member-ref>RequestHandles</tp:member-ref> method. For - example, a handle observed in an emitted signal, or displayed - somewhere in the UI that is not associated with a channel. The - connection manager must not deallocate a handle where any clients - have used this method to indicate it is in use until the - <tp:member-ref>ReleaseHandles</tp:member-ref> - method is called, or the clients disappear from the bus.</p> - - <p>Note that HoldHandles is idempotent - calling it multiple times - is equivalent to calling it once. If a handle is "referenced" by - several components which share a D-Bus unique name, the client - should perform reference counting internally, and only call - ReleaseHandles when none of the cooperating components need the - handle any longer.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The handle type is invalid - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - One of the given handles is not valid - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="InspectHandles" tp:name-for-bindings="Inspect_Handles"> - <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - The type of handle to be inspected - </tp:docstring> - </arg> - - <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> - <tp:docstring> - An array of integer handles of this type - </tp:docstring> - </arg> - - <arg direction="out" type="as" name="Identifiers"> - <tp:docstring> - An array of identifiers corresponding to the given handles, in the same order. - </tp:docstring> - </arg> - - <tp:docstring> - Return a string representation for a number of handles of a given - type. - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The handle type is invalid - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - One of the given handles is not valid - </tp:docstring> - </tp:error> - </tp:possible-errors> - </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> - An array of structs representing channels. - </tp:docstring> - </arg> - - <tp:docstring> - List all the channels which currently exist on this connection. - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </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 - </tp:docstring> - </arg> - - <arg name="Channel_Type" type="s" tp:type="DBus_Interface"> - <tp:docstring> - A D-Bus interface name representing the channel type - </tp:docstring> - </arg> - - <arg name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - An integer representing the type of handle this channel - communicates with, or Handle_Type_None if no handle is specified - </tp:docstring> - </arg> - - <arg name="Handle" type="u" tp:type="Handle"> - <tp:docstring> - A handle indicating the specific contact, room or list this - channel communicates with, or zero if no handle is specified - </tp:docstring> - </arg> - - <arg name="Suppress_Handler" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, the channel was requested by a client that intends to - present it to the user itself (i.e. it passed suppress_handler=TRUE - to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no - other handler should be - launched. Clients MAY assume that channels where this is true - were created by a user request.</p> - - <p>If false, either the channel was created due to incoming - information from the service, or the channel was requested by - a local client that does not intend to handle the channel itself - (this usage is deprecated).</p> - - <p>Clients MUST NOT assume that only incoming channels will have - this flag set to false.</p> - </tp:docstring> - </arg> - - <tp:docstring> - Emitted when a new Channel object is created, either through user - request or incoming information from the service. - </tp:docstring> - </signal> - - <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles"> - <tp:changed version="0.21.6">If - <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - this method no longer does anything.</tp:changed> - <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - An integer handle type (as defined in RequestHandle) - </tp:docstring> - </arg> - - <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> - <tp:docstring> - An array of integer handles being held by the client - </tp:docstring> - </arg> - - <tp:docstring> - <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - which SHOULD always be the case in this version of telepathy-spec, - this method does nothing and returns successfully, unless - the given handle type or any of the given handles is invalid.</p> - - <p>In older connection managers, this method - explicitly notifies the connection manager that your client is no - longer holding any references to the given handles, and that they - may be deallocated if they are not held by any other clients or - referenced by any existing channels. See - <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The handle type is invalid - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - One of the given handles is not valid - </tp:docstring> - </tp:error> - </tp:possible-errors> - </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 - </tp:docstring> - </arg> - - <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - An integer representing the handle type, or Handle_Type_None if - no handle is specified - </tp:docstring> - </arg> - - <arg direction="in" name="Handle" type="u" tp:type="Handle"> - <tp:docstring> - A nonzero integer handle representing a contact, room, list etc. - according to handle_type, or zero if the handle_type is - Handle_Type_None - </tp:docstring> - </arg> - - <arg direction="in" name="Suppress_Handler" type="b"> - <tp:docstring> - <p>Clients SHOULD always set this to true.</p> - - <tp:rationale> - <p>The historical meaning was that clients that did not - intend to take responsibility for displaying the channel to - the user could set this to FALSE, in which case the channel - dispatcher would launch an appropriate channel handler.</p> - - <p>However, clients whose functionality relies on having a - working channel dispatcher should obtain that functionality by - calling methods on the channel dispatcher, so that they will - get an appropriate error if the channel dispatcher is missing - or not working.</p> - - <p>The channel dispatcher itself should set this to true too, - so that it will ignore the - <tp:member-ref>NewChannel</tp:member-ref> signal that results - from the creation of the channel. It can then dispatch the - channel returned from this method to an - appropriate handler.</p> - - <p>So, there is no sensible use-case for setting this to false, - and setting it to false can result in unhandled channels (in - the case where clients assume that a channel dispatcher is - present, but it isn't).</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg direction="out" type="o" name="Object_Path"> - <tp:docstring> - The D-Bus object path for the channel created or retrieved - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request a channel satisfying the specified type and communicating - with the contact, room, list etc. indicated by the given - handle_type and handle. The handle_type and handle may both be - zero to request the creation of a new, empty channel, which may - or may not be possible, depending on the protocol and channel - type.</p> - - <p>On success, the returned channel will always be of the requested - type (i.e. implement the requested channel-type interface).</p> - - <p>If a new, empty channel is requested, on success the returned - channel will always be an "anonymous" channel for which the type - and handle are both zero.</p> - - <p>If a channel to a contact, room etc. is requested, on success, the - returned channel may either be a new or existing channel to - the requested entity (i.e. its - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - properties are the - requested handle type and handle), or a newly created "anonymous" - channel associated with the requested handle in some - implementation-specific way.</p> - - <p>For example, for a contact handle, the returned channel - might be "anonymous", but implement the groups interface and have - the requested contact already present among the members.</p> - - <p>If the request cannot be satisfied, an error is raised and no - channel is created.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Unknown channel type - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - The given handle does not exist or cannot be created - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The requested channel type cannot be created with the given handle - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> - <tp:docstring> - The requested channel cannot be created because contact doesn't - have the required capabilities. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> - </tp:possible-errors> - </method> - - <tp:enum name="Handle_Type" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - A "null" handle type used to indicate the absence of a handle. - When a handle type and a handle appear as a pair, if the handle - type is zero, the handle must also be zero. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Contact" value="1"> - <tp:docstring> - A contact - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Room" value="2"> - <tp:docstring> - A chat room - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="List" value="3"> - <tp:docstring> - A server-generated contact list (see Channel.Interface.Group) - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Group" value="4"> - <tp:docstring> - A user-defined contact list (see Channel.Interface.Group) - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <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" - 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" - 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" - 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" - 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> - - <method name="RequestHandles" tp:name-for-bindings="Request_Handles"> - <tp:changed version="0.21.6">If - <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - this method no longer has its reference-counting effect.</tp:changed> - <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> - <tp:docstring> - The type of handle required - </tp:docstring> - </arg> - - <arg direction="in" name="Identifiers" type="as"> - <tp:docstring> - An array of identifiers of entities to request handles for - </tp:docstring> - </arg> - - <arg direction="out" type="au" tp:type="Handle[]" - name="Handles"> - <tp:docstring> - An array of integer handle numbers in the same order as the given identifiers. - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request several handles from the connection manager which represent a - number of contacts, rooms or server-stored lists on the service.</p> - - <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, - which SHOULD always be the case in this version of telepathy-spec, - the handles remain valid until the connection disconnects.</p> - - <p>The implementation of this method in older connection managers - must record that these handles are in use by the - client who invokes this method, and must not deallocate the handles - until the client disconnects from the bus or calls the - <tp:member-ref>ReleaseHandles</tp:member-ref> - method. Where the identifier refers to an entity that already has a - handle in this connection manager, this handle should be returned - instead. The handle number 0 must not be returned by the connection - manager.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - The given identifier does not identify a valid entity of the given - type. - - <tp:rationale> - For instance, an XMPP connection would raise this error for - identifiers with type Handle_Type_Room that do not contain - exactly one '@' character, that contain spaces, and so on. - </tp:rationale> - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given handle type is not valid, or is not implemented on this - connection. - - <tp:rationale> - For instance, a connection to a protocol that doesn't have - chat rooms would raise this error for room handles, and all CMs - would raise this error for Handle_Type_None. - </tp:rationale> - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u"> - <tp:enumvalue suffix="Connected" value="0"> - <tp:docstring> - The connection is fully connected and all methods are available. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Connecting" value="1"> - <tp:docstring> - <tp:member-ref>Connect</tp:member-ref> has been called but the - connection has not yet been established. Some methods may fail - until the connection has been established. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Disconnected" value="2"> - <tp:docstring> - If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or - <tp:member-ref>Status</tp:member-ref>, it indicates that connection - has not yet been attempted. If seen in a - <tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates - that the connection has failed; the Connection object SHOULD be - removed from D-Bus immediately, and all subsequent method calls - SHOULD fail. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:enum name="Connection_Status_Reason" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A reason why the status of the connection changed. Apart from - Requested, the values of this enumeration only make sense as - reasons why the status changed to Disconnected.</p> - </tp:docstring> - - <tp:enumvalue suffix="None_Specified" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There is no reason set for this state change. Unknown status - reasons SHOULD be treated like this reason.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Requested" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change is in response to a user request. Changes to the - Connecting or Connected status SHOULD always indicate this reason; - changes to the Disconnected status SHOULD indicate this reason - if and only if the disconnection was requested by the user.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Network_Error" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There was an error sending or receiving on the network socket.</p> - - <p>When the status changes from Connecting to Disconnected for this - reason, the equivalent D-Bus error is either - <code>org.freedesktop.Telepathy.Error.NetworkError</code>, - <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>, - <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code> - or some more specific error.</p> - - <p>When the status changes from Connected to Disconnected for this - reason, the equivalent D-Bus error is either - <code>org.freedesktop.Telepathy.Error.NetworkError</code>, - <code>org.freedesktop.Telepathy.Error.ConnectionLost</code> - or some more specific error.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Authentication_Failed" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The username or password was invalid.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Encryption_Error" value="4"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There was an error negotiating SSL on this connection, or - encryption was unavailable and require-encryption was set when the - connection was created.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code> - if encryption was not available at all, or - <code>org.freedesktop.Telepathy.Error.EncryptionError</code> - if encryption failed.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Name_In_Use" value="5"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>In general, this reason indicates that the requested account - name or other identification could not be used due to conflict - with another connection. It can be divided into three cases:</p> - - <ul> - <li>If the status change is from Connecting to Disconnected - and the 'register' parameter to RequestConnection was present - and true, the requested account could not be created on the - server because it already exists. - The equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>. - </li> - - <li>If the status change is from Connecting to Disconnected - but the 'register' parameter is absent or false, the connection - manager could not connect to the specified account because - a connection to that account already exists. - The equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>. - - <tp:rationale> - In some protocols, like XMPP (when connecting with the same - JID and resource as an existing connection), the existing - connection "wins" and the new one fails to connect. - </tp:rationale> - </li> - - <li>If the status change is from Connected to Disconnected, - the existing connection was automatically disconnected because - a new connection to the same account (perhaps from a different - client or location) was established. - The equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>. - - <tp:rationale> - In some protocols, like MSNP (when connecting twice with the - same Passport), the new connection "wins" and the - existing one is automatically disconnected. - </tp:rationale> - </li> - </ul> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Not_Provided" value="6"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server did not provide a SSL certificate.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Untrusted" value="7"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate is signed by an untrusted certifying - authority. This error SHOULD NOT be used to represent a self-signed - certificate: use the more specific Cert_Self_Signed reason for - that.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Expired" value="8"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate has expired.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Not_Activated" value="9"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate is not yet valid.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate did not match its hostname.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate does not have the expected - fingerprint.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Self_Signed" value="12"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate is self-signed.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Other_Error" value="13"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There was some other error validating the server's SSL - certificate.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Revoked" value="14"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate has been revoked.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Insecure" value="15"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The server's SSL certificate uses an insecure algorithm, - or is cryptographically weak.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>. - </p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The length in bytes of the server certificate, or the depth of the - sever certificate chain exceed the limits imposed by the crypto - library.</p> - - <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code> - </p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="ConnectionError" tp:name-for-bindings="Connection_Error"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when an error occurs that renders this connection unusable. - </p> - - <p>Whenever this signal is emitted, it MUST immediately be followed by - a <tp:member-ref>StatusChanged</tp:member-ref> signal with status - Connection_Status_Disconnected and an appropriate reason - code.</p> - - <p>Connection managers SHOULD emit this signal on disconnection, but - need not do so. Clients MUST support connection managers that emit - StatusChanged(Disconnected, ...) without first emitting - ConnectionError.</p> - - <tp:rationale> - <p>This signal provides additional information about the reason - for disconnection. The reason for connection is always - straightforward - it was requested - so it does not need further - explanation. However, on errors, it can be useful to provide - additional information.</p> - - <p>The <tp:type>Connection_Status_Reason</tp:type> is not given - here, since it will be signalled in - <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client - implementation would be to store the information given by this - signal until StatusChanged is received, at which point the - information given by this signal can be used to supplement the - StatusChanged signal.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Error" type="s" tp:type="DBus_Error_Name"> - <tp:docstring> - The name of a D-Bus error describing the error that occurred, - which may correspond to a - <tp:type>Connection_Status_Reason</tp:type>, or may be a more - specific Telepathy error - (such as - <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code> - for Connection_Status_Reason_Network_Error) - or a protocol-specific or connection-manager-specific error in a - suitable namespace. - - <tp:rationale> - For instance, a SIP connection manager could signal - "402 Payment Required" as an error in a - connection-manager-specific namespace, or a link-local - XMPP implementation that used Avahi could provide the error - given to it by the avahi-daemon. - </tp:rationale> - </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 error, 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> - - <dt>server-message (s)</dt> - <dd>A human-readable message from the server explaining what - happened. This may be in the user's native language, or in the - server operator's native language, or even in Lojban.</dd> - - <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt> - <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd> - </dl> - - </tp:docstring> - </arg> - - </signal> - - <signal name="StatusChanged" tp:name-for-bindings="Status_Changed"> - <arg name="Status" type="u" tp:type="Connection_Status"> - <tp:docstring> - An integer indicating the new status, as defined by ConnectionStatus - </tp:docstring> - </arg> - - <arg name="Reason" type="u" tp:type="Connection_Status_Reason"> - <tp:docstring> - An integer indicating the reason for the status change, as defined - by ConnectionStatusReason - </tp:docstring> - </arg> - - <tp:docstring> - Emitted when the status of the connection changes. All states and - reasons have numerical values, as defined in ConnectionStatus - and ConnectionStatusReason. - </tp:docstring> - </signal> - - <tp:contact-attribute name="contact-id" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same string that would be returned by - <tp:member-ref>InspectHandles</tp:member-ref>. As a special case, - this is always present in the result of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>, - whether it was explicitly requested or not.</p> - </tp:docstring> - </tp:contact-attribute> - - <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest"> - <tp:added version="0.21.3"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Register a client's interest in notifications related to one or - more interfaces.</p> - - <p>Groups of notifications are identified by a token which is either - a D-Bus interface name, or a string that starts with a D-Bus - interface name. The meaning of each token is given by that D-Bus - interface, which MUST define it in its documentation.</p> - - <tp:rationale> - <p>Initially, all interests are in entire interface, but allowing - other strings allows subscription to part of an interface; for - instance, an interest in ...MailNotification/count could track - the number of messages without caring about their detailed - content.</p> - </tp:rationale> - - <p>For each token with which this method interacts, the - Connection tracks an "interest count" (like a reference count) for - each unique bus name that has called this method. When a client - calls this method, for each token, the interest count for its - unique bus name is incremented; when - <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, - all interest counts for that unique bus name are decremented. - If the unique bus name leaves the bus (for instance, if the - client crashes or exits), all interest counts for that unique bus - name are set to zero.</p> - - <p>The Connection can then use these reference counts to - avoid subscribing to protocol-level notifications unless at least - one client has a non-zero interest count for the relevant - token.</p> - - <tp:rationale> - <p>This method exists to reduce memory and network overhead when - there is no active subscription.</p> - - <p>One situation where this is useful is <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface" - >Location</tp:dbus-ref>: on XMPP, location updates are received - over PEP. If the Connection advertises the - <code>geoloc+notify</code> capability, it will be sent location - updates for all contacts. To avoid consuming resources for this, - the connection should avoid advertising that capability until - a client has expressed an interest in contacts' locations.</p> - - <p>Another example of a protocol that benefits from this method is - the Google XMPP Mail Notification extension, which can be used - to implement <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface" - >MailNotification</tp:dbus-ref>. In this protocol, the CM - receives a notification that something has changed, but to get - more information, the CM must request this information. Knowing - that nobody is currently interested in this information, the CM - can avoid generating useless network traffic. Similarly, the CM - may free the list of unread messages to reduce memory overhead.</p> - </tp:rationale> - - <p>If this method is called for an interface that might require - protocol-level subscription, but the connection cannot set up - that subscription yet (for instance because the - <tp:member-ref>Status</tp:member-ref> is not Connected yet), the - Connection MUST remember the client's interest, and attempt to - subscribe to the appropriate protocol feature when this becomes - possible.</p> - - <p>Clients MAY ignore any errors raised by this method; it is intended - to be called with the reply ignored.</p> - - <tp:rationale> - <p>The only reason it could fail is if it's unimplemented, in which - case the only thing the client can usefully do is to proceed as if - it had succeeded.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Tokens" type="as" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interfaces or parts of interfaces in which to register an - interest, represented by either a - <tp:type>DBus_Interface</tp:type>, or a string prefixed with a - <tp:type>DBus_Interface</tp:type>.</p> - - <p>If the Connection does not support one of these tokens, this - is not considered to be an error; the unsupported token is - simply ignored.</p> - </tp:docstring> - </arg> - </method> - - <method name="RemoveClientInterest" - tp:name-for-bindings="Remove_Client_Interest"> - <tp:added version="0.21.3"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Release an interest registered using - <tp:member-ref>AddClientInterest</tp:member-ref>. See that - method's documentation for details.</p> - - <p>Clients MAY ignore any errors raised by this method; it is intended - to be called with the reply ignored.</p> - - <tp:rationale> - <p>The only reasons it could fail are if it's unimplemented, or if - the client's reference-counting is wrong and it has tried to - remove a client interest that it did not add. In both cases, - there's nothing the client could do about it.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Tokens" type="as" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interfaces or parts of interfaces that were previously passed to - <tp:member-ref>AddClientInterest</tp:member-ref>.</p> - </tp:docstring> - </arg> - </method> - - <property name="HasImmortalHandles" - tp:name-for-bindings="Has_Immortal_Handles" - access="read" type="b"> - <tp:added version="0.21.6"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if handles last for the whole lifetime of the Connection. - This SHOULD be the case in all connection managers, but clients - MUST interoperate with older connection managers - (which reference-count handles).</p> - </tp:docstring> - </property> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This models a connection to a single user account on a communication - service. Its basic capability is to provide the facility to request and - receive channels of differing types (such as text channels or streaming - media channels) which are used to carry out further communication.</p> - - <p>In order to allow Connection objects to be discovered by new clients, - the object path and well-known bus name MUST be of the form - <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code> - and - <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code> - where:</p> - - <ul> - <li><em>cmname</em> is the same - <tp:type>Connection_Manager_Name</tp:type> that appears - in the connection manager's object path and well-known bus name</li> - <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>, - but with "-" replaced with "_" to get a valid - object path/bus name</li> - <li><em>account</em> is some non-empty sequence of ASCII letters, - digits and underscores not starting with a digit</li> - </ul> - - <p><em>account</em> SHOULD be formed such that any valid distinct - connection instance on this protocol has a distinct name. This - might be formed by including the server name followed by the user - name (escaped via some suitable mechanism like telepathy-glib's - tp_escape_as_identifier() function to preserve uniqueness); on - protocols where connecting multiple times is permissable, a - per-connection identifier might be necessary to ensure - uniqueness.</p> - - <p>Clients MAY parse the object path to determine the connection - manager name and the protocol, but MUST NOT attempt to parse the - <em>account</em> part. Connection managers MAY use any unique string - for this part.</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.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 - <tp:member-ref>GetInterfaces</tp:member-ref> method.</p> - - <p>Contacts, rooms, and server-stored lists (such as subscribed contacts, - block lists, or allow lists) on a service are all represented by - immutable <em>handles</em>, which are unsigned non-zero integers which are - valid only for the lifetime of the connection object, and are used - throughout the protocol where these entities are represented, allowing - simple testing of equality within clients.</p> - - <p>Zero as a handle value is sometimes used as a "null" value to mean - the absence of a contact, room, etc.</p> - - <p>Handles have per-type uniqueness, meaning that - every (handle type, handle number) tuple is guaranteed to be unique within - a connection and that a handle alone (without its type) is meaningless or - ambiguous. Connection manager implementations should reference count these - handles to determine if they are in use either by any active clients or any - open channels, and may deallocate them when this ceases to be true. Clients - may request handles of a given type and identifier with the - <tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity - identifier with the <tp:member-ref>InspectHandles</tp:member-ref> - method, keep handles from being released with - <tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no - longer storing handles with - <tp:member-ref>ReleaseHandles</tp:member-ref>.</p> - </tp:docstring> - - <tp:changed version="0.17.10">Previously, the account part of - Connection bus names/object paths was allowed to have more than one - component (i.e. contain dots or slashes), resulting in Connection - 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_Future.xml b/qt4/spec/Connection_Future.xml deleted file mode 100644 index 6b5291efd..000000000 --- a/qt4/spec/Connection_Future.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_FUTURE" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" - > - <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 -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.Connection.FUTURE" - tp:causes-havoc='experimental'> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar"> - <tp:added version="0.19.0">(as a draft)</tp:added> - - <arg direction="in" name="Main_Interface" type="s" - tp:type="DBus_Interface"> - <tp:docstring> - The "primary" interface implemented by an object attached - to a connection. For example, a Gabble plugin implementing - fine-grained control of XEP-0016 privacy lists might expose an object - implementing <tt>com.example.PrivacyLists</tt>. - </tp:docstring> - </arg> - - <arg direction="out" name="Path" type="o"> - <tp:docstring>The object path of the sidecar, exported by the same bus - name as the Connection to which it is attached.</tp:docstring> - </arg> - <arg direction="out" name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring>Immutable properties of the sidecar.</tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request an object with a particular interface providing additional - connection-specific functionality, together with its immutable - properties. These will often be implemented by plug-ins to the - connection managers; for example, support for an XMPP XEP for which - no generic Telepathy interface exists might be implemented by a - Gabble plugin exposing a sidecar with a particular interface.</p> - - <p>This method may be called at any point during the lifetime of a - connection, even before its <tp:type>Connection_Status</tp:type> - changes to Connected. It MAY take a long time to - return—perhaps it needs to wait for a connection to be established - and for all the services supported by the server to be discovered - before determining whether necessary server-side support is - available—so callers SHOULD override the default method timeout (25 - seconds) with a much higher value (perhaps even MAX_INT32, meaning - “no timeout” in recent versions of libdbus).</p> - - <tp:rationale> - <p>There is an implicit assumption that any connection - manager plugin will only want to export one “primary” object per - feature it implements, since there is a one-to-one mapping between - interface and object. This is reasonable since Sidecars are - (intended to be) analogous to extra interfaces on the connection, - providing once-per-connection shared functionality; it also makes - client code straightforward (look up the interface you care about - in a dictionary, build a proxy object from the value). More - “plural” plugins are likely to want to implement new types of - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> - instead.</p> - </tp:rationale> - </tp:docstring> - - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The requested sidecar is not implemented by this connection manager, - or a necessary server-side component does not exist. (FIXME: split - these two errors out? Then again, once we list the guaranteed and - possible sidecars on a Protocol object, clients can tell the - difference themselves, because they shouldn't be calling this in the - first case.) - </tp:docstring> - </tp:error> - - <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> - <tp:docstring> - A server-side component needed by the requested sidecar reported it - is currently too busy, or did not respond for some - implementation-defined time. The caller may wish to try again later. - </tp:docstring> - </tp:error> - - <tp:error name="org.freedesktop.Telepathy.Error.Cancelled"> - <tp:docstring> - The connection was disconnected while the sidecar was being set up. - </tp:docstring> - </tp:error> - </method> - - </interface> -</node> diff --git a/qt4/spec/Connection_Interface_Addressing.xml b/qt4/spec/Connection_Interface_Addressing.xml deleted file mode 100644 index 497c6d0d9..000000000 --- a/qt4/spec/Connection_Interface_Addressing.xml +++ /dev/null @@ -1,258 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2010 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or (at - your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser - General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public License - along with this library; if not, write to the Free Software Foundation, - Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface deals with the multiple address types that can - refer to the same contact, such as vCard fields and URIs.</p> - - <p>It can be used to retrieve contacts with a specific addresses - through <tp:member-ref>GetContactsByVCardField</tp:member-ref> and - <tp:member-ref>GetContactsByURI</tp:member-ref>, as well as - defining the various addressing methods for a given contact - through this interface's contact attributes.</p> - </tp:docstring> - - <method name="GetContactsByVCardField" - tp:name-for-bindings="Get_Contacts_By_VCard_Field"> - <arg direction="in" name="Field" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The vCard field of the addresses we are requesting. The - field name SHOULD be in lower case. Supported - fields can be found in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p> - - <p>The <code>url</code> vCard field MUST NOT appear here; see - <tp:member-ref>GetContactsByURI</tp:member-ref> instead.</p> - - <tp:rationale> - <p>In practice, protocols have a limited set of URI - schemes that make sense to resolve as a contact.</p> - </tp:rationale> - - </tp:docstring> - </arg> - <arg direction="in" name="Addresses" type="as"> - <tp:docstring> - The addresses to get contact handles for. The address types - should match the given vCard field. - </tp:docstring> - </arg> - <arg direction="in" name="Interfaces" type="as" - tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of strings indicating which D-Bus interfaces the calling - process is interested in. All supported attributes from these - interfaces, whose values can be obtained without additional network - activity, will be in the reply.</p> - - <p>Attributes from this interface and from - <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> - are always returned, and need not be requested - explicitly.</p> - - <p>The behavior of this parameter is similar to the same - parameter in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts" - tp:type="Contact_Attributes_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary mapping the contact handles to contact attributes. - If any of the requested addresses are in fact invalid, they are - simply omitted from this mapping. If contact attributes are not - immediately known, the behaviour is defined by the interface; - the attribute should either be omitted from the result or - replaced with a default value.</p> - - <p>Requested addresses that cannot be satisfied MUST be ommitted - from the mapping.</p> - - <p>Each contact's attributes will always include at least the - identifier that would be obtained by inspecting the handle - (<code>org.freedesktop.Telepathy.Connection/contact-id</code>), - and the vCard field used for requesting the contact in - <code>org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info</code>. - </p> - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request contacts and retrieve their attributes using a given field - in their vCards.</p> - - <p>The connection manager should record that these handles are in - use by the client who invokes this method, and must not - deallocate the handles until the client disconnects from the - bus or calls the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> - method.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - - <method name="GetContactsByURI" - tp:name-for-bindings="Get_Contacts_By_URI"> - <arg direction="in" name="URIs" type="as"> - <tp:docstring> - The URI addresses to get contact handles for. Supported - schemes can be found in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableURISchemes</tp:dbus-ref>. - </tp:docstring> - </arg> - <arg direction="in" name="Interfaces" type="as" - tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of strings indicating which D-Bus interfaces the calling - process is interested in. All supported attributes from these - interfaces, whose values can be obtained without additional network - activity, will be in the reply.</p> - - <p>Attributes from this interface and from - <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> - are always returned, and need not be requested - explicitly.</p> - - <p>The behavior of this parameter is similar to the same - parameter in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> - </tp:docstring> - </arg> - - <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts" - tp:type="Contact_Attributes_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary mapping the contact handles to contact attributes. - If any of the requested addresses are in fact invalid, they are - simply omitted from this mapping. If contact attributes are not - immediately known, the behaviour is defined by the interface; - the attribute should either be omitted from the result or - replaced with a default value.</p> - - <p>Requested URIs that cannot be satisfied MUST be ommitted - from the mapping.</p> - - <p>Each contact's attributes will always include at least the - identifier that would be obtained by inspecting the handle - (<code>org.freedesktop.Telepathy.Connection/contact-id</code>). - </p> - </tp:docstring> - </arg> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request contacts and retrieve their attributes using URI addresses.</p> - - <p>The connection manager should record that these handles are in - use by the client who invokes this method, and must not - deallocate the handles until the client disconnects from the - bus or calls the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> - method.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - - <tp:mapping name="VCard_Field_Address_Map" array-name=""> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping of vCard fields and addresses that repreent - the given contact.</p> - </tp:docstring> - <tp:member type="s" name="VCard_Field"/> - <tp:member type="s" name="Address"/> - </tp:mapping> - - <tp:contact-attribute name="addresses" type="a{ss}" - tp:type="VCard_Field_Address_Map"> - <tp:docstring> - The various vCard addresses that identify this contact. - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="uris" type="as"> - <tp:docstring> - The various URI addresses that identify this contact. - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="requested-address" type="(ss)" - tp:type="Requested_Address"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contact's address, as it was requested - through <tp:member-ref>GetContactsByVCardField</tp:member-ref>. This - attribute MUST be ommitted if the contact was not retrieved - through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p> - <tp:rationale> - <p>When retrieving more than one contact - through <tp:member-ref>GetContactsByVCardField</tp:member-ref>, - there needs to be a way to map the given contact back o the - original request.</p> - </tp:rationale> - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="requested-uri" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contact's URI, as it was requested through - <tp:member-ref>GetContactsByURI</tp:member-ref>. This - attribute MUST be ommitted if the contact was not retrieved - through <tp:member-ref>GetContactsByURI</tp:member-ref>.</p> - <tp:rationale> - <p>When retrieving more than one contact - through <tp:member-ref>GetContactsByURI</tp:member-ref>, - there needs to be a way to map the given contact back o the - original request.</p> - </tp:rationale> - </tp:docstring> - </tp:contact-attribute> - - <tp:struct name="Requested_Address" array-name=""> - <tp:docstring> - The address that has been requested by - <tp:member-ref>GetContactsByVCardField</tp:member-ref> or - <tp:member-ref>GetContactsByURI</tp:member-ref>. - </tp:docstring> - - <tp:member name="Field" type="s"> - <tp:docstring> - The vCard field used in <tp:member-ref>GetContactsByVCardField</tp:member-ref>. - </tp:docstring> - </tp:member> - - <tp:member name="Address" type="s"> - <tp:docstring> - The address that was requested. - </tp:docstring> - </tp:member> - - </tp:struct> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Aliasing.xml b/qt4/spec/Connection_Interface_Aliasing.xml deleted file mode 100644 index 967577135..000000000 --- a/qt4/spec/Connection_Interface_Aliasing.xml +++ /dev/null @@ -1,185 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Aliasing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.Aliasing"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:mapping name="Alias_Map" array-name=""> - <tp:docstring>A dictionary whose keys are contact handles and whose - values are aliases.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" name="Alias"/> - </tp:mapping> - - <tp:struct name="Alias_Pair" array-name="Alias_Pair_List"> - <tp:docstring> - A pair (contact handle, alias) as seen in the - <tp:member-ref>AliasesChanged</tp:member-ref> signal. - </tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" name="Alias"/> - </tp:struct> - - <signal name="AliasesChanged" tp:name-for-bindings="Aliases_Changed"> - <arg name="Aliases" type="a(us)" tp:type="Alias_Pair[]"> - <!-- FIXME: if we break API, this could be an Alias_Map, a{us} --> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array containing structs of: - <ul> - <li>the handle representing the contact</li> - <li>the new alias</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - Signal emitted when a contact's alias (or that of the user) is changed. - </tp:docstring> - </signal> - <tp:flags name="Connection_Alias_Flags" value-prefix="Connection_Alias_Flag" type="u"> - <tp:flag suffix="User_Set" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The aliases of contacts on this connection may be changed by the - user of the service, not just by the contacts themselves. This is - the case on Jabber, for instance.</p> - <p>It is possible that aliases can be changed by the contacts too - - which alias takes precedence is not defined by this - specification, and depends on the server and/or connection manager - implementation.</p> - <p>This flag only applies to the aliases of "globally valid" contact - handles. At this time, clients should not expect to be able to - change the aliases corresponding to any channel-specific - handles. If this becomes possible in future, a new flag will - be defined.</p> - </tp:docstring> - </tp:flag> - </tp:flags> - <method name="GetAliasFlags" tp:name-for-bindings="Get_Alias_Flags"> - <arg direction="out" type="u" tp:type="Connection_Alias_Flags" - name="Alias_Flags"> - <tp:docstring> - An integer with a bitwise OR of flags from ConnectionAliasFlags - </tp:docstring> - </arg> - <tp:docstring> - Return a bitwise OR of flags detailing the behaviour of aliases on this - connection. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - <method name="RequestAliases" tp:name-for-bindings="Request_Aliases"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts - </tp:docstring> - </arg> - <arg direction="out" type="as" name="Aliases"> - <tp:docstring> - A list of aliases in the same order as the contact handles - </tp:docstring> - </arg> - <tp:docstring> - Request the value of several contacts' aliases at once. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - <method name="GetAliases" tp:name-for-bindings="Get_Aliases"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts - </tp:docstring> - </arg> - <arg direction="out" type="a{us}" tp:type="Alias_Map" name="Aliases"> - <tp:docstring> - A dictionary mapping contact handles to aliases - </tp:docstring> - </arg> - <tp:docstring> - Request the value of several contacts' aliases at once. This SHOULD - only return cached aliases, falling back on the contact identifier - (i.e. the string corresponding to the handle) if none is present. Also - if there was no cached alias, a request SHOULD be started of which the - result is later signalled by - <tp:member-ref>AliasesChanged</tp:member-ref>. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - <method name="SetAliases" tp:name-for-bindings="Set_Aliases"> - <arg direction="in" name="Aliases" type="a{us}" tp:type="Alias_Map"> - <tp:docstring> - A dictionary mapping integer handles of contacts - to strings of the new alias to set. - </tp:docstring> - </arg> - <tp:docstring> - Request that the alias of the given contact be changed. Success will be - indicated by emitting an <tp:member-ref>AliasesChanged</tp:member-ref> - signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is - not set, this method will only ever succeed if the contact is the - user's own handle (as returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>). - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <tp:contact-attribute name="alias" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same string that would be returned by - <tp:member-ref>GetAliases</tp:member-ref> - (always present with some value, possibly the - same as Connection/contact-id, if information from the - Aliasing interface was requested) - </p> - </tp:docstring> - </tp:contact-attribute> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface on connections to support protocols where contacts have an - alias which they can change at will. Provides a method for the user to set - their own alias, and a signal which should be emitted when a contact's - alias is changed or first discovered.</p> - - <p>On connections where the user is allowed to set aliases for contacts and - store them on the server, the <tp:member-ref>GetAliasFlags</tp:member-ref> - method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the - <tp:member-ref>SetAliases</tp:member-ref> method may be called on contact - handles other than the user themselves.</p> - - <p>Aliases are intended to be used as the main displayed name for the - contact, where available.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Anonymity.xml b/qt4/spec/Connection_Interface_Anonymity.xml deleted file mode 100644 index 704263cb9..000000000 --- a/qt4/spec/Connection_Interface_Anonymity.xml +++ /dev/null @@ -1,165 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Anonymity" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Connection.Interface.Anonymity"> - <tp:added version="0.19.7">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface to support anonymity settings on a per-connection basis. - This defines what personal identifying information a remote contact - may or may not see. For example, GSM might use this for CLIR, while - SIP might use this for privacy service requests.</p> - </tp:docstring> - - <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u"> - <tp:docstring> - <p>Flags for the various types of anonymity modes. These modes are solely to - inform the CM of the desired anonymous settings. It is up to the - CM to determine whether the anonymity modes should be handled within - the CM itself, or whether the network that a CM might be talking to - should be enforcing anonymity.</p> - - <p>CMs MAY support only a subset of these modes, and specific - connections MAY support none at all.</p> - </tp:docstring> - - <tp:flag value="1" suffix="Client_Info"> - <tp:docstring> - <p>Obscure any information that provides user identification, - user-agent identification or personal details. Examples of this - information might be GSM CallerID, SIP from address, various - informational email headers, etc.</p> - - <p>The CM should scrub/replace any of this information before - passing messages or data onto the network. Note that a CM which - has the option of obscuring the information at the CM or privacy - service level would choose both (anonymity services are opaque - to clients of this interface).</p> - - <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. - If they are set, the CM MUST respect Client_Info and ignore - Show_Client_Info.</p> - </tp:docstring> - </tp:flag> - - <tp:flag value="2" suffix="Show_Client_Info"> - <tp:docstring> - <p>Explicitly request showing of client information. In connection - context, this can be used to override service default. In channel - context, this overrides connection anonymity modes.</p> - - <tp:rationale> - <p>In GSM, it's possible to have CLIR enabled by default, and - explicitly suppress CLIR for a single phone call.</p> - </tp:rationale> - - <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. - If they are set, the CM MUST respect Client_Info and ignore - Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info - in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate - its support for explicitly hiding and publicising client information. - </p> - </tp:docstring> - </tp:flag> - - <tp:flag value="4" suffix="Network_Info"> - <tp:docstring> - <p>Obscure any originating IP address information, contact URIs, - and anonymize all traffic involved with sending/receiving any - media streams or call content. - Examples of this include the "headers" portions of - <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as - well as the History-Info (described in - <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>) - for a SIP CM.</p> - - <p>This SHOULD have the effect of hiding address information from - the remote contact (ie, the contact cannot know what IP address - the session is originated from). Obviously the network still needs - to be able to route information between contacts, so this provides - no guarantees of what can be seen by intermediaries.</p> - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="SupportedAnonymityModes" type="u" access="read" - tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes"> - <tp:docstring> - The anonymity modes supported by the CM for this connection. Once - Connection.Status has moved to Connected, this property MUST NOT change. - </tp:docstring> - </property> - - <property name="AnonymityMandatory" type="b" access="readwrite" - tp:name-for-bindings="Anonymity_Mandatory" - tp:is-connection-parameter='yeah'> - <tp:docstring> - <p>This specifies whether or not the anonymity settings MUST be respected - by the CM and any intermediaries between the local and remote contacts. - If this is set to true but anonymity settings cannot be followed, then - the session MUST be denied with a - <code>org.freedesktop.Telepathy.Error.<tp:error-ref>WouldBreakAnonymity</tp:error-ref></code> - error. - Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref> - SHOULD also set this property first (rather than accepting the CM's - default value).</p> - </tp:docstring> - </property> - - <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" - access="readwrite" tp:name-for-bindings="Anonymity_Modes" - tp:is-connection-parameter='yeah'> - <tp:docstring> - <p>The currently enabled anonymity modes for the connection. Setting - has the effect of requesting new modes for the connection, and may - raise an error if the unsupported modes are set. Successfully changing - the modes will result in emission of - <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - An unsupported mode was supplied. Supported modes are specified - in the SupportedAnonymityModes property, and this should be - checked prior to setting AnonymityModes. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </property> - - <signal name="AnonymityModesChanged" - tp:name-for-bindings="Anonymity_Modes_Changed"> - <tp:docstring> - Emitted when the anonymity mode has changed. - </tp:docstring> - - <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags"> - <tp:docstring> - The new anonymity modes for this connection. - </tp:docstring> - </arg> - </signal> - - </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 deleted file mode 100644 index 3b9290e1d..000000000 --- a/qt4/spec/Connection_Interface_Avatars.xml +++ /dev/null @@ -1,516 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Avatars" 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: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.Connection.Interface.Avatars"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <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 - unique</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An opaque token chosen by the connection manager, representing - a particular avatar.</p> - - <tp:rationale> - <p>Because avatars can be relatively large images, most protocols - provide a way to detect whether an old avatar is still valid, - or whether an avatar has changed, without pushing the actual - avatar data to all clients.</p> - </tp:rationale> - - <p>The connection manager MUST choose these tokens in a way that - makes it highly unlikely that two different avatars with the same - connection manager and protocol will have the same token.</p> - - <tp:rationale> - <p>This means that clients MAY use the triple - (<tp:type>Connection_Manager_Name</tp:type>, - <tp:type>Protocol</tp:type>, avatar token) as a key for - their avatar cache. For instance, an avatar for a - telepathy-gabble Jabber contact might be stored in a file - .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.</p> - </tp:rationale> - - <p>For instance, some protocols (like XMPP) identify avatars by a - hash of the avatar data; in this case, the hash can be used as the - avatar token.</p> - - <p>Some protocols identify avatars by the timestamp of the last - change to the avatar; in these protocols it would be necessary for - the connection manager to encode both the timestamp and the - contact's identifier into the avatar token in order to ensure - uniqueness.</p> - - <p>This token SHOULD be kept short and reasonably suitable for use - in a filename, but MAY contain any UTF-8 character (so clients using - avatar tokens in filenames MUST be prepared to escape characters - that are not valid in filenames). Connection managers for protocols - where tokens would otherwise become inconveniently large or contain - many unsuitable characters SHOULD hash the identifying data to - generate the token.</p> - </tp:docstring> - </tp:simple-type> - - <tp:mapping name="Avatar_Token_Map"> - <tp:docstring>A dictionary whose keys are contact handles and whose - values are avatar tokens.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" tp:type="Avatar_Token" name="Token"/> - </tp:mapping> - - <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated"> - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact whose avatar has changed - </tp:docstring> - </arg> - <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s"> - <tp:docstring> - Unique token for their new avatar - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the avatar for a contact has been updated, or first - discovered on this connection. If the token differs from the token - associated with the client's cached avatar for this contact, the new - avatar should be requested with - <tp:member-ref>RequestAvatars</tp:member-ref>. - </tp:docstring> - </signal> - - <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved"> - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact whose avatar has been retrieved - </tp:docstring> - </arg> - <arg name="Token" tp:type="Avatar_Token" type="s"> - <tp:docstring> - The token corresponding to the avatar - </tp:docstring> - </arg> - <arg name="Avatar" type="ay"> - <tp:docstring> - An array of bytes containing the image data - </tp:docstring> - </arg> - <arg name="Type" type="s"> - <tp:docstring> - A string containing the image MIME type (eg image/jpeg), or empty if - unknown - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the avatar for a contact has been retrieved. - </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) - </tp:docstring> - </arg> - <arg direction="out" type="q" name="Min_Width"> - <tp:docstring> - The minimum image width in pixels - </tp:docstring> - </arg> - <arg direction="out" type="q" name="Min_Height"> - <tp:docstring> - The minimum image height in pixels - </tp:docstring> - </arg> - <arg direction="out" type="q" name="Max_Width"> - <tp:docstring> - The maximum image width in pixels, or 0 if there is no limit - </tp:docstring> - </arg> - <arg direction="out" type="q" name="Max_Height"> - <tp:docstring> - The maximum image height in pixels, or 0 if there is no limit - </tp:docstring> - </arg> - <arg direction="out" type="u" name="Max_Bytes"> - <tp:docstring> - The maximum image size in bytes, or 0 if there is no limit - </tp:docstring> - </arg> - <tp:docstring> - Get the required format of avatars on this connection. - </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.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <method name="GetAvatarTokens" tp:name-for-bindings="Get_Avatar_Tokens"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts - </tp:docstring> - </arg> - <arg direction="out" type="as" name="Tokens" tp:type="Avatar_Token[]"> - <tp:docstring> - An array of avatar tokens or empty strings (if no avatar is set) in the - 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. - - Using this method in new Telepathy clients is deprecated; use - <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead. - </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.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <method name="GetKnownAvatarTokens" - tp:name-for-bindings="Get_Known_Avatar_Tokens"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts - </tp:docstring> - </arg> - <arg direction="out" type="a{us}" name="Tokens" tp:type="Avatar_Token_Map"> - <tp:docstring> - A dictionary of handles mapped to avatar tokens, containing only - the known avatar tokens. - </tp:docstring> - </arg> - <tp:docstring> - Get the unique tokens for the given contacts' avatars. These tokens - can be persisted across connections, and should be used by the client - to check whether the avatars have been updated. For handles other than - the self handle, only tokens that are already known are returned; an - empty token means the given contact has no avatar. However, a CM must - always have the tokens for the self handle if one is set (even if it is - set to no avatar). On protocols where the avatar does not persist - between connections, a CM should omit the self handle from the returned - map until an avatar is explicitly set or cleared. - </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.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <method name="RequestAvatar" tp:name-for-bindings="Request_Avatar"> - <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact to request the avatar for - </tp:docstring> - </arg> - <arg direction="out" type="ay" name="Data"> - <tp:docstring> - An array of bytes containing the image data - </tp:docstring> - </arg> - <arg direction="out" type="s" name="MIME_Type"> - <tp:docstring> - A string containing the image MIME type (eg image/jpeg), or empty if - 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. - </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.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact does not currently have an avatar. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="RequestAvatars" tp:name-for-bindings="Request_Avatars"> - <arg direction="in" name="Contacts" type="au" - tp:type="Contact_Handle[]"> - <tp:docstring> - The contacts to retrieve avatars for - </tp:docstring> - </arg> - <tp:docstring> - Request avatars for a number of contacts. The - <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for - each avatar retrieved. If the handles are valid but retrieving an - avatar fails (for any reason, including the contact not having an - avatar) the AvatarRetrieved signal is not emitted for that contact. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="SetAvatar" tp:name-for-bindings="Set_Avatar"> - <arg direction="in" name="Avatar" type="ay"> - <tp:docstring> - An array of bytes representing the avatar image data - </tp:docstring> - </arg> - <arg direction="in" name="MIME_Type" type="s"> - <tp:docstring> - A string representing the image MIME type - </tp:docstring> - </arg> - <arg direction="out" type="s" name="Token" tp:type="Avatar_Token"> - <tp:docstring> - The string token of the new avatar - </tp:docstring> - </arg> - <tp:docstring> - Set a new avatar image for this connection. The avatar image must - respect the requirements obtained by - <tp:member-ref>GetAvatarRequirements</tp:member-ref>. - </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.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <method name="ClearAvatar" tp:name-for-bindings="Clear_Avatar"> - <tp:added version="0.15.0" /> - <tp:docstring> - Remove the avatar image for this connection. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same string that would be returned by - <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> - (omitted from the result if the contact's avatar token is not known, - present as an empty string if the contact is known not to have - an avatar). Unlike in the - <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> - method, the avatar tokens for the self handle aren't required to be - present. This attribute should not be used to determine whether or - not the Avatar needs to be set. - </p> - </tp:docstring> - </tp:contact-attribute> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for requesting avatars for contacts on a given connection, - receiving notification when avatars are changed, and publishing your own - avatar.</p> - - <p>Avatars are identified by a string, the <tp:type>Avatar_Token</tp:type>, - which represents a particular avatar. Tokens MUST be chosen by the - connection manager in such a way that the triple - (<tp:type>Connection_Manager_Name</tp:type>, <tp:type>Protocol</tp:type>, - <tp:type>Avatar_Token</tp:type>) uniquely identifies an avatar. - An empty token means that an avatar has not been set for this contact, and - a changed token implies the contact's avatar has changed, but the strings - should otherwise be considered opaque by clients.</p> - - <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> - to request the tokens for the - avatars of all the contacts it is interested in when it connects. The - avatars can then be requested using - <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts. Clients - should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and - request a new copy of - the avatar when a contacts' avatar token changes. Clients should cache the - token and data of each contact's avatar between connections, to avoid - repeatedly retrieving the same avatar.</p> - - <p>To publish an avatar, a client should use - <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets - the requirements returned by the - <tp:member-ref>GetAvatarRequirements</tp:member-ref> - function. On some protocols the avatar is stored on the server, so setting - the avatar is persistent, but on others it is transferred via a peer to - peer mechanism, so needs to be set every connection. Hence, on every - connection, clients should inspect the avatar token of the connection's - self handle using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; if - the self handle is not in the - returned map, the client should re-set the avatar. If the self handle's - avatar token is known, but the avatar has been changed locally since the - last connection, the client should upload the new avatar; if the avatar has - not changed locally, then the client should download the avatar from the - server if its token differs from the that of the local avatar.</p> - - <p>To remove the published avatar on protocols which have persistent avatars, - a client should use the <tp:member-ref>ClearAvatar</tp:member-ref> method. - This method can safely be used even if there is no avatar for this - connection.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Balance.xml b/qt4/spec/Connection_Interface_Balance.xml deleted file mode 100644 index 76f9040e9..000000000 --- a/qt4/spec/Connection_Interface_Balance.xml +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Balance" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009 Collabora Ltd.</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 - 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.Connection.Interface.Balance"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.19.0">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>In many real-time communication services the user can pay for certain - services, typically calls to the - <abbr title="Public Switched Telephone Network">PSTN</abbr>, - in advance. In (at least) Skype, it's possible to query the current - balance in a machine-readable way.</p> - </tp:docstring> - - <tp:struct name="Currency_Amount"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An amount of money in a specified currency. For example, - 3.21 British pounds would conventionally be represented by - (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>, - <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by - (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>, - <var>Currency</var> = <tt>"GBP"</tt>) in a service that records - balance in units of 0.001 pounds.</p> - - <p>As a special case, if <var>Amount</var> = <tt>0</tt>, - <var>Scale</var> = <tt>2**32 - 1</tt> (i.e. the largest possible - 32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this - indicates an unknown amount.</p> - </tp:docstring> - - <tp:member type="i" name="Amount"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The amount, expressed as a fixed-point number with decimal scale - defined by the <var>Scale</var> field; for instance, an - <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of - <tt>2</tt> represents 12.34 in the currency unit given by the - <var>Currency</var> field.</p> - </tp:docstring> - </tp:member> - <tp:member type="u" name="Scale"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The decimal scale for the fixed point value of the - <var>Amount</var> field, defining the number of rightmost decimal - digits from the integer value which form the fractional part of the - resulting currency value.</p> - - <p>As well as defining the interpretation of <var>Amount</var>, user - interfaces may use this value to determine the precision with which - to display the amount.</p> - </tp:docstring> - </tp:member> - <tp:member type="s" name="Currency"> - <tp:docstring> - The currency code represented by this amount, which SHOULD be an - international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>, - or <tt>"JPY"</tt> if possible. An empty string can be used to - indicate that the currency is not known. - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="AccountBalance" tp:name-for-bindings="Account_Balance" - access="read" type="(ius)" tp:type="Currency_Amount"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The user's balance on the account corresponding to this <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. - A negative amount may be possible on some services, and indicates - that the user owes money to the service provider.</p> - - <p>On initial connection, this property may have an unknown - value, represented by <var>Amount</var> = <tt>0</tt>, - <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit - unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p> - </tp:docstring> - </property> - - <signal name="BalanceChanged" tp:name-for-bindings="Balance_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the user's balance has changed.</p> - </tp:docstring> - - <arg name="Balance" type="(ius)" tp:type="Currency_Amount"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The new value of the <tp:member-ref>AccountBalance</tp:member-ref> - property.</p> - </tp:docstring> - </arg> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Capabilities.xml b/qt4/spec/Connection_Interface_Capabilities.xml deleted file mode 100644 index 8e5eb3357..000000000 --- a/qt4/spec/Connection_Interface_Capabilities.xml +++ /dev/null @@ -1,254 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.Capabilities"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connections where it is possible to know what channel - types may be requested before the request is made to the connection - object. Each capability represents a commitment by the connection - manager that it will ordinarily be able to create a channel when given - a request with the given type and handle.</p> - - <p>Capabilities pertain to particular contact handles, and represent - activities such as having a text chat or a voice call with the user. - The activities are represented by the D-Bus interface name of the - channel type for that activity.</p> - - <p>The generic capability flags are defined by - <tp:type>Connection_Capability_Flags</tp:type>.</p> - - <p>In addition, channel types may have type specific capability flags of - their own, which are described in the documentation for each channel - type.</p> - - <p>This interface also provides for user interfaces notifying the - connection manager of what capabilities to advertise for the user. This - is done by using the - <tp:member-ref>AdvertiseCapabilities</tp:member-ref> method, and deals - with the - interface names of channel types and the type specific flags pertaining - to them which are implemented by available client processes.</p> - </tp:docstring> - - <tp:changed version="0.17.8">Previously, this interface - also expressed capabilities of the connection itself, indicating what - sorts of channels could be requested (for instance, the ability to - open chatroom lists or chatrooms). However, this was never very - well-defined or consistent, and as far as we know it was never - implemented correctly. This usage is now deprecated.</tp:changed> - - <tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> - instead.</tp:deprecated> - <tp:changed version="0.19.8">Connection managers implementing - Capabilities MUST implement ContactCapabilities too.</tp:changed> - - <tp:flags name="Connection_Capability_Flags" - value-prefix="Connection_Capability_Flag" type="u"> - <tp:flag suffix="Create" value="1"> - <tp:docstring> - The given channel type and handle can be given to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> - to create a new channel of this type. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Invite" value="2"> - <tp:docstring> - The given contact can be invited to an existing channel of this type. - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:struct name="Capability_Pair" array-name="Capability_Pair_List"> - <tp:docstring>A pair (channel type, type-specific flags) as passed to - <tp:member-ref>AdvertiseCapabilities</tp:member-ref> on the - Capabilities interface.</tp:docstring> - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> - <tp:member type="u" name="Type_Specific_Flags"/> - </tp:struct> - - <tp:struct name="Contact_Capability" array-name="Contact_Capability_List"> - <tp:docstring>A struct (contact handle, channel type, generic flags, - type-specific flags) representing a capability posessed by a contact, - as returned by <tp:member-ref>GetCapabilities</tp:member-ref> on the - Capabilities interface.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> - <tp:member type="u" tp:type="Connection_Capability_Flags" - name="Generic_Flags"/> - <tp:member type="u" name="Type_Specific_Flags"/> - </tp:struct> - - <tp:struct name="Capability_Change" array-name="Capability_Change_List"> - <tp:docstring>A struct (contact handle, channel type, old generic flags, - new generic flags, old type-specific flags, new type-specific flags) - representing a change to one of a contact's capabilities, as seen in the - <tp:member-ref>CapabilitiesChanged</tp:member-ref> signal on the - Capabilities interface.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> - <tp:member type="u" tp:type="Connection_Capability_Flags" - name="Old_Generic_Flags"/> - <tp:member type="u" tp:type="Connection_Capability_Flags" - name="New_Generic_Flags"/> - <tp:member type="u" name="Old_Type_Specific_Flags"/> - <tp:member type="u" name="New_Type_Specific_Flags"/> - </tp:struct> - - <method name="AdvertiseCapabilities" - tp:name-for-bindings="Advertise_Capabilities"> - <arg direction="in" name="Add" type="a(su)" tp:type="Capability_Pair[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structures containing: - <ul> - <li>a string channel type</li> - <li>a bitwise OR of type specific capability flags</li> - </ul> - </tp:docstring> - </arg> - <arg direction="in" name="Remove" type="as" tp:type="DBus_Interface[]"> - <tp:docstring> - An array of D-Bus interface names of channel types to remove - </tp:docstring> - </arg> - <arg direction="out" type="a(su)" tp:type="Capability_Pair[]" - name="Self_Capabilities"> - <tp:docstring> - An array of structures describing the current capabilities containing: - <ul> - <li>a string channel type</li> - <li>a bitwise OR of type specific capability flags</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Used by user interfaces to indicate which channel types they are able - to handle on this connection. Because these may be provided by - different client processes, this method accepts channel types to add - and remove from the set already advertised on this connection. The type - of advertised capabilities (create versus invite) is protocol-dependent - and hence cannot be set by the this method. In the case of a client - adding an already advertised channel type but with new channel type - specific flags, the connection manager should simply add the new flags - to the set of advertised capabilities.</p> - - <p>Upon a successful invocation of this method, the - <tp:member-ref>CapabilitiesChanged</tp:member-ref> - signal will be emitted for the user's own handle ( <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>) - by the connection manager to indicate the changes - that have been made. This signal should also be monitored to ensure - that the set is kept accurate - for example, a client may remove - capabilities or type specific capability flags when it exits - which are still provided by another client.</p> - - <p>On connections managed by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>, - this method SHOULD NOT be used by clients other than the - ChannelDispatcher itself.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - - <signal name="CapabilitiesChanged" - tp:name-for-bindings="Capabilities_Changed"> - <arg name="Caps" type="a(usuuuu)" tp:type="Capability_Change[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structures containing: - <ul> - <li>an integer handle representing the contact</li> - <li>a string channel type</li> - <li>a bitwise OR of the contact's old generic capability flags</li> - <li>a bitwise OR of the contact's new generic capability flags</li> - <li>a bitwise OR of the contact's old type specific capability flags</li> - <li>a bitwise OR of the contact's new type specific capability flags</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Announce that there has been a change of capabilities on the - given handle.</p> - - <p>If the handle is zero, the capabilities refer to the connection - itself, in some poorly defined way. This usage is deprecated and - clients should ignore it.</p> - </tp:docstring> - </signal> - - <method name="GetCapabilities" tp:name-for-bindings="Get_Capabilities"> - <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of contact handles for this connection.</p> - - <p>This may include zero, which originally meant a query for - capabilities available on the connection itself. This usage - is deprecated; clients SHOULD NOT do this, and connection managers - SHOULD proceed as though zero had not been present in this - list.</p> - </tp:docstring> - </arg> - <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]" - name="Contact_Capabilities"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structures containing: - <ul> - <li>an integer handle representing the contact</li> - <li>a string channel type</li> - <li>a bitwise OR of generic capability flags for the type</li> - <li>a bitwise OR of type specific capability flags for the type</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - Returns an array of capabilities for the given contact handles. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - The handle does not represent a contact and is not zero - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <tp:contact-attribute name="caps" - type="a(usuu)" tp:type="Contact_Capability[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same structs that would be returned by - <tp:member-ref>GetCapabilities</tp:member-ref> - (all of them will redundantly have the contact's handle as the - first member). Omitted from the result if the contact's capabilities - are not known; present in the result as an empty array if the - contact is known to have no capabilities at all.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Cellular.xml b/qt4/spec/Connection_Interface_Cellular.xml deleted file mode 100644 index e9b10e3c5..000000000 --- a/qt4/spec/Connection_Interface_Cellular.xml +++ /dev/null @@ -1,157 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Cellular" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Connection.Interface.Cellular"> - <tp:added version="0.19.8">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface is for various cellular things (GSM and/or CDMA) that - aren't really applicable to other protocols.</p> - </tp:docstring> - - <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period" - type="u" access="readwrite" - tp:is-connection-parameter='yup'> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Define how long should the service centre try message delivery before - giving up, failing delivery and deleting the message. A value of 0 - means to use the service centre's default period.</p> - - <p>The value specified is in seconds. Note that various protocols or - implementations may round the value up (eg. to a minute or hour - precision). The maximum validity period may vary depending on - protocol or provider.</p> - </tp:docstring> - </property> - - <property name="OverrideMessageServiceCentre" - tp:name-for-bindings="Override_Message_Service_Centre" - type="b" access="readwrite" - tp:is-connection-parameter='can i get a hell yeah?'> - <tp:added version='0.19.12'>Previously, as an undocumented - feature, setting <tp:member-ref>MessageServiceCentre</tp:member-ref> - to the empty string caused the SIM's default SMSC to be used.</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <code>True</code>, SMSes will be sent via the service centre - specified by <tp:member-ref>MessageServiceCentre</tp:member-ref>. If - <code>False</code>, the SIM's default SMSC will be used, ignoring the - value of MessageServiceCentre.</p> - - <tp:rationale> - <p>It could be desirable for a configuration interface to remember - the user's previous choice of custom SMSC, even if it's not in use. - This boolean allows that choice to be saved as an account parameter - by Mission Control, rather than the UI needing to save it elsewhere - to be restored if the user wants to reactivate it.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre" - type="s" access="readwrite" - tp:is-connection-parameter='HELL YEAH!!!'> - <tp:changed version='0.19.12'>This property's value is now - ignored unless - <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is - <code>True</code>.</tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - - <p>Address for the messaging service centre. Typically (as is the case - for GSM's SMSC), it's the ISDN / telephony address (ie. a phone - number). If - <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is - <code>False</code>, this property's value should be ignored by the CM - in favour of the SIM's default SMSC.</p> - </tp:docstring> - </property> - - <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The International Mobile Subscriber Identifier, if it exists. This - would originate from a SIM card. If the IMSI is unknown, this will - contain an empty string ("").</p> - </tp:docstring> - </property> - - <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed"> - <tp:docstring> - Emitted when the IMSI for the connection changes. This sort of thing - is rare, but could happen on cellular phones that allow hot-swapping - of SIM cards. In the case of SIM swapping, this signal would be - emitted twice; the first time while the SIM is being ejected (with an - empty string), and the second time after a new SIM has been inserted - (assuming that the IMSI can be determined from the new SIM). - </tp:docstring> - - <arg name="IMSI" type="s"> - <tp:docstring> - The new IMSI value. This may be an empty string in the case where - the IMSI is being reset or removed. - </tp:docstring> - </arg> - </signal> - - <property name="MessageReducedCharacterSet" - tp:name-for-bindings="Message_Reduced_Character_Set" - type="b" access="readwrite" - tp:is-connection-parameter='no... just kidding! yes!'> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Determines how to encode SMSes containing characters that do not - fit into a non-Unicode character set. - If <code>False</code> (which SHOULD be the default), messages will - be encoded as UCS-2 and sent with no loss of fidelity (at the - potential financial cost of using twice as many SMSes); if - <code>True</code>, the message will be recoded in an - implementation‐specific way to fit into a GSM reduced character - set.</p> - </tp:docstring> - </property> - - <property name="MessageNationalCharacterSet" - tp:name-for-bindings="Message_National_Character_Set" - type="s" access="readwrite" - tp:is-connection-parameter='affirmative'> - <tp:added version="0.21.12"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Hint for the connection manager for the GSM character set that - should be used to send SMSes. The connection manager SHOULD follow - this hint unless it has other ways to determine a better encoding. - If the value is <code>"gsm"</code> (which SHOULD be the default), - SMSes will be encoded in the normal 7-bit GSM character set, - eventually falling back to UCS-2; see the - <tp:member-ref>MessageReducedCharacterSet</tp:member-ref> property - for details. - Other valid character sets are specified in the - <a href="http://www.3gpp.org/ftp/specs/archive/23_series/23.038/" - >GSM standard</a> and are, for instance, <code>"turkey"</code>, - <code>"spain"</code> or <code>"portugal"</code>. - If the SMS cannot be encoded using the requested character set the - behaviour is implementation-specific, but it is RECOMMENDED that - the connection manager should behave as if this property was set - to <code>"gsm"</code>.</p> - </tp:docstring> - </property> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Client_Types.xml b/qt4/spec/Connection_Interface_Client_Types.xml deleted file mode 100644 index 97908561a..000000000 --- a/qt4/spec/Connection_Interface_Client_Types.xml +++ /dev/null @@ -1,218 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Client_Types" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2010 Collabora Ltd.</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.Connection.Interface.ClientTypes"> - <tp:added version="0.21.1">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface on connections to support protocols which allows users to - subscribe to the client types of their contacts.</p> - - <p>One can connect to instant messaging networks on a huge variety of - devices, from PCs, to phones to consoles. It can be useful for users - to know what kind of device a contact is using so that he or she - can decide not to send that big file or start a video chat. This - interface exposes exactly this information for clients to display.</p> - - <p>The client types are represented in strings, using the values - <a href="http://xmpp.org/registrar/disco-categories.html#client"> - documented by the XMPP registrar</a> with some additional types - added for other protocols. A contact can set one or more client types - so this interface returns a list of strings to denote client types - for a contact. The well-known client types to be used are:</p> - - <ul> - <li>bot</li> - <li>console (minimal non-GUI client used on dumb terminals or - text-only screens, <strong>not</strong> a games console)</li> - <li>handheld</li> - <li>pc</li> - <li>phone</li> - <li>web</li> -<!-- Excluding these two because there's been no conclusion regarding my mail - to standards@xmpp.org about adding these two to their list: - - <li>sms (the client is not actually an instant messaging client - but all messages sent to this contact will be delivered as SMSs)</li> - <li>game (a gaming device)</li> ---> - </ul> - - <p>If the empty list is given as the client types, this means that - details about the contact's client types are unknown. If there are - multiple resources of a contact online at one point in time, the - client types of the most available resource will be returned. In - other words, the returned client types are those for the resource whose - presence will be retreived using the - <tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref> - interface.</p> - - <p>For example, if a contact has two resources:</p> - - <ul> - <li>their phone, with presence "available"; and</li> - <li>their pc, with presence "busy";</li> - </ul> - - <p>then the methods in this interface will return an array (with - one element: "phone") as the client types because that is the more - available resource. If at some later time the contact's phone's presence - changes to "away", the - <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will - notify that the contact's client types attribute has changed from - ["phone"] to ["pc"], - because "busy" is a more available presence than "away".</p> - - </tp:docstring> - - <tp:mapping name="Contact_Client_Types"> - <tp:docstring> - A mapping from contact handle to client types. - </tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Contact"> - <tp:docstring> - A contact. - </tp:docstring> - </tp:member> - <tp:member type="as" name="Client_Types" tp:type="Contact_Client_Type[]"> - <tp:docstring> - The contact's client types as documented earlier in this interface. - </tp:docstring> - </tp:member> - </tp:mapping> - - <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types"> - <tp:docstring> - Return the client types of the given contacts, if they are - already known. If any of the given contacts' client types are - not known, request their current client types, but return - immediately without waiting for a reply; if a reply with a - non-empty client type array is later received for those - contacts, the - <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will - be emitted for them. - - <tp:rationale> - This method is appropriate for "lazy" client type finding, for instance - displaying the client types (if available) of everyone in your contact - list. - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The contacts whose client types should be returned or signalled. - </tp:docstring> - </arg> - - <arg direction="out" name="Client_Types" type="a{uas}" - tp:type="Contact_Client_Types"> - <tp:docstring> - The contacts' client types, if already known. Contacts whose client - types are not already known are omitted from the mapping; contacts known - to have no client type information appear in the mapping with an empty - list. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="RequestClientTypes" tp:name-for-bindings="Request_Client_Types"> - <tp:docstring> - Return the current client types of the given contact. If necessary, make - a request to the server for up-to-date information, and wait for a - reply. - - <tp:rationale> - This method is appropriate for use in a "Contact Information..." - dialog; it can be used to show progress information (while waiting - for the method to return), and can distinguish between various error - conditions. - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact whose client types should be returned. - </tp:docstring> - </arg> - - <arg direction="out" name="Client_Types" type="as" - tp:type="Contact_Client_Type[]"> - <tp:docstring> - The contact's client types. It MAY be empty, indicating that no client - type information was found. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> - <tp:docstring> - The requested contact does not allow the local user to see their - client type information. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated"> - <tp:docstring> - Emitted when a contact's client types change or become known. - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact. - </tp:docstring> - </arg> - <arg name="Client_Types" type="as" tp:type="Contact_Client_Type[]"> - <tp:docstring> - The contact's client types, or an empty list to indicate that nothing - is known about the contact's client types. - </tp:docstring> - </arg> - </signal> - - <tp:contact-attribute name="client-types" type="as" - tp:type="Contact_Client_Type[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same mapping that would be returned by - <tp:member-ref>GetClientTypes</tp:member-ref> for this contact. - Omitted from the result if the contact's client types are not - known.</p> - </tp:docstring> - </tp:contact-attribute> - - <tp:simple-type name="Contact_Client_Type" type="s" - array-name="Contact_Client_Type_List"> - <tp:docstring>A string representing a single client type of a - contact.</tp:docstring> - </tp:simple-type> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Communication_Policy.xml b/qt4/spec/Connection_Interface_Communication_Policy.xml deleted file mode 100644 index 31343de68..000000000 --- a/qt4/spec/Connection_Interface_Communication_Policy.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Communication_Policy" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> -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. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details. - -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. - </tp:license> - - <interface - name="org.freedesktop.Telepathy.Connection.Interface.CommunicationPolicy.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.1">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - This interface supports controlling which contacts are allowed - to initiate text chats, incoming calls, and other forms of - communication as supported by the underlying protocol. The - policies supported for different communication methods on this - connection are listed in the - <tp:member-ref>SupportedPolicies</tp:member-ref> property. The - current configuration is held in - <tp:member-ref>ActivePolicies</tp:member-ref>; it can be modified - using <tp:member-ref>SetPolicy</tp:member-ref>, and changes - are signalled by <tp:member-ref>PolicyChanged</tp:member-ref>. - </p> - </tp:docstring> - - <tp:mapping name="Active_Policies_Map"> - <tp:docstring> - A mapping of communication methods (channel types), and their - associated policy. - </tp:docstring> - - <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"> - <tp:docstring> - The channel interface with the policy. - </tp:docstring> - </tp:member> - - <tp:member type="(uv)" tp:type="Access_Control" name="Active_Policy"> - <tp:docstring> - The active policy for this channel type. - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="SupportedPolicies" - tp:name-for-bindings="Supported_Policies" access="read" - type="a(asau)" tp:type="Supported_Policy[]"> - <tp:docstring> - The communication policies supported by this connection. - </tp:docstring> - </property> - - <property name="ActivePolicies" tp:name-for-bindings="Active_Policies" - access="read" type="a{s(uv)}" tp:type="Active_Policies_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The active communication policies on this - connection. Communication methods that are not in this - mapping are considered open.</p> - - <p>For example, to allow incoming calls only from contacts - buddy list, and to allow text messages from anyone, - the policy would look like this:</p> - - <pre> -{ - 'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open, - 'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List -} - </pre> - - <p>Changes to this property are signalled by - <tp:member-ref>PolicyChanged</tp:member-ref>.</p> - </tp:docstring> - </property> - - <method name="SetPolicy" tp:name-for-bindings="Set_Policy"> - <tp:docstring> - Set a policy for a communication method (channel - type). Depending on the server or protocol, more than one - communication method could be bound to the same policy, if - calling this method on one channel type changes the policy on - another channel type, the <tp:member-ref>PolicyChanged</tp:member-ref> - signal that would follow would include all the channel types - that have an altered policy. - </tp:docstring> - <arg name="Channel_Type" direction="in" type="s" - tp:type="DBus_Interface"> - <tp:docstring> - The channel type to set the policy for. - </tp:docstring> - </arg> - <arg name="Policy" direction="in" type="(uv)" - tp:type="Access_Control"> - <tp:docstring> - The policy to set for this channel. - </tp:docstring> - </arg> - </method> - - <signal name="PolicyChanged" tp:name-for-bindings="Policy_Changed"> - <tp:docstring> - <tp:member-ref>ActivePolicies</tp:member-ref> has - changed. This occurs when the server unilaterally changed the - policy or <tp:member-ref>SetPolicy</tp:member-ref> has been - called. - </tp:docstring> - <arg name="Changed_Policies" type="a{s(uv)}" - tp:type="Active_Policies_Map"> - <tp:docstring> - A subset of the active policies that have changed. - </tp:docstring> - </arg> - </signal> - - <tp:struct name="Supported_Policy" array-name="Supported_Policy_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The communication methods (channel types), and the policies - that can be applied to them. This is server and protocol - dependant.</p> - - <p>Grouped channel types will always have the same policy applied - to them.</p> - - <tp:rationale> - Different protocols have different limitations to the - granularity of communication policies. One protocol might be - able to set a different policy for VoIP calls and text chat, - while another protocol might only be able to set one policy - to both VoIP and text chat. - </tp:rationale> - </tp:docstring> - <tp:member type="as" tp:type="DBus_Interface[]" - name="Channel_Types"> - <tp:docstring> - A list of channel interfaces that support these policies. - </tp:docstring> - </tp:member> - <tp:member type="au" tp:type="Access_Control_Type[]" - name="Supported_Policies"> - <tp:docstring> - A list of supported policies. - </tp:docstring> - </tp:member> - </tp:struct> - - </interface> -</node> diff --git a/qt4/spec/Connection_Interface_Contact_Blocking.xml b/qt4/spec/Connection_Interface_Contact_Blocking.xml deleted file mode 100644 index 756fd4db8..000000000 --- a/qt4/spec/Connection_Interface_Contact_Blocking.xml +++ /dev/null @@ -1,207 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009–2011 Collabora Ltd.</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 - 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.Connection.Interface.ContactBlocking"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/> - <tp:added version='0.21.13'>Changes from the draft: - methods and signals now return <tp:type>Handle_Identifier_Map</tp:type> - (<code>a{us}</code>) rather than bare lists of contact handles - (<code>au</code>)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connections where contacts can be blocked from - communicating with this user and receiving this user's presence. - Clients may retrieve a list of currently-blocked contacts using - <tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for - <tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified - when contacts are blocked and unblocked. The - <tp:member-ref>BlockContacts</tp:member-ref> and - <tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say - on the tin; depending on the value of the - <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property, - contacts may be reported for spam or other abuse when calling - <tp:member-ref>BlockContacts</tp:member-ref>.</p> - - <p>This interface is intended for protocols where blocking contacts - persists on the server between connections; connection managers for - protocols with no server-side support for blocking contacts MAY choose - to implement this interface using an on-disk file of blocked - contacts or some other means to store blocked contacts between - connections.</p> - - <p>This interface is intended to replace the - <tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref> - channel with <tp:dbus-ref - namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> - <code>List</code> and <tp:dbus-ref - namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code> - (along with the <tp:dbus-ref - namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and - <tp:dbus-ref - namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref> - interfaces replacing other channels with <tp:dbus-ref - namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> - <code>List</code> and <tp:dbus-ref - namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> - <code>Group</code>, respectively).</p> - </tp:docstring> - - <method name="BlockContacts" tp:name-for-bindings="Block_Contacts"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Direct the server to block some contacts. The precise effect is - protocol-dependent, but SHOULD include ignoring all current and - subsequent communications from the given contacts, avoiding sending - presence to them in future, and if they were already receiving the - local user's presence, behaving as if the local user went - offline.</p> - </tp:docstring> - - <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]"> - <tp:docstring>Some contacts to block. If some of the contacts in this - list are already blocked, the connection manager MUST act as if they - were not specified in this list.</tp:docstring> - </arg> - - <arg name="Report_Abusive" type="b" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>In addition to blocking, report these contacts as abusive to the - server administrators.</p> - - <p>Clients can determine whether this capability is available by - checking the - <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> - property. If this argument is set to <code>True</code> by a client - despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> - not containing the <code>Can_Report_Abusive</code> flag, the - connection manager SHOULD act as if it were <code>False</code> and - simply block the supplied contacts.</p> - - <tp:rationale> - <p>A correct user interface shouldn't get this far without knowing - that reporting abusive contacts is not supported. If it does, - then the user has expressed their intention to block these - contacts. Returning an error would leave the UI with three - options:</p> - - <ul> - <li>Ignore the error, leaving the contacts not actually blocked;</li> - <li>Display an error to the user;</li> - <li>Call this method again, passing <code>False</code> for this - argument.</li> - </ul> - - <p>None of these seem preferable to the CM just ignoring this flag - if it doesn't support it: that way, the contacts will be blocked, - as the user requested, and UIs have fewer ways to mess up - entirely.</p> - </tp:rationale> - </tp:docstring> - </arg> - </method> - - <method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Direct the server to unblock some contacts.</p> - </tp:docstring> - - <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]"> - <tp:docstring>Some contacts to unblock. If some of the contacts in this - list are not currently blocked, the connection manager MUST act as if - they were not specified in this list.</tp:docstring> - </arg> - </method> - - <method name="RequestBlockedContacts" - tp:name-for-bindings="Request_Blocked_Contacts"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>List the contacts that are blocked.</p> - - <p>Clients SHOULD allow a relatively long timeout for calls to this - method, since on some protocols contact blocking is part of the - contact list, which can take a significant time to retrieve.</p> - </tp:docstring> - - <arg name="Contacts" type="a{us}" direction="out" - tp:type="Handle_Identifier_Map"> - <tp:docstring>The blocked contacts’ handles, together with their - identifiers.</tp:docstring> - </arg> - </method> - - <signal name="BlockedContactsChanged" - tp:name-for-bindings="Blocked_Contacts_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the list of blocked contacts is first retrieved - (before returning from any pending calls to - <tp:member-ref>RequestBlockedContacts</tp:member-ref>), and - whenever the list of blocked contacts subsequently changes.</p> - </tp:docstring> - - <arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map"> - <tp:docstring>Contacts added to the result of - <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring> - </arg> - - <arg name="Unblocked_Contacts" type="a{us}" - tp:type="Handle_Identifier_Map"> - <tp:docstring>Contacts removed from the result of - <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring> - </arg> - </signal> - - <tp:contact-attribute name="blocked" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p><code>True</code> if the contact would be in the result of - <tp:member-ref>RequestBlockedContacts</tp:member-ref>; - <code>False</code> or omitted if the contact is not blocked, or if it - is unknown whether the contact is blocked.</p> - </tp:docstring> - </tp:contact-attribute> - - <property name="ContactBlockingCapabilities" - tp:name-for-bindings="Contact_Blocking_Capabilities" - tp:type="Contact_Blocking_Capabilities" type="u" access="read" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional capabilities for contact blocking; currently, this is - limited to whether contacts may be reported as abusive.</p> - - <p>Note that there is no capability for supporting blocking itself: - the presence of this interface on a <tp:dbus-ref - namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking - contacts is supported.</p> - </tp:docstring> - </property> - - <tp:flags name="Contact_Blocking_Capabilities" type="u" - value-prefix="Contact_Blocking_Capability"> - <tp:flag suffix="Can_Report_Abusive" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - When calling <tp:member-ref>BlockContacts</tp:member-ref>, the - contacts may be reporting as abusive to the server administrators by - setting <var>Report_Abusive</var> to <code>True</code>. - </tp:docstring> - </tp:flag> - </tp:flags> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Contact_Capabilities.xml b/qt4/spec/Connection_Interface_Contact_Capabilities.xml deleted file mode 100644 index fb13c37d7..000000000 --- a/qt4/spec/Connection_Interface_Contact_Capabilities.xml +++ /dev/null @@ -1,306 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006, 2008 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006, 2008 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.ContactCapabilities"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.17.28">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Contact capabilities describe the channel classes which may be - created with a given contact in advance of attempting to create a - channel. Each capability represents a commitment by the - connection manager that it will ordinarily be able to create a channel - with a contact when given a request with the properties defined by the - channel class.</p> - - <p>Capabilities pertain to particular contact handles, and represent - activities such as having a text chat, a voice call with the user or a - stream tube of a defined type.</p> - - <p>This interface also enables user interfaces to notify the connection - manager what capabilities to advertise for the user to other contacts. - This is done by using the - <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p> - - <tp:rationale> - <p>XMPP is a major user of this interface: XMPP contacts will not, - in general, be callable using VoIP unless they advertise suitable - Jingle capabilities.</p> - - <p>Many other protocols also have some concept of capability flags, - which this interface exposes in a protocol-independent way.</p> - </tp:rationale> - </tp:docstring> - - <tp:struct name="Handler_Capabilities" - array-name="Handler_Capabilities_List"> - <tp:docstring> - A structure representing the capabilities of a single client. - </tp:docstring> - - <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name"> - <tp:docstring> - For implementations of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Client</tp:dbus-ref> - interface, the well-known bus name name of the client; for any other - process, any other reversed domain name that uniquely identifies it. - </tp:docstring> - </tp:member> - - <tp:member name="Channel_Classes" type="aa{sv}" - tp:type="String_Variant_Map[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of channel classes that can be handled by this client. - This will usually be a copy of the client's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - property. - </tp:docstring> - </tp:member> - - <tp:member name="Capabilities" - type="as" tp:type="Handler_Capability_Token[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of client capabilities supported by this client, to be - used by the connection manager to determine what capabilities to - advertise. This will usually be a copy of the client's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> - property. - </tp:docstring> - </tp:member> - </tp:struct> - - <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Alter the connection's advertised capabilities to include - the intersection of the given clients' capabilities with what the - connection manager is able to implement.</p> - - <p>On connections managed by the ChannelDispatcher, processes other - than the ChannelDispatcher SHOULD NOT call this method, and the - ChannelDispatcher SHOULD use this method to advertise the - capabilities of all the registered <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref> - implementations.On connections not managed by the ChannelDispatcher, - clients MAY use this method directly, to indicate the channels they - will handle and the extra capabilities they have.</p> - - <p>Upon a successful invocation of this method, the connection manager - will only emit the - <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal - for the user's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">SelfHandle</tp:dbus-ref> - if, in the underlying protocol, the new capabilities are distinct - from the previous state.</p> - - <tp:rationale> - <p>The connection manager will essentially intersect the provided - capabilities and the channel classes it implements. Therefore, - certain properties which are never fixed for a channel class - (such as the target handle, or the Parameters property of a tube - channel) will almost certainly not be advertised.</p> - </tp:rationale> - - <p>This method MAY be called on a newly-created connection while it - is still in the DISCONNECTED state, to request that when the - connection connects, it will do so with the appropriate - capabilities. Doing so MUST NOT fail.</p> - </tp:docstring> - - <arg direction="in" name="Handler_Capabilities" type="a(saa{sv}as)" - tp:type="Handler_Capabilities[]"> - <tp:docstring> - <p>The capabilities of one or more clients.</p> - - <p>For each client in the given list, any capabilities previously - advertised for the same client name are discarded, then replaced by - the capabilities indicated.</p> - - <p>As a result, if a client becomes unavailable, this method SHOULD - be called with a <tp:type>Handler_Capabilities</tp:type> structure - containing its name, an empty list of channel classes, and an - empty list of capabilities. When this is done, the connection - manager SHOULD free all memory associated with that client name.</p> - - <tp:rationale> - <p>This method takes a list of clients so that - when the channel dispatcher first calls it (with a list of all - the Handlers that are initially available), the changes can be - made atomically, with only one transmission of updated - capabilities to the network. Afterwards, the channel dispatcher - will call this method with a single-element list every time - a Handler becomes available or unavailable.</p> - </tp:rationale> - - <p>The connection manager MUST ignore any channel classes and client - capabilities for which there is no representation in the protocol - or no support in the connection manager.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - - <method name="GetContactCapabilities" - tp:name-for-bindings="Get_Contact_Capabilities"> - <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of contact handles for this connection.</p> - - <p>The handle zero MUST NOT be included in the request.</p> - </tp:docstring> - </arg> - <arg direction="out" type="a{ua(a{sv}as)}" - tp:type="Contact_Capabilities_Map" name="Contact_Capabilities"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from contact handles to lists of requestable channel - classes, representing the channel requests that are expected - to succeed for that contact.</p> - - <p>Contacts listed among Handles whose capabilities are unknown - SHOULD be omitted from this map; contacts known to have an empty - set of capabilities SHOULD be included in the keys of this map, - with an empty array as the corresponding value.</p> - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Returns an array of requestable channel classes for the given - contact handles, representing the channel requests that are - expected to succeed.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - The handle does not represent a contact. Zero is always invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="ContactCapabilitiesChanged" - tp:name-for-bindings="Contact_Capabilities_Changed"> - <arg name="caps" type="a{ua(a{sv}as)}" - tp:type="Contact_Capabilities_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - All the capabilities of the contacts - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Announce that there has been a change of capabilities on the - given handles. A single signal can be emitted for several - contacts.</p> - - <tp:rationale> - <p>The underlying protocol can get several contacts' capabilities at - the same time.</p> - </tp:rationale> - - </tp:docstring> - </signal> - - <tp:mapping name="Contact_Capabilities_Map" - array-name="Contact_Capabilities_Map_List"> - <tp:docstring>A mapping from contact handle to their capabilities. - </tp:docstring> - <tp:member type="u" name="Key" tp:type="Contact_Handle"> - <tp:docstring> - A contact handle. - </tp:docstring> - </tp:member> - <tp:member type="a(a{sv}as)" name="Value" - tp:type="Requestable_Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contact's capabilities. These should be represented - in the same way as in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref>, - except that they may have more fixed properties or fewer allowed - properties, to represent contacts who do not have all the - capabilities of the connection.</p> - - <p>In particular, requestable channel classes for channels with - target handle type Contact MUST list <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >TargetHandleType</tp:dbus-ref> among their fixed properties when - they appear here, and clients MAY assume that this will be the - case.</p> - - <tp:rationale> - <p>This matches the initial implementations - service-side in - telepathy-gabble, and client-side in telepathy-qt4 - and means - that clients can use exactly the same code to interpret - RequestableChannelClasses and contact capabilities.</p> - </tp:rationale> - - <p>Channel classes with target handle type Handle_Type_Contact - indicate that a request that matches the channel class, and also - either has the contact's handle as <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel" - >TargetHandle</tp:dbus-ref> or the contact's identifier as - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" - >TargetID</tp:dbus-ref>, can be expected to succeed. Connection - managers SHOULD NOT include the TargetHandle or TargetID as a - fixed property in contact capabilities.</p> - - <tp:rationale> - <p>This makes one channel class sufficient to describe requests via - TargetHandle or TargetID, and is necessary in order to allow - clients to interpret RequestableChannelClasses and contact - capabilities with the same code.</p> - </tp:rationale> - - <p>Channel classes with target handle type Handle_Type_Room or - Handle_Type_None indicate that if a channel matching the channel - class is created, then inviting the contact to that channel - can be expected to succeed.</p> - - <tp:rationale> - <p>To support room-based XMPP protocols like - <a href="http://telepathy.freedesktop.org/wiki/Muji">Muji</a> - and MUC Tubes, it's necessary to be able to discover who can be - invited to a given room channel; most XMPP contacts won't - support being invited into a Muji conference call, at least - in the short to medium term.</p> - </tp:rationale> - - <p>No interpretation is defined for channel classes with any other - target handle type, or for channel classes that do not fix a - target handle type, in this version of the Telepathy - specification.</p> - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:contact-attribute name="capabilities" - type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same structs that would be returned by - <tp:member-ref>GetContactCapabilities</tp:member-ref>. - Omitted from the result if the contact's capabilities - are not known; present in the result as an empty array if the - contact is known to have no capabilities at all.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Contact_Groups.xml b/qt4/spec/Connection_Interface_Contact_Groups.xml deleted file mode 100644 index 5282a8272..000000000 --- a/qt4/spec/Connection_Interface_Contact_Groups.xml +++ /dev/null @@ -1,549 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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 - 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.Connection.Interface.ContactGroups"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/> - <tp:added version="0.21.0">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connections in which contacts can be placed in - user-defined groups.</p> - - <p>The most basic functionality of this interface is to list and monitor - a contact's set of groups. To do this, use the - <tp:member-ref>GroupsChanged</tp:member-ref> signal, and the - <tp:token-ref>groups</tp:token-ref> contact attribute (this should - usually be done by connecting to the GroupsChanged signal, then - calling <tp:dbus-ref - namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref> with this interface - included in the Interfaces argument). Simple user interfaces can - limit themselves to displaying that information, and ignore the rest - of this interface: to ensure that this works, - <tp:member-ref>GroupsChanged</tp:member-ref> is emitted for every - change, even if that change could be inferred from another signal - such as <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> - - <p>Looking at contacts' lists of groups is sufficient to present a - user interface resembling XMPP's data model, in which groups behave - like tags applied to contacts, and so an empty group cannot exist - or is not interesting. However, some protocols model groups as - objects in their own right. User interfaces may either track - the set of groups via the <tp:member-ref>Groups</tp:member-ref> - property and the <tp:member-ref>GroupsCreated</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref> signals, or ignore - this extra information.</p> - - <p>Similarly, in some protocols it is possible to rename a group as - a single atomic operation. Simpler user interfaces will - see the new name being created, the old name being removed, and the - members moving to the new name, via the signals described above. - More advanced user interfaces can optionally distinguish between an - atomic rename and a create/remove pair, and display renamed groups - differently, by monitoring the - <tp:member-ref>GroupRenamed</tp:member-ref> signal.</p> - - <p>This interface also provides various methods to manipulate - user-defined groups, which can be expected to work if - <tp:member-ref>GroupStorage</tp:member-ref> is not None.</p> - - <p>Depending on the protocol, some methods might be implemented by - more than one protocol operation; for instance, in a - "contact-centric" protocol like XMPP, - <tp:member-ref>SetContactGroups</tp:member-ref> is a single - protocol operation and <tp:member-ref>SetGroupMembers</tp:member-ref> - requires a protocol operation per contact, whereas in a more - "group-centric" protocol it might be the other way around. User - interfaces SHOULD call whichever method most closely resembles the - way in which the user's action was represented in the UI, and - let the connection manager deal with the details.</p> - </tp:docstring> - - <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups" - access="read" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if each contact can be in at most one group; false if each - contact can be in many groups.</p> - - <p>This property cannot change after the connection has moved to the - Connected state. Until then, its value is undefined, and it may - change at any time, without notification.</p> - </tp:docstring> - </property> - - <property name="GroupStorage" tp:name-for-bindings="Group_Storage" - type="u" tp:type="Contact_Metadata_Storage_Type" access="read"> - <tp:docstring> - <p>Indicates the extent to which contacts' groups can be set and - stored.</p> - - <p>This property cannot change after the connection has moved to the - Connected state. Until then, its value is undefined, and it may - change at any time, without notification.</p> - </tp:docstring> - </property> - - <tp:contact-attribute name="groups" type="as"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The names of groups of which a contact is a member.</p> - - <p>Change notification is via - <tp:member-ref>GroupsChanged</tp:member-ref>; clients can also - get extra context for group membership changes by receiving - <tp:member-ref>GroupRenamed</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> - </tp:docstring> - </tp:contact-attribute> - - <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed"> - <tp:docstring> - Emitted when contacts' groups change. - </tp:docstring> - - <arg name="Contact" type="au" tp:type="Contact_Handle"> - <tp:docstring>The relevant contacts.</tp:docstring> - </arg> - - <arg name="Added" type="as"> - <tp:docstring>The names of groups to which the contacts were - added.</tp:docstring> - </arg> - - <arg name="Removed" type="as"> - <tp:docstring>The names of groups from which the contacts were - removed.</tp:docstring> - </arg> - </signal> - - <property name="Groups" type="as" access="read" - tp:name-for-bindings="Groups"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The names of all groups that currently exist. This may be a - larger set than the union of all contacts' <code>groups</code> - contact attributes, if the connection allows groups to be - empty.</p> - - <p>Change notification is via - <tp:member-ref>GroupsCreated</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref>; clients can also - distinguish between a create/remove pair and a renamed group by - receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p> - - <p>This property's value is not meaningful until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> has become Success.</p> - </tp:docstring> - </property> - - <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created"> - <tp:docstring> - Emitted when new, empty groups are created. This will often be - followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that - add some members. - </tp:docstring> - - <arg name="Names" type="as"> - <tp:docstring>The names of the new groups.</tp:docstring> - </arg> - </signal> - - <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a group is renamed, in protocols where this can - be distinguished from group creation, removal and membership - changes.</p> - - <p>Immediately after this signal is emitted, - <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the - creation of a group with the new name, and - <tp:member-ref>GroupsRemoved</tp:member-ref> MUST signal the - removal of a group with the old name.</p> - - <tp:rationale> - <p>Emitting these extra signals, in this order, means that clients - that are interested in the set of groups that exist (but treat a - rename and a create/remove pair identically) can ignore the - GroupRenamed signal entirely.</p> - </tp:rationale> - - <p>If the group was not empty, immediately after those signals are - emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal - that the members of that group were removed from the old name - and added to the new name.</p> - - <p>On connection managers where groups behave like tags, renaming a - group MAY be signalled as a set of - <tp:member-ref>GroupsCreated</tp:member-ref>, - <tp:member-ref>GroupsRemoved</tp:member-ref> and - <tp:member-ref>GroupsChanged</tp:member-ref> signals, instead of - emitting this signal.</p> - - <tp:rationale> - <p>On protocols like XMPP, another resource "renaming a group" is - indistinguishable from changing contacts' groups individually.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Old_Name" type="s"> - <tp:docstring>The old name of the group.</tp:docstring> - </arg> - - <arg name="New_Name" type="s"> - <tp:docstring>The new name of the group.</tp:docstring> - </arg> - </signal> - - <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when one or more groups are removed. If they had members at - the time that they were removed, then immediately after this signal - is emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal - that their members were removed.</p> - - <tp:rationale> - <p>Emitting the signals in this order allows for two modes of - operation. A client interested only in a contact's set of groups - can ignore <tp:member-ref>GroupsRemoved</tp:member-ref> and rely - on the <tp:member-ref>GroupsChanged</tp:member-ref> signal that - will follow; a more elaborate client wishing to distinguish between - all of a group's members being removed, and the group itself - being removed, can additionally watch for - <tp:member-ref>GroupsRemoved</tp:member-ref> and use it to - disambiguate.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Names" type="as"> - <tp:docstring>The names of the groups.</tp:docstring> - </arg> - </signal> - - <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Add the given contact to the given groups (creating new groups - if necessary), and remove them from all other groups.</p> - - <tp:rationale> - <p>This is the easiest and most correct way to implement user - interfaces that display a single contact with a list of groups, - resulting in a user expectation that when they apply the changes, - the contact's set of groups will become exactly what was - displayed.</p> - </tp:rationale> - - <p>If the user is removed from a group of which they were the only - member, the group MAY be removed automatically.</p> - - <tp:rationale> - <p>In protocols like XMPP where groups behave like tags, a group - with no members has no protocol representation.</p> - </tp:rationale> - - <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, - <tp:member-ref>GroupsChanged</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> - <tp:docstring>The contact to alter.</tp:docstring> - </arg> - - <arg name="Groups" type="as" direction="in"> - <tp:docstring>The set of groups which the contact should be - in.</tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref> - is true and the list of groups has more than one - member.</tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Add the given members to the given group (creating it if necessary), - and remove all other members.</p> - - <tp:rationale> - <p>This is the easiest and most correct way to implement user - interfaces that display a single group with a list of contacts, - resulting in a user expectation that when they apply the changes, - the groups's set of members will become exactly what was - displayed.</p> - </tp:rationale> - - <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, - this will also remove each member from their previous group.</p> - - <p>If the user is removed from a group of which they were the only - member, the group MAY be removed automatically.</p> - - <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, - <tp:member-ref>GroupsChanged</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Group" type="s" direction="in"> - <tp:docstring>The group to alter.</tp:docstring> - </arg> - - <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> - <tp:docstring>The set of members for the group. If this set is - empty, this method MAY remove the group.</tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - <method name="AddToGroup" tp:name-for-bindings="Add_To_Group"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Add the given members to the given group, creating it if - necessary.</p> - - <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, - this will also remove each member from their previous group.</p> - - <tp:rationale> - <p>This is good for user interfaces in which you can edit groups - via drag-and-drop.</p> - </tp:rationale> - - <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, - <tp:member-ref>GroupsChanged</tp:member-ref> and - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Group" type="s" direction="in"> - <tp:docstring>The group to alter.</tp:docstring> - </arg> - - <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> - <tp:docstring>The set of members to include in the group.</tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Remove the given members from the given group.</p> - - <tp:rationale> - <p>This is good for user interfaces in which you can edit groups - via drag-and-drop.</p> - </tp:rationale> - - <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Group" type="s" direction="in"> - <tp:docstring>The group to alter. If it does not exist, then it has - no members by definition, so this method SHOULD return - successfully.</tp:docstring> - </arg> - - <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> - <tp:docstring>The set of members to remove from the group. It is not - an error to remove members who are already not in the group. - If there are no members left in the group afterwards, the group MAY - itself be removed.</tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - <method name="RemoveGroup" tp:name-for-bindings="Remove_Group"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Remove all members from the given group, then remove the group - itself. If the group already does not exist, this method SHOULD - return successfully.</p> - - <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Group" type="s" direction="in"> - <tp:docstring>The group to remove.</tp:docstring> - </arg> - - <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.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - <method name="RenameGroup" tp:name-for-bindings="Rename_Group"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Rename the given group.</p> - - <p>On protocols where groups behave like tags, this is an API - short-cut for adding all of the group's members to a group with - the new name, then removing the old group.</p> - - <tp:rationale> - <p>Otherwise, clients can't perform this operation atomically, even - if the connection could.</p> - </tp:rationale> - - <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or - <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from - this method call MUST be emitted before the method returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >ContactListState</tp:dbus-ref> changes to Success. - If the ContactListState is Failure, this method SHOULD raise the - same error as - <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" - >GetContactListAttributes</tp:dbus-ref>.</p> - </tp:docstring> - - <arg name="Old_Name" type="s" direction="in"> - <tp:docstring>The group to rename.</tp:docstring> - </arg> - - <arg name="New_Name" type="s" direction="in"> - <tp:docstring>The new name for the group.</tp:docstring> - </arg> - - <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.NotImplemented"> - <tp:docstring> - Raised if <tp:member-ref>GroupStorage</tp:member-ref> - is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist"> - <tp:docstring>Raised if there is no group with that - name.</tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring>Raised if there is already a group with the new - name.</tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Contact_Info.xml b/qt4/spec/Connection_Interface_Contact_Info.xml deleted file mode 100644 index 527d32522..000000000 --- a/qt4/spec/Connection_Interface_Contact_Info.xml +++ /dev/null @@ -1,550 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_Info" 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: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.Connection.Interface.ContactInfo"> - <tp:added version="0.19.4">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List"> - <tp:member type="s" name="Field_Name"> - <tp:docstring> - The name of the field; this is the lowercased name of a vCard field. - For example, a field representing a contact's address would be named - "adr". - </tp:docstring> - </tp:member> - <tp:member type="as" name="Parameters"> - <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> - 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 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 - into multiple Telepathy-level fields; for example, 'n' became - 'family-name', 'given-name', etc. But under this representation, - omitting empty components leads to difficulty identifying where one - name ends and another begins. Consider the fields ['given-name', - 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does - this represent two 'n' fields, or one with incorrect component - ordering? - </tp:rationale> - </tp:docstring> - </tp:member> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Represents one piece of information about a contact, as modelled by - a single vCard field. Of the fields defined in RFC 2426, common - examples include:</p> - - <dl> - <dt>fn</dt> - <dd>The contact's full name, formatted to their liking</dd> - - <dt>n</dt> - <dd>The contact's full name, divided into five parts: family name, - given name, additional names, honorific prefixes, and honorific - suffixes</dd> - - <dt>org</dt> - <dd>The contact's organisation, divided into the organization's name - possibly followed by one or more organizational unit names.</dd> - - <dt>adr</dt> - <dd>A street address for the contact, divided into seven components: - post office box, extended address, street address, locality (e.g., - city), region (e.g., state or province), the postal code, and the - country name.</dd> - - <dt>label</dt> - <dd>A free-form street address for the contact, formatted as a - single value (with embedded newlines where necessary) suitable for - printing on an address label</dd> - - <dt>tel</dt> - <dd>A telephone number for the contact.</dd> - - <dt>email</dt> - <dd>An email address for the contact.</dd> - </dl> - - <p>For example, the following vCard:</p> - - <pre> - BEGIN:vCard - VERSION:3.0 - FN:Wee Ninja - N;LANGUAGE=ja:Ninja;Wee;;;-san - ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement - ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire - ;CB2 1SJ;UK - LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ - TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753 - 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> - - <pre> -[ - ('fn', [], ['Wee Ninja']), - ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']), - ('org', [], ['Collabora, Ltd.', 'Management Division', - 'Human Resources; Company Policy Enforcement']), - ('adr', ['type=work','type=postal','type=parcel'], - ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']), - ('label', ['type=work','type=postal','type=parcel'], - ['''11 Kings Parade - Cambridge - Cambridgeshire - UK - CB2 1SJ''']), - ('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> - - <tp:mapping name="Contact_Info_Map" array-name=""> - <tp:docstring>A dictionary whose keys are contact handles and whose - values are contact information..</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="a(sasas)" tp:type="Contact_Info_Field[]" - name="Contact_Info"/> - </tp:mapping> - - <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed"> - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact whose info has changed. - </tp:docstring> - </arg> - <arg name="ContactInfo" type="a(sasas)" tp:type="Contact_Info_Field[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of fields representing information about this contact. - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a contact's information has changed or been received for - the first time on this connection. - </tp:docstring> - </signal> - - <method name="GetContactInfo" - tp:name-for-bindings="Get_Contact_Info"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts. - </tp:docstring> - </arg> - <arg direction="out" name="ContactInfo" type="a{ua(sasas)}" - tp:type="Contact_Info_Map"> - <tp:docstring> - A dictionary mapping contact handles to information, whose keys are - the subset of the requested list of handles for which information was - cached. - </tp:docstring> - </arg> - <tp:docstring> - Request information on several contacts at once. This SHOULD only - return cached information, omitting handles for which no information is - cached from the returned map. - </tp:docstring> - </method> - - <method name="RefreshContactInfo" - tp:name-for-bindings="Refresh_Contact_Info"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - Integer handles for contacts. - </tp:docstring> - </arg> - <tp:docstring> - Retrieve information for the given contact, requesting it from the - network if an up-to-date version is not cached locally. This method - SHOULD return immediately, emitting - <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts' - updated contact information is returned. - - <tp:rationale> - This method allows a client with cached contact information to - update its cache after a number of days. - </tp:rationale> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="RequestContactInfo" - tp:name-for-bindings="Request_Contact_Info"> - <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for a contact. - </tp:docstring> - </arg> - <arg direction="out" name="Contact_Info" type="a(sasas)" - tp:type="Contact_Info_Field[]"> - <tp:docstring> - Information about that contact. - </tp:docstring> - </arg> - <tp:docstring> - Retrieve information for a contact, requesting it from the network if - it is not cached locally. - - <tp:rationale> - This method is appropriate for an explicit user request to show - a contact's information; it allows a UI to wait for the contact - info to be returned. - </tp:rationale> - </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.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact's information could not be retrieved. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="SetContactInfo" tp:name-for-bindings="Set_Contact_Info"> - <tp:docstring> - Set new contact information for this connection, replacing existing - information. This method is only suppported if - <tp:member-ref>ContactInfoFlags</tp:member-ref> contains - <code>Can_Set</code>, and may only be passed fields conforming to - <tp:member-ref>SupportedFields</tp:member-ref>. - </tp:docstring> - <arg direction="in" name="ContactInfo" type="a(sasas)" - tp:type="Contact_Info_Field[]"> - <tp:docstring> - The new information to be set. - </tp:docstring> - </arg> - <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.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - Setting your own information is not supported on this protocol. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The supplied fields do not match the restrictions specified by - <tp:member-ref>SupportedFields</tp:member-ref>. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:flags name="Contact_Info_Flags" value-prefix="Contact_Info_Flag" - type="u"> - <tp:docstring> - Flags defining the behaviour of contact information on this protocol. - Some protocols provide no information on contacts without an explicit - request; others always push information to the connection manager as - and when it changes. - </tp:docstring> - - <tp:flag suffix="Can_Set" value="1"> - <tp:docstring> - Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is - supported on this connection. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Push" value="2"> - <tp:docstring> - Indicates that the protocol pushes all contacts' information to the - connection manager without prompting. If set, - <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted - whenever contacts' information changes. - </tp:docstring> - </tp:flag> - </tp:flags> - - <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_Flags" tp:name-for-bindings="Contact_Info_Flags"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An integer representing the bitwise-OR of flags on this - connection.</p> - - <p>This property MAY change, without change notification, at any time - before the connection moves to status Connection_Status_Connected. - It MUST NOT change after that point.</p> - - <tp:rationale> - <p>Some XMPP servers, like Facebook Chat, do not allow the vCard to - be changed (and so would not have the Can_Set flag). Whether the - user's server is one of these cannot necessarily be detected until - quite late in the connection process.</p> - </tp:rationale> - - </tp:docstring> - </property> - - <tp:struct name="Field_Spec" array-name="Field_Specs"> - <tp:docstring>A struct describing a vCard field, with parameters, that - may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this - Connection.</tp:docstring> - - <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: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_Exact flag is not set, any vCard type - parameters may be used.</tp:docstring> - </tp:member> - - <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags"> - <tp:docstring>Flags describing the behaviour of this - field.</tp:docstring> - </tp:member> - - <tp:member type="u" name="Max"> - <tp:docstring>Maximum number of instances of this field which may be - set. MAXUINT32 is used to indicate that there is no - limit.</tp:docstring> - </tp:member> - </tp:struct> - - <property name="SupportedFields" type="a(sasuu)" tp:type="Field_Spec[]" - access="read" tp:name-for-bindings="Supported_Fields"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of field specifications describing the kinds of fields which may - be passed to <tp:member-ref>SetContactInfo</tp:member-ref>. The empty - list indicates that arbitrary vCard fields are permitted. This - property SHOULD be the empty list, and be ignored by clients, if - <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the - Can_Set flag.</p> - - <p>For example, a protocol in which arbitrary vCards were stored - as-is would set this property to the - empty list. A protocol whose notion of contact information is one - each of personal phone number, mobile phone number, location, email - address and date of birth, with no attributes allowed on each piece - of information, would set this property to (in Python-like - syntax):</p> - - <pre> -[ - ('tel', ['type=home'], Parameters_Exact, 1), - ('tel', ['type=cell'], Parameters_Exact, 1), - ('adr', [], Parameters_Exact, 1), - ('bday', [], Parameters_Exact, 1), - ('email', ['type=internet'], Parameters_Exact, 1), -]</pre> - - <p>A protocol which allows users to specify up to four phone numbers, - which may be labelled as personal and/or mobile, would set this - property to - <code>[ ('tel', ['type=home', 'type=cell'], 0, 4), ]</code>.</p> - - <tp:rationale> - <p>Studying existing IM protocols shows that in practice protocols - allow either a very restricted set of fields (such as MSN, which - seems to correspond roughly to the largest example above), or - something mapping 1:1 to a large subset of vCard (such as XMPP's - XEP-0054).</p> - </tp:rationale> - - <p>This property MAY change, without change notification, at any time - before the connection moves to status Connection_Status_Connected. - It MUST NOT change after that point.</p> - - <tp:rationale> - <p>Some XMPP servers, like Google Talk, only allow a small subset of - the "vcard-temp" protocol. Whether the user's server is one of - these cannot be detected until quite late in the connection - process.</p> - </tp:rationale> - </tp:docstring> - </property> - - <tp:flags name="Contact_Info_Field_Flags" - value-prefix="Contact_Info_Field_Flag" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Flags describing the behaviour of a vCard field. - </tp:docstring> - <tp:flag suffix="Parameters_Exact" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If present, exactly the parameters indicated must be set on this - field; in the case of an empty list of parameters, this implies that - parameters may not be used.</p> - - <p>If absent, and the list of allowed parameters is non-empty, - any (possibly empty) subset of that list may be - used.</p> - - <p>If absent, and the list of allowed parameters is empty, - any parameters may be used.</p> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Overwritten_By_Nickname" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Indicates that this field will be overwritten when the user's alias - is changed with <tp:dbus-ref - namespace="ofdT.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> - or when the Account's <tp:dbus-ref - namespace="ofdT.Account">Nickname</tp:dbus-ref> - is updated. Clients that allow the editing of the Alias and the - ContactInfo in the same location should hide fields with this flag.</p> - <tp:rationale> - <p>If a client allowed the user to edit both the nickname and the - ContactInfo field at the same time, the user could set them to two - different values even though they map to the same property. This - would result in surprising behavior where the second value would - win over the first.</p> - </tp:rationale> - <p>In addition to hiding this field when editing ContactInfo together - with the user's nickname, it is recommended that clients call - <tp:member-ref>SetContactInfo</tp:member-ref> before setting the - user's nickname.</p> - <tp:rationale> - <p>This ensures that if the user changes the nickname, the correct - value will get set even if the stale nickname is mistakenly sent - along with <tp:member-ref>SetContactInfo</tp:member-ref>.</p> - </tp:rationale> - <p>If used, this flag typically appears on either the 'nickname' or - 'fn' field.</p> - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for requesting information about a contact on a given - connection. Information is represented as a list of - <tp:type>Contact_Info_Field</tp:type>s forming a - structured representation of a vCard (as defined by RFC 2426), using - field names and semantics defined therein.</p> - - <p>On some protocols, information about your contacts is pushed to you, - with change notification; on others, like XMPP, the client must - explicitly request the avatar, and has no way to tell whether it has - changed without retrieving it in its entirety. This distinction is - exposed by <tp:member-ref>ContactInfoFlags</tp:member-ref> containing - the Push flag.</p> - - <p>On protocols with the Push flag set, UIs can connect to - <tp:member-ref>ContactInfoChanged</tp:member-ref>, call - <tp:member-ref>GetContactInfo</tp:member-ref> once at login for the set - of contacts they are interested in, and then be sure they will receive - the latest contact info. On protocols like XMPP, clients can do the - same, but will receive (at most) opportunistic updates if the info is - retrieved for other reasons. Clients may call - <tp:member-ref>RequestContactInfo</tp:member-ref> or - <tp:member-ref>RefreshContactInfo</tp:member-ref> to force a contact's - info to be updated, but MUST NOT do so unless this is either in - response to direct user action, or to refresh their own cache after a - number of days.</p> - - <tp:rationale> - <p>We don't want clients to accidentally cause a ridiculous amount of - network traffic.</p> - </tp:rationale> - </tp:docstring> - - <tp:contact-attribute name="info" - type="a(sasas)" tp:type="Contact_Info_Field[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same value that would be returned by - <tp:member-ref>GetContactInfo</tp:member-ref> for this contact. - Omitted from the result if the contact's info - is not known.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Contact_List.xml b/qt4/spec/Connection_Interface_Contact_List.xml deleted file mode 100644 index 033c64d1d..000000000 --- a/qt4/spec/Connection_Interface_Contact_List.xml +++ /dev/null @@ -1,1085 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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 - 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.Connection.Interface.ContactList"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.21.0">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connections that have any concept of a list of - known contacts (roster, buddy list, friends list etc.)</p> - - <tp:rationale> - <p>On many protocols, there's a server-side roster (as in XMPP), - or a set of server-side lists that can be combined to form a - roster (as in MSN).</p> - - <p>In some protocols (like link-local XMPP), while there might not be - any server or roster, it's possible to list "nearby" contacts.</p> - - <p>In Telepathy 0.20 and older, we represented contact lists as a - collection of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type" - >ContactList</tp:dbus-ref> channels. This is remarkably difficult to - work with in practice - every client that cares about contact lists - has to take the union of some hard-to-define set of these - channels - and conflicts with the idea that channels that cannot - be dispatched to a handler should be closed.</p> - </tp:rationale> - - <p>The list of contacts is not exposed as a D-Bus property; it can be - fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>. - </p> - - <tp:rationale> - <p>In some protocols, such as XMPP, the contact list may not be - available immediately. The - <tp:member-ref>GetContactListAttributes</tp:member-ref> method - will fail until the contact list is available. - Using a method also allows extra attributes to be retrieved at - the same time.</p> - </tp:rationale> - </tp:docstring> - - <tp:enum name="Contact_List_State" type="u"> - <tp:docstring> - The progress made in retrieving the contact list. - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring>The connection has not started to retrieve the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is - called in this state, it will raise NotYet.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Waiting" value="1"> - <tp:docstring>The connection has started to retrieve the contact - list, but has not yet succeeded or failed. - If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called - in this state, it will raise NotYet.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Failure" value="2"> - <tp:docstring> - <p>The connection has tried and failed to retrieve the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> - is called in this state, it will immediately raise an error - indicating the reason for failure.</p> - - <p>The connection manager SHOULD try again to obtain the contact - list, if appropriate for the protocol. If it succeeds later, - the <tp:member-ref>ContactListState</tp:member-ref> MUST advance - to Success.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Success" value="3"> - <tp:docstring>The connection has successfully retrieved the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> - is called in this state, it will return successfully.</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="ContactListState" tp:name-for-bindings="Contact_List_State" - type="u" tp:type="Contact_List_State" access="read"> - <tp:docstring> - The progress made in retrieving the contact list. - Change notification is via - <tp:member-ref>ContactListStateChanged</tp:member-ref>. - </tp:docstring> - </property> - - <signal name="ContactListStateChanged" - tp:name-for-bindings="Contact_List_State_Changed"> - <tp:docstring> - Emitted when <tp:member-ref>ContactListState</tp:member-ref> - changes. - </tp:docstring> - - <arg name="Contact_List_State" type="u" tp:type="Contact_List_State"> - <tp:docstring> - The new value of <tp:member-ref>ContactListState</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <method name="GetContactListAttributes" - tp:name-for-bindings="Get_Contact_List_Attributes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Return some contact attributes for a list of contacts - associated with the user. This list MUST include at least:</p> - - <ul> - <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref> - attribute is not No</li> - <li>all contacts whose <tp:token-ref>publish</tp:token-ref> - attribute is not No</li> - </ul> - - <p>but MAY contain other contacts.</p> - - <tp:rationale> - <p>For instance, on XMPP, all contacts on the roster would appear - here even if they have subscription="none", unless there's - reason to believe the user does not want to see them (such as - having been blocked).</p> - </tp:rationale> - - <p>This list does not need to contain every visible contact: for - instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear - here. Blocked contacts SHOULD NOT appear here, unless they still - have a non-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or - <tp:token-ref>publish</tp:token-ref> attribute - for some reason.</p> - - <tp:rationale> - <p>It's reasonable to assume that blocked contacts should not be - visible to the user unless they specifically go looking for them, - at least in protocols like XMPP where blocking a contact - suppresses presence.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Interfaces" type="as" - tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of strings indicating which D-Bus interfaces the calling - process is interested in. Equivalent to the corresponding argument - to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" - >GetContactAttributes</tp:dbus-ref>, - except that if this list does not contain the ContactList - interface itself, it is treated as though that interface was also - requested.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Hold" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, all handles that appear as keys in the result have been - held on behalf of the calling process, as if by a call to - <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. - (If <tp:dbus-ref namespace="ofdT.Connection" - >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the - case in all new connection managers, this has no effect.)</p> - </tp:docstring> - </arg> - - <arg direction="out" type="a{ua{sv}}" name="Attributes" - tp:type="Contact_Attributes_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary mapping the contact handles to contact attributes, - equivalent to the result of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" - >GetContactAttributes</tp:dbus-ref>.</p> - - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:member-ref>ContactListState</tp:member-ref> is - None or Waiting. In particular, this error is raised if the - <tp:dbus-ref namespace="ofdT.Connection">Status</tp:dbus-ref> - is not yet Connection_Status_Connected.</p> - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:enum name="Subscription_State" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An enumeration indicating whether presence subscription is denied, - denied but pending permission, or allowed. The exact semantics - vary according to where this type is used: see the - <tp:token-ref>subscribe</tp:token-ref> and - <tp:token-ref>publish</tp:token-ref> contact attributes for - details.</p> - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring>The presence subscription state is - unknown.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="No" value="1"> - <tp:docstring>Presence information cannot be seen, and either the - subscription state Removed_Remotely does not apply, or it is - not known whether that state applies. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Removed_Remotely" value="2"> - <tp:docstring>Presence information cannot be seen because the - remote contact took action: either the local user's request to - see the remote contact's presence was denied, or the remote - contact requested to see the local user's presence but then - cancelled their request.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Ask" value="3"> - <tp:docstring>Presence information cannot be seen. Permission - to see presence information has been requested, and the request - has not yet been declined or accepted.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Yes" value="4"> - <tp:docstring>Presence information can be seen.</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:contact-attribute name="subscribe" - type="u" tp:type="Subscription_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If this attribute on a contact is Yes, this connection can - expect to receive their presence, along with any other information - that has the same access control.</p> - - <tp:rationale> - <p>This is subscription="from" or subscription="both" in XMPP, - the "forward list" on MSN, or the contact being "added to - the local user's buddy list" in ICQ, for example.</p> - </tp:rationale> - - <p>If this attribute is not Yes, the local user cannot generally - expect to receive presence from this contact. Their presence status - as returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref> - is likely to be (Unknown, "unknown", ""), unless the local user - can temporarily see their presence for some other reason (for - instance, on XMPP, contacts seen in chatrooms will temporarily - have available presence).</p> - - <p>If this attribute is Ask, this indicates that the local user has - asked to receive the contact's presence at some time. It is - implementation-dependent whether contacts' subscribe attributes - can remain set to Ask, or are reset to No, when the connection - disconnects.</p> - - <tp:rationale> - <p>Some protocols store the fact that we wishes to see a contact's - presence; on these protocols, this attribute can remain Ask - indefinitely. On other protocols, only contacts who have been - asked during the current session will ever have Ask status.</p> - </tp:rationale> - - <p>If this attribute is Removed_Remotely, this indicates that the - local user has asked to receive the contact's presence at some time, - but the remote contact has rejected that request, and a local - user interface has not yet acknowledged this. It is - implementation-dependent whether contacts' subscribe attributes can - remain set to Removed_Remotely, or are reset to No, when the - connection disconnects.</p> - - <p>After notifying the user, user interfaces MAY acknowledge a change - to <tt>subscribe</tt>=Removed_Remotely by calling either - <tp:member-ref>Unsubscribe</tp:member-ref> or - <tp:member-ref>RemoveContacts</tp:member-ref>, which will set - <tt>subscribe</tt> to No (and perhaps remove the contact). This - allows user interfaces to detect that the user has been notified - about the rejected request.</p> - - <p>This attribute's value will be Unknown or omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</p> - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="publish" - type="u" tp:type="Subscription_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If this attribute on a contact is Yes, the local user's presence - is published to that contact, along with any other information that - shares an access-control mechanism with presence (depending on - protocol, server configuration and/or user configuration, this may - include avatars, "rich presence" such as location, etc.).</p> - - <tp:rationale> - <p>This is subscription="to" or subscription="both" in XMPP, - the "reverse list" on MSN, or the state of "being added to - the contact's buddy list" in ICQ, for example.</p> - </tp:rationale> - - <p>If this attribute is not Yes, the - local user's presence is not published to that contact; however, - if it is Ask, the contact has requested that the local user's - presence is made available to them.</p> - - <p>It is implementation-dependent whether contacts' <tt>publish</tt> - attributes can remain set to Ask, or are reset to No, when the - connection disconnects.</p> - - <tp:rationale> - <p>Some protocols store the fact that a contact wishes to see our - presence; on these protocols, this attribute can remain Ask - indefinitely. On other protocols, only contacts who have asked - during the current session will ever have Ask status.</p> - </tp:rationale> - - <p>If this attribute is Removed_Remotely, this indicates that the - remote contact has asked to receive the user's presence at some time, - but has then cancelled that request before a response was given by - the local user. User interfaces MAY reset <tt>publish</tt> from - Removed_Remotely to No, by calling either - <tp:member-ref>Unpublish</tp:member-ref> or - <tp:member-ref>RemoveContacts</tp:member-ref>.</p> - - <p>If multiple factors affect whether a contact can receive the local - user's presence, this attribute SHOULD reflect the overall - result. For instance, an XMPP contact with subscription="to" or - subscription="both", but who has been blocked via - <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy - Lists</a>, SHOULD have publish=No.</p> - - <p>This attribute's value will be Unknown or omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</p> - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="publish-request" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If the <tp:token-ref>publish</tp:token-ref> attribute is Ask, an - optional message that was sent by the contact asking to receive the - local user's presence; omitted if none was given.</p> - - <tp:rationale> - <p>If the contact asking to receive our presence is also using - Telepathy, this is the message they supplied as the Message - argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p> - </tp:rationale> - - <p>Otherwise, this SHOULD be omitted.</p> - - <p>This attribute will also be omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</p> - </tp:docstring> - </tp:contact-attribute> - - <property name="ContactListPersists" - tp:name-for-bindings="Contact_List_Persists" type="b" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, presence subscriptions (in both directions) on this - connection are stored by the server or other infrastructure.</p> - - <tp:rationale> - <p>XMPP, MSN, ICQ, etc. all behave like this.</p> - </tp:rationale> - - <p>If false, presence subscriptions on this connection are not - stored.</p> - - <tp:rationale> - <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record - of subscriptions, as described below. In link-local XMPP, - subscriptions are implicit (everyone on the local network receives - presence from everyone else) so nothing is ever stored.</p> - </tp:rationale> - - <p>If <tp:member-ref>CanChangeContactList</tp:member-ref> - is true, Telepathy clients (e.g. user interfaces or address books) - MAY keep a record of permission to publish and requests to subscribe - locally, and attempt to restore it for each Connection. If - ContactListPersists is false, clients MAY do this for all contacts; - if ContactListPersists is true, clients SHOULD NOT change the state - of contacts that were not changed locally.</p> - - <tp:rationale> - <p>In SIMPLE (SIP), ContactListPersists is false, but - CanChangeContactList is true. Presence will not be received - unless clients renew any subscriptions they have for each - connection, in the way described. There is no server-side storage, - so clients have no alternative but to maintain independent contact - lists.</p> - - <p>In protocols like XMPP and MSN, it may be useful for clients to - queue up subscription requests or removals made while offline and - process them next time the connection is online. However, clients - should only replay the changes, rather than resetting the contact - list to match a stored copy, to avoid overwriting changes that - were made on the server.</p> - </tp:rationale> - - <p>Clients that replay requests like this SHOULD do so by calling - AuthorizePublication to pre-approve publication of presence to the - appropriate contacts, followed by RequestSubscription to request the - appropriate contacts' presences.</p> - - <p>This property cannot change after the connection has moved to the - Connected state. Until then, its value is undefined, and it may - change at any time, without notification.</p> - </tp:docstring> - </property> - - <tp:enum name="Contact_Metadata_Storage_Type" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Values of this enumeration indicate the extent to which metadata - such as aliases and group memberships can be stored for the contacts - on a particular connection.</p> - - <p>On some protocols, certain metadata (for instance, contact aliases) - can only be stored for contacts on the contact list, or contacts - with a particular contact list state.</p> - - <p>To make it easier to deal with such protocols, if clients set - metadata on a contact who is not in the required state, the - Connection MUST cache the metadata for the duration of the session. - If clients request the attributes of that contact after the - appropriate "set" method has returned successfully, the Connection - MUST return the new (cached) value.</p> - - <p>If the contact is later placed in the required state to store - metadata (for instance, if subscription to the contact's presence - is requested, on a protocol like MSN where the alias has storage type - Subscribed_Or_Pending), the connection MUST store the cached - metadata at that time.</p> - - <tp:rationale> - <p>If the Connection didn't cache changes in this way, a client - intending to change the alias on MSN would have to wait until - the server acknowledged the subscription request; in the meantime, - other clients would still display the old alias.</p> - </tp:rationale> - - <p>The only exception to that general rule is that if the Connection - cannot store particular metadata at all (i.e. the - storage type is None), it MUST reject attempts to set it.</p> - - <tp:rationale> - <p>If the implementation knows that metadata can't be stored at - all, it's useful to report that, which can be done - synchronously. In general, user interfaces should detect - storage type None and not display editing controls at all.</p> - </tp:rationale> - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This connection cannot store this type of metadata at all, and - attempting to do so will fail with NotImplemented.</p> - - <tp:rationale> - <p>Link-local XMPP can't store aliases or group memberships at - all, and subscription and presence states are implicit (all - contacts on the local network have subscribe = publish = Yes - and no other contacts exist).</p> - - <p>As of April 2010, the XMPP server for Facebook Chat provides a - read-only view of the user's Facebook contacts, so it could also - usefully have this storage type.</p> - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Subscribed_Or_Pending" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This type of metadata can only be stored permanently for contacts - whose subscribe attribute is Ask or Yes.</p> - - <tp:rationale> - <p>Contact aliases and groups on MSN have this behaviour.</p> - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Subscribed" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This type of metadata can only be stored permanently for contacts - whose subscribe attribute is Yes.</p> - - <tp:rationale> - <p>No service with this behaviour is currently known, but it's a - stricter form of Subscribed_Or_Pending.</p> - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Anyone" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The user can set this metadata for any valid contact identifier, - whether or not they have any presence subscription relationship - to it, and it will be stored on their contact list.</p> - - <tp:rationale> - <p>Contact aliases and groups on XMPP have this behaviour; it - is possible to put a contact in a group, or assign an alias - to them, without requesting that presence be shared.</p> - </tp:rationale> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Contact_Subscriptions" array-name=""> - <tp:docstring> - A single contact's subscribe, publish and publish-request attributes. - </tp:docstring> - - <tp:member name="Subscribe" type="u" tp:type="Subscription_State"> - <tp:docstring> - The new value of the contact's "subscribe" attribute. - </tp:docstring> - </tp:member> - - <tp:member name="Publish" type="u" tp:type="Subscription_State"> - <tp:docstring> - The new value of the contact's "publish" attribute. - </tp:docstring> - </tp:member> - - <tp:member name="Publish_Request" type="s"> - <tp:docstring> - The new value of the contact's "publish-request" attribute, - or the empty string if that attribute would be omitted. - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Contact_Subscription_Map" array-name=""> - <tp:docstring> - A map from contacts to their subscribe, publish and publish-request - attributes. - </tp:docstring> - - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact's handle. - </tp:docstring> - </tp:member> - - <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions"> - <tp:docstring> - The contact's subscribe, publish and publish-request attributes. - </tp:docstring> - </tp:member> - </tp:mapping> - - <signal name="ContactsChangedWithID" - tp:name-for-bindings="Contacts_Changed_With_ID"> - <tp:added version="0.21.8"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the contact list becomes available, when contacts' - basic stored properties change, when new contacts are added to the - list that would be returned by - <tp:member-ref>GetContactListAttributes</tp:member-ref>, - or when contacts are removed from that list.</p> - - <tp:rationale> - <p>This provides change notification for that list, and for - contacts' <tp:token-ref>subscribe</tp:token-ref>, - <tp:token-ref>publish</tp:token-ref> and - <tp:token-ref>publish-request</tp:token-ref> attributes.</p> - </tp:rationale> - - <p>Connection managers SHOULD also emit this signal when a contact - requests that the user's presence is published to them, even if - that contact's <tp:token>publish</tp:token> attribute is already - Ask and the <tp:token>publish-request</tp:token> has not changed.</p> - - <tp:rationale> - <p>If the same contact sends 10 identical requests, 10 identical - signals should be emitted.</p> - </tp:rationale> - </tp:docstring> - - <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> - <tp:docstring> - The new <tp:token-ref>subscribe</tp:token-ref>, - <tp:token-ref>publish</tp:token-ref> and - <tp:token-ref>publish-request</tp:token-ref> attributes of all the - contacts that have been added, and all the contacts for which those - attributes have changed. - </tp:docstring> - </arg> - - <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The identifiers of the contacts in the <var>Changes</var> map. - </tp:docstring> - </arg> - - <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The contacts that have been removed from the list that would be - returned by - <tp:member-ref>GetContactListAttributes</tp:member-ref>. - This also implies that they have subscribe = No and publish = No; - contacts MUST NOT be listed both here and in <var>Changes</var>. - </tp:docstring> - </arg> - </signal> - - <signal name="ContactsChanged" - tp:name-for-bindings="Contacts_Changed"> - <tp:deprecated version="0.21.8">Connection managers MUST still - emit this signal, but clients SHOULD listen for the - <tp:member-ref>ContactsChangedWithID</tp:member-ref> signal in - addition, and ignore this signal after ContactsChangedWithID has been - emitted at least once. - </tp:deprecated> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted immediately after - <tp:member-ref>ContactsChangedWithID</tp:member-ref>, under the same - circumstances.</p> - - <p>If clients receive this signal without first receiving a - corresponding <tp:member-ref>ContactsChangedWithID</tp:member-ref>, - they MUST assume that only this signal will be emitted.</p> - </tp:docstring> - - <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> - <tp:docstring> - The same as the corresponding argument to - <tp:member-ref>ContactsChangedWithID</tp:member-ref>. - </tp:docstring> - </arg> - - <arg name="Removals" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The same as the corresponding argument to - <tp:member-ref>ContactsChangedWithID</tp:member-ref>, except that it - only includes handles and not identifiers. - </tp:docstring> - </arg> - </signal> - - <property name="CanChangeContactList" type="b" access="read" - tp:name-for-bindings="Can_Change_Contact_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, presence subscription and publication can be changed - using the - <tp:member-ref>RequestSubscription</tp:member-ref>, - <tp:member-ref>AuthorizePublication</tp:member-ref> and - <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p> - - <p>If false, all of those methods will always fail; they SHOULD raise - the error org.freedesktop.Telepathy.Error.NotImplemented.</p> - - <tp:rationale> - <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is - implicitly published to everyone in the local subnet, so the user - cannot control their presence publication.</p> - </tp:rationale> - - <p>This property cannot change after the connection has moved to the - Connected state. Until then, its value is undefined, and it may - change at any time, without notification.</p> - </tp:docstring> - </property> - - <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that the given contacts allow the local user to - subscribe to their presence, i.e. that their subscribe attribute - becomes Yes.</p> - - <p>Connection managers SHOULD NOT attempt to enforce a - mutual-subscription policy (i.e. when this method is called, they - should not automatically allow the contacts to see the local user's - presence). User interfaces that require mutual subscription - MAY call <tp:member-ref>AuthorizePublication</tp:member-ref> - at the same time as this method.</p> - - <tp:rationale> - <p>Whether to enforce mutual subscription is a matter of policy, - so it is left to the user interface and/or the server.</p> - </tp:rationale> - - <p>Before calling this method on a connection where <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" - >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag, - user interfaces SHOULD obtain, from the user, an alias to - identify the contact in future, and store it using <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" - >SetAliases</tp:dbus-ref>.</p> - - <p>The user MAY be - prompted using the contact's current self-assigned nickname, or - something derived from the contact's (presumably self-assigned) - identifier, as a default, but these names chosen by the contact - SHOULD NOT be used without user approval.</p> - - <tp:rationale> - <p>This is a generalization of - <a href="http://xmpp.org/extensions/xep-0165.html" - >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>) - to protocols other than XMPP. A reasonable user interface for - this, as used in many XMPP clients, is to have a text entry - for the alias adjacent to the text entry for the identifier - to add.</p> - </tp:rationale> - - <p>For contacts with subscribe=Yes, this method has no effect. - It MUST return successfully if all contacts are in this state.</p> - - <p>For contacts with subscribe=Ask, this method SHOULD send a new - request, with the given message, if allowed by the underlying - protocol.</p> - - <p>For contacts with subscribe=No or subscribe=Rejected, this method - SHOULD request that the contact allows the local user to subscribe - to their presence; in general, this will change their publish - attribute to Ask (although it could change directly to Yes in some - situations).</p> - - <p>Any state changes that immediately result from this request MUST - be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> - before this method returns.</p> - - <tp:rationale> - <p>This makes it easy for user interfaces to see what practical - effect this method had.</p> - </tp:rationale> - - <p>If the remote contact accepts the request, their subscribe - attribute will later change from Ask to Yes.</p> - - <p>If the remote contact explicitly rejects the request (in protocols - that allow this), their subscribe attribute will later change from - Ask to Rejected.</p> - - <p>If the subscription request is cancelled by the local user, the - contact's subscribe attribute will change from Ask to No.</p> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Contacts" direction="in" - type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more contacts to whom requests are to be sent.</p> - </tp:docstring> - </arg> - - <arg name="Message" type="s" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An optional plain-text message from the user, to send to those - contacts with the subscription request. The - <tp:member-ref>RequestUsesMessage</tp:member-ref> property - indicates whether this message will be used or ignored.</p> - - <p>Clients SHOULD NOT send a non-empty message without first giving - the user an opportunity to edit it.</p> - - <tp:rationale> - <p>These messages are typically presented to the remote contact - as if the user had typed them, so as a minimum, the user should be - allowed to see what the UI will be saying on their behalf.</p> - </tp:rationale> - - <p>Connections where this message is not useful MUST still allow it to - be non-empty.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action, because - <tp:member-ref>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <property name="RequestUsesMessage" type="b" access="read" - tp:name-for-bindings="Request_Uses_Message"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, the Message parameter to - <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be - significant, and user interfaces SHOULD prompt the user for a - message to send with the request; a message such as "I would like - to add you to my contact list", translated into the local user's - language, might make a suitable default.</p> - - <tp:rationale> - <p>This matches user expectations in XMPP and ICQ, for instance.</p> - </tp:rationale> - - <p>If false, the parameter is ignored; user interfaces SHOULD avoid - prompting the user, and SHOULD pass an empty string to - RequestSubscription.</p> - - <tp:rationale> - <p><em>FIXME: is there any such protocol?</em></p> - </tp:rationale> - </tp:docstring> - </property> - - <method name="AuthorizePublication" - tp:name-for-bindings="Authorize_Publication"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For each of the given contacts, request that the local user's - presence is sent to that contact, i.e. that their publish attribute - becomes Yes.</p> - - <p>Connection managers SHOULD NOT attempt to enforce a - mutual-subscription policy (i.e. when this method is called, they - should not automatically request that the contacts allow the user to - subscribe to their presence). User interfaces that require mutual - subscription MAY call - <tp:member-ref>RequestSubscription</tp:member-ref> at the same time - as this method.</p> - - <tp:rationale> - <p>Whether to enforce mutual subscription is a matter of policy, - so it is left to the user interface and/or the server.</p> - </tp:rationale> - - <p>For contacts with publish=Yes, this method has no effect; it - MUST return successfully if all contacts given have this state.</p> - - <p>For contacts with publish=Ask, this method accepts the - contact's request to see the local user's presence, changing - their publish attribute from Ask to Yes.</p> - - <p>For contacts with publish=No, if the protocol allows it, this - method allows the contacts to see the local user's presence even - though they have not requested it, changing their publish attribute - from No to Yes. Otherwise, it merely records the fact that - presence publication to those contacts is allowed; if any of - those contacts ask to receive the local user's presence - later in the lifetime of the connection, the connection SHOULD - immediately allow them to do so, changing their publish - attribute directly from No to Yes.</p> - - <tp:rationale> - <p>This makes it easy to implement the common UI policy that if - the user attempts to subscribe to a contact's presence, requests - for reciprocal subscription are automatically approved.</p> - </tp:rationale> - - <p>Any state changes that immediately result from this request MUST - be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> - before this method returns.</p> - - <tp:rationale> - <p>This makes it easy for user interfaces to see what practical - effect this method had.</p> - </tp:rationale> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Contacts" direction="in" - type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more contacts to authorize.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action, because - <tp:member-ref>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Remove the given contacts from the contact list entirely. It is - protocol-dependent whether this works, and under which - circumstances.</p> - - <p>If possible, this method SHOULD set the contacts' subscribe and - publish attributes to No, remove any stored aliases for those - contacts, and remove the contacts from the result of - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - - <p>This method SHOULD succeed even if it was not possible to carry out - the request entirely or for all contacts (for instance, if there is an - outstanding request to subscribe to the contact's presence, and it's - not possible to cancel such requests). However, all signals that - immediately result from this method call MUST be emitted before it - returns, so that clients can interpret the result.</p> - - <tp:rationale> - <p>User interfaces removing a contact from the contact list are - unlikely to want spurious failure notifications resulting from - limitations of a particular protocol. However, emitting the - signals first means that if a client does want to check exactly - what happened, it can wait for the method to return (while - applying change-notification signals to its local cache of the - contact list's state), then consult its local cache of the - contact list's state to see whether the contact is still there.</p> - </tp:rationale> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Contacts" direction="in" - type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more contacts to remove.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action because - <tp:member-ref>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Attempt to set the given contacts' subscribe attribute to No, - i.e. stop receiving their presence.</p> - - <p>For contacts with subscribe=Ask, this attempts to cancel - an earlier request to subscribe to the contact's presence; for - contacts with subscribe=Yes, this attempts to - unsubscribe from the contact's presence.</p> - - <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method - SHOULD succeed even if it was not possible to carry out the request - entirely or for all contacts; however, all signals that - immediately result from this method call MUST be emitted before it - returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Contacts" direction="in" - type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more contacts to remove.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action because - <tp:member-ref>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Unpublish" tp:name-for-bindings="Unpublish"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Attempt to set the given contacts' publish attribute to No, - i.e. stop sending presence to them.</p> - - <p>For contacts with publish=Ask, this method explicitly rejects the - contact's request to subscribe to the user's presence; for - contacts with publish=Yes, this method attempts to prevent the - user's presence from being received by the contact.</p> - - <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method - SHOULD succeed even if it was not possible to carry out the request - entirely or for all contacts; however, all signals that - immediately result from this method call MUST be emitted before it - returns.</p> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> - </tp:docstring> - - <arg name="Contacts" direction="in" - type="au" tp:type="Contact_Handle[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>One or more contacts to remove.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action because - <tp:member-ref>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Contacts.xml b/qt4/spec/Connection_Interface_Contacts.xml deleted file mode 100644 index 1020190d4..000000000 --- a/qt4/spec/Connection_Interface_Contacts.xml +++ /dev/null @@ -1,191 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Contacts" 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, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or (at - your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 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.Connection.Interface.Contacts"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.17.9"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface allows many attributes of many contacts to be - obtained in a single D-Bus round trip.</p> - - <p>Each contact attribute has an string identifier - (<tp:type>Contact_Attribute</tp:type>), which is namespaced - by the D-Bus interface which defines it.</p> - </tp:docstring> - - <tp:simple-type name="Contact_Attribute" type="s"> - <tp:docstring> - A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character - and an identifier for an attribute defined by that interface. The - attribute identifier SHOULD be in lower case. - - <tp:rationale> - These aren't D-Bus core Properties, and we want them to look visibly - different. - </tp:rationale> - </tp:docstring> - </tp:simple-type> - - <tp:mapping name="Single_Contact_Attributes_Map"> - <tp:docstring> - Some of the attributes of a single contact. - </tp:docstring> - - <tp:member type="s" tp:type="Contact_Attribute" name="Attribute"> - <tp:docstring> - The name of the attribute - </tp:docstring> - </tp:member> - - <tp:member type="v" name="Value"> - <tp:docstring> - The value of the attribute - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:mapping name="Contact_Attributes_Map"> - <tp:docstring>Mapping returned by - <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a - collection of Contacts and their requested attributes.</tp:docstring> - - <tp:member type="u" tp:type="Contact_Handle" name="Contact"> - <tp:docstring> - A contact - </tp:docstring> - </tp:member> - - <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map" - name="Attributes"> - <tp:docstring> - Attributes of that contact - </tp:docstring> - </tp:member> - </tp:mapping> - - <property name="ContactAttributeInterfaces" access="read" type="as" - tp:type="DBus_Interface[]" - tp:name-for-bindings="Contact_Attribute_Interfaces"> - <tp:docstring> - A list of D-Bus interfaces for which - <tp:member-ref>GetContactAttributes</tp:member-ref> is expected to work. - This cannot change during the lifetime of the Connection. - </tp:docstring> - </property> - - <method name="GetContactAttributes" - tp:name-for-bindings="Get_Contact_Attributes"> - <tp:docstring> - Return any number of contact attributes for the given handles. - </tp:docstring> - - <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of handles representing contacts. - </tp:docstring> - </arg> - - <arg direction="in" name="Interfaces" type="as" - tp:type="DBus_Interface[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of strings indicating which D-Bus interfaces the calling - process is interested in. All supported attributes from these - interfaces, whose values can be obtained without additional network - activity, will be in the reply.</p> - - <p>Connection managers SHOULD ignore interfaces requested which they - do not support (i.e. those not mentioned in the - <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> - property.)</p> - - <tp:rationale> - <p>This simplifies client-side code. Clients which care may - distinguish between unsupported interfaces (e.g. this Connection - does not support Avatars), and interfaces on which no information - is known for these contacts (e.g. we don't know the avatar tokens - of any of the contacts, so we omitted them all) by inspecting - <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>.</p> - </tp:rationale> - - <p>Attributes from the interface - <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> - are always returned, and need not be requested explicitly.</p> - - <p>As well as returning cached information immediately, the - connection MAY start asynchronous requests to obtain better - values for the contact attributes. If better values are later - obtained by this process, they will be indicated with the usual - signals (such as <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">AliasesChanged</tp:dbus-ref>).</p> - - <tp:rationale> - For instance, an XMPP connection manager could download vCards - in response to a request for <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref> - attributes. - </tp:rationale> - </tp:docstring> - <tp:changed version="0.19.2"> - requesting information for interfaces not mentioned in - <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> is no - longer an error. Be aware that older connection managers may still - consider this an error. - </tp:changed> - </arg> - - <arg direction="in" name="Hold" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, all handles that appear as keys in the result have been - held on behalf of the calling process, as if by a call to - <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. - (If <tp:dbus-ref namespace="ofdT.Connection" - >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the - case in all new connection managers, this has no effect.)</p> - - <tp:rationale> - <p>For further round-trip avoidance.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg direction="out" type="a{ua{sv}}" name="Attributes" - tp:type="Contact_Attributes_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary mapping the contact handles to contact attributes. - If any of the requested handles are in fact invalid, they are - simply omitted from this mapping. If contact attributes are not - immediately known, the behaviour is defined by the interface; - the attribute should either be omitted from the result or - replaced with a default value.</p> - - <p>Each contact's attributes will always include at least the - identifier that would be obtained by inspecting the handle - (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - </tp:possible-errors> - </method> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Forwarding.xml b/qt4/spec/Connection_Interface_Forwarding.xml deleted file mode 100644 index e5457b1ea..000000000 --- a/qt4/spec/Connection_Interface_Forwarding.xml +++ /dev/null @@ -1,346 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Forwarding" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details.</p> - - <p>You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301, USA.</p> - </tp:license> - - <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This connection interface is for protocols that are capable of - signaling to remote contacts that incoming communication channels - should be instead sent to a separate contact. This might apply to - things such as call forwarding, for example.</p> - - <p>In some cases, a CM may register forwarding rules with an external - service; in those cases, it will never see the incoming channel, and - the forwarding will happen automatically.</p> - - <p>In other cases, the CM will handle the forwarding itself. When an - incoming channel is detected, the status of the local user will - determine whether or not a forwarding rule is matched. For some - rules, this MAY happen immediately (ie, if the user is Busy); for - others, there MAY be a timeout (in seconds) that must expire - before the forwarding rule is matched (the timeout is specified - by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p> - - <p>Once a forwarding rule is matched and any necessary timeouts have - expired, the CM can forward the incoming channel to the specified - handle. If for whatever reason the remote handle does not accept - the channel AND the CM supports multiple forwarding entries AND - any necessary timeouts have expired (specified by the next entry - in the list), the CM can forward the incoming channel to the next - handle in the entry list. This continues until the list is - exhausted, or the incoming channel is accepted.</p> - - <p>Note that the rule matches are only for the first entry in the - in the forwarding rule list. Once the incoming channel has been - forwarded, the next entry in the list (assuming one exists and - the contact that the channel has been forwarded to does not respond - after any necessary timeouts) is used regardless of the status of - the forwarded channel. The initial match rule might have been - Busy, whereas the contact that the channel has been forwarded to - might be offline. Even in this case, the Busy list is still - traversed until the channel is handled (or there are no more - forwarding entries in the list).</p> - - <p>For example, assuming the following dict for Forwarding_Rules:</p> - <pre> - ForwardingRules = { - Busy: ( initial-timeout: 30, [ - (handle: 3, timeout: 15), - (handle: 5, timeout: 20) - ]), - NoReply: ( initial-timeout: 15, [ - (handle: 5, timeout: 30), - (handle: 3, timeout: 20) - ]) - }</pre> - - <p>We can imagine a scenario where an incoming channel is detected, - the media stream is available (ie, not Busy), - and the local user is online. While the CM is waiting for the local user to - accept the channel, it looks at NoReply's first timeout value. After 15s if - the local user hasn't accepted, the CM forwards the channel to Handle #5. The - CM then waits 30s for Handle #5 to accept the channel. If after 30s it does - not, the CM forwards the incoming channel to Handle #3, which will have - 20s to accept the channel.</p> - - <p>When an unanswered <tp:dbus-ref - namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> call is - forwarded, both the contact and the self handle should be removed from - the group with the self handle as the actor, and - <tp:type>Channel_Group_Change_Reason</tp:type> <code>No_Answer</code> or - <code>Busy</code>, as appropriate. For <tp:dbus-ref - namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels, the - <tp:type>Call_State_Change_Reason</tp:type> <code>Forwarded</code> - should be used.</p> - </tp:docstring> - - <tp:enum name="Forwarding_Condition" type="u"> - <tp:docstring> - The various forwarding conditions that are supported by this interface. - In general, the conditions should not overlap; it should be very clear - which rule would be chosen given a CM's behavior with an incoming - channel. The exception to this is Unconditional, - which will override all other rules. - </tp:docstring> - - <tp:enumvalue value="0" suffix="Unconditional"> - <tp:docstring> - Incoming channels should always be forwarded. Note that setting this - will override any other rules. If not set, other rules will - be checked when an incoming communication channel is detected. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="1" suffix="Busy"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The incoming channel should be forwarded if a busy signal is - detected. What defines "Busy" is CM-specific (perhaps a single - resource is already in use, or a user's status is set to Busy - <tp:type>Connection_Presence_Type</tp:type>).</p> - - <p>If initial timeout is specified for Busy condition and call - waiting is not supported by the service, the timeout will be - ignored.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="2" suffix="No_Reply"> - <tp:docstring> - The incoming channel should be forwarded if the local user doesn't - accept it within the specified amount of time. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="3" suffix="Not_Reachable"> - <tp:docstring> - The incoming channel should be forwarded if the user is offline. - This could be a manual setting (the user has chosen to set their - presence to offline or invisible) or something specified by the - underlying network (the user is not within range of a cell tower). - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Forwarding_Rule_Entry" - array-name="Forwarding_Rule_Entry_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A forwarding rule entry. These MAY be chained together - for CMs that support chaining of forwards (in other words, - a forwarding rule may have multiple entries; if the contact - in the first entry doesn't respond, the incoming channel - might be forwarded to the contact in the second entry).</p> - - <p>For CMs and protocols that don't support chaining of - entries, only the first entry would be used.</p> - </tp:docstring> - - <tp:member type="u" name="Timeout"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The length of time (in seconds) to wait the contact to respond - to the forwarded channel. This MAY be ignored by the CM if it - isn't supported by the underlying network/protocol for the - specific status of the remote contact (for example, a GSM call - that is forwarded may return Not_Reachable immediately without - waiting for the timeout value to expire).</p> - - <p>A value of 0 means the condition can match immediately. A - value of MAX_UINT32 means that the CM's default should be - used.</p> - </tp:docstring> - </tp:member> - - <tp:member type="u" tp:type="Contact_Handle" name="Handle"> - <tp:docstring> - The contact to forward an incoming channel to. If the handle - doesn't point to anything (e.g. points to a phone number that - doesn't exist), the entry SHOULD be skipped. - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Forwarding_Rule_Chain"> - <tp:docstring> - A chain of forwarding rules and an initial timeout after which - the rules are applied. - </tp:docstring> - - <tp:member type="u" name="InitialTimeout"> - <tp:docstring>Initial timeout for the rule.</tp:docstring> - </tp:member> - - <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]"> - <tp:docstring>The forwarding targets (an array of type - <tp:type>Forwarding_Rule_Entry</tp:type>). - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Forwarding_Rule_Map" array-name=""> - <tp:docstring>A dictionary whose keys are forwarding conditions and - whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs. - </tp:docstring> - - <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> - <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain" - name="Rule_Chain" /> - </tp:mapping> - - <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name=""> - <tp:docstring>A dictionary whose keys are forwarding conditions and - whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> - for the condition. - </tp:docstring> - <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> - <tp:member type="u" name="Chain_Length" /> - </tp:mapping> - - <property name="SupportedForwardingConditions" type="a{uu}" access="read" - tp:type="Supported_Forwarding_Conditions_Map" - tp:name-for-bindings="Supported_Forwarding_Conditions"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map of forwarding conditions supported on this connection to - maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> - supported for the specific condition.</p> - - <tp:rationale> - <p>When forwarding is done by the provider, different providers - might support different chain sizes, or provider and local - implementation chain sizes might differ.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="ForwardingRules" type="a{u(ua(uu))}" access="read" - tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The current forwarding rules that are enabled for this connection. - Forwarding rules each contain an array of type - <tp:type>Forwarding_Rule_Entry</tp:type>.</p> - </tp:docstring> - </property> - - <signal name="ForwardingRuleChanged" - tp:name-for-bindings="Forwarding_Rule_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p> - - <p>By the time this is emitted, the property MUST have been updated - with the new rules being active. If any protocol/network - requests must be made, they should be completed before the signal - is emitted.</p> - </tp:docstring> - - <arg name="Condition" type="u" tp:type="Forwarding_Condition"> - <tp:docstring> - The condition of the forwarding rule that's been changed. - </tp:docstring> - </arg> - - <arg name="Timeout" type="u"> - <tp:docstring> - The new initial timeout for the rule. - </tp:docstring> - </arg> - - <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> - <tp:docstring> - The new (and as of the emission of the signal, currently active) - forwards. The order is relevant; those at the lowest array index - are used first. - </tp:docstring> - </arg> - </signal> - - <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule"> - <tp:docstring> - Update the forwarding rules. - </tp:docstring> - - <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The forwarding rule to override. Note that this SHOULD not affect - other rules; setting a rule that overrides others (such as - Forwarding_Rule_Unconditional) will not modify other rules. This - means that when a client sets Forwarding_Rule_Busy and then - temporarily sets Forwarding_Rule_Unconditional, the - Forwarding_Rule_Busy rule will retain settings after - Forwarding_Rule_Unconditional, has been unset.</p> - - <p>If the CM has no choice but to adjust multiple rules after a call - to this function (ie, due to the network or protocol forcing such - behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref> - signals for each changed rule. The order of the signals is - implementation-dependent, with the only requirement that the - last signal is for the rule that was originally requested to have - been changed (e.g. if Unconditional automatically modifies - Busy and NoReply, three - separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the - last signal being for Forwarding_Rule_Unconditional).</p> - - <p>Each forwarding condition will occur no more than once in - the rule array. Setting a rule will overwrite the old rule - with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p> - </tp:docstring> - </arg> - - <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> - <tp:docstring> - The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to - activate for the rule. An empty array will effectively disable the - rule. - </tp:docstring> - </arg> - - <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> - <tp:docstring> - The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>). - This is the list of entries that is being replaced with the call to - <tp:member-ref>SetForwardingRule</tp:member-ref>. - </tp:docstring> - </arg> - <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:docstring> - The specified Condition is not supported by this connection, - or the number of chained - <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should - be checked prior to calling - <tp:member-ref>SetForwardingRule</tp:member-ref>. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - A Handle that has been supplied is invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Keepalive.xml b/qt4/spec/Connection_Interface_Keepalive.xml deleted file mode 100644 index 9f4ac6833..000000000 --- a/qt4/spec/Connection_Interface_Keepalive.xml +++ /dev/null @@ -1,73 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Keepalive" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2010 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.Connection.Interface.Keepalive.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.21.2">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Most messaging protocols allow the client to send periodic - content-less pings to the server when the connection is otherwise idle, - to reassure both itself and the server that its connection is still - alive. Depending on the nature of the network connection, and the - device running the client, the desired interval between such pings may - vary.</p> - - <tp:rationale> - <p>For instance, on a mobile handset connected via 3G, - overly-frequent keepalives can drain the battery through needlessly - waking up the radio, and a relatively high interval is appropiate. By - contrast, a desktop computer is less likely to be asleep in the first - place, and users expect dropped connections to be noticed as soon as - possible.</p> - </tp:rationale> - - <p>This interface provides a - <tp:member-ref>KeepaliveInterval</tp:member-ref> property which - controls the frequency of keepalive pings, if any. Connection managers - implementing this property should also include it in <tp:dbus-ref - namespace='org.freedesktop.Telepathy'>Protocol.Parameters</tp:dbus-ref> - with the <code>DBus_Property</code> flag, allowing the desired value to - be stored in <tp:dbus-ref - namespace='org.freedesktop.Telepathy'>Account.Parameters</tp:dbus-ref> - and passed onto the connection by the account manager.</p> - </tp:docstring> - - <property name="KeepaliveInterval" type="u" access="readwrite" - tp:name-for-bindings="Keepalive_Interval" - tp:is-connection-parameter='och aye'> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The time in seconds between pings sent to the server to ensure that - the connection is still alive, or <tt>0</tt> to disable such - pings.</p> - - <p>This property (and parameter) supersedes the older - <tt>keepalive-interval</tt> - <tp:type>Connection_Parameter_Name</tp:type>.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Location.xml b/qt4/spec/Connection_Interface_Location.xml deleted file mode 100644 index fe5492345..000000000 --- a/qt4/spec/Connection_Interface_Location.xml +++ /dev/null @@ -1,464 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Location" - 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: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.Connection.Interface.Location"> - <tp:added version="0.17.27">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface on connections to support protocols which allow users to - publish their current geographical location, and subscribe to the - current location of their contacts.</p> - - <p>This interface is geared strongly towards automatic propagation and - use of this information, so focuses on latitude, longitude and - altitude which can be determined by GPS, although provision is also - included for an optional human-readable description of locations. All - co-ordinate information is required to be relative to the WGS84 - datum.</p> - - <p>The information published through this interface is intended to have - the same scope as presence information, so will normally be made - available to those individuals on the user's "publish" contact list. - Even so, user interfaces should not automatically publish location - information without the consent of the user, and it is recommended - that an option is made available to reduce the accuracy of the - reported information to allow the user to maintain their privacy.</p> - - <p>Location information is represented using the terminology of XMPP's - <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a> - or the XEP-0080-derived - <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where - possible.</p> - - <p>Clients of this interface SHOULD register an interest in it by calling - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref> with an argument - containing the name of this interface, - before calling any Location method. If they do so, they SHOULD also call - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> after use to allow - the CM to release resources associated with this interface.</p> - </tp:docstring> - - <!-- Potentially to be reinstated later: - http://bugs.freedesktop.org/show_bug.cgi?id=19585 - <tp:enum name="Location_Accuracy_Level" type="i"> - <tp:docstring> - A location accuracy level. This should be kept in sync with - GeoclueAccuracyLevel in the Geoclue project. - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - The accuracy is unspecified. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Country" value="1"> - <tp:docstring> - The location indicates the contact's country. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Region" value="2"> - <tp:docstring> - The location indicates the contact's region within a country. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Locality" value="3"> - <tp:docstring> - The location indicates the contact's locality within a region - (e.g. the correct city). - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Postal_Code" value="4"> - <tp:docstring> - The location indicates the correct postal code. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Street" value="5"> - <tp:docstring> - The location indicates the correct street. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Detailed" value="6"> - <tp:docstring> - The location's accuracy is given by the accuracy key. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - --> - - <tp:mapping name="Location"> - <tp:docstring> - A user's location, represented as an extensible mapping. - </tp:docstring> - - <tp:member name="Key" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - - <p>Civic addresses are represented by the following well-known - keys (all of which have string values), which should be kept in - sync with those used in XEP-0080 and in the Geoclue project:</p> - - <ul> - <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country - code, e.g. "us", "gb", "fr"</li> - <li>country - s: a country name in unspecified locale, e.g. - "USA"</li> - <li>region - s: an administrative region of the nation, such as a - state or province</li> - <li>locality - s: a locality within the administrative region, such - as a town or city</li> - <li>area - s: a named area such as a campus or neighborhood</li> - <li>postalcode - s: a code used for postal delivery</li> - <li>street - s: a thoroughfare within the locality, or a crossing of - two thoroughfares</li> - </ul> - - <p>The following address keys are defined in XEP-0080 but not by - Geoclue, and are also allowed:</p> - - <ul> - <li>building - s: a specific building on a street or in an area</li> - <li>floor - s: a particular floor in a building</li> - <li>room - s: a particular room in a building</li> - <li>text - s: any more specific information, e.g. - "Northwest corner of the lobby"</li> - <li>description - s: A natural-language name for or description of - the location, e.g. "Bill's house"</li> - <li>uri - s: a URI representing the location or pointing to more - information about it</li> - </ul> - - <p>Since the previous strings have data intended to be read by users, - the language used should be stated using:</p> - - <ul> - <li>language - s: a specific language or locale of location - information in a format compatible to RFC 4646. Note that UTF-8 - is the only allowed encoding, e.g. "en" or "fr-CA".</li> - </ul> - - <p>Positions are represented by the following well-known keys:</p> - - <ul> - <li>lat - d: latitude in decimal degrees north, -90 to +90, - relative to the WGS-84 datum - <tp:rationale> - This is from XEP-0080; the XEP allows use of a different - datum, but recommends this one. We enforce sanity by requiring - a consistent datum: a minimal compliant implementation of this - specification in terms of XEP-0080 would simply ignore the - <lat> and <lon> elements if <datum> exists - and has a value other than WGS-84, while an advanced - implementation might correct for the different datum. - </tp:rationale> - </li> - <li>lon - d: Longitude in decimal degrees east, -180 to +180, - relative to the WGS-84 datum - <tp:rationale> - Same rationale as 'lat' - </tp:rationale> - </li> - <li>alt - d: altitude in metres above sea level (negative - if below sea level) - <tp:rationale> - This is from XEP-0080 - </tp:rationale> - </li> - - <!-- Potentially to be reinstated later: - http://bugs.freedesktop.org/show_bug.cgi?id=19585 - <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>): - an indication of accuracy, which SHOULD be omitted if it would be - Location_Accuracy_Level_None or - Location_Accuracy_Level_Detailed - <tp:rationale> - This is a struct field in GeoClue; the name is new in this - specification, and was chosen in an attempt to avoid clashing - with any future XEP-0080 terminology. - </tp:rationale> - </li> - --> - - <li>accuracy - d: horizontal position error in metres if - known - <tp:rationale> - This is from XEP-0080 - </tp:rationale> - </li> - </ul> - - <p>Velocities are represented by the following well-known keys:</p> - - <ul> - <li>speed - d: speed in metres per second - <tp:rationale> - This is from XEP-0080 - </tp:rationale> - </li> - <li>bearing - d: direction of movement in decimal degrees, - where North is 0 and East is 90 - <tp:rationale> - This is from XEP-0080, and is equivalent to the struct field - called "direction" in GeoClue - </tp:rationale> - </li> - </ul> - - <p>Other well-known keys:</p> - - <ul> - <li>timestamp - x (<tp:type>Unix_Timestamp64</tp:type>): the time - that the contact was at this location, in seconds since - 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC) - <tp:rationale> - XEP-0080 uses an ISO 8601 string for this, but a number of - seconds since the epoch is probably easier to work with. - </tp:rationale> - </li> - </ul> - </tp:docstring> - </tp:member> - - <tp:member name="Value" type="v"> - <tp:docstring> - The value corresponding to the well-known key. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:mapping name="Contact_Locations" type="a{ua{sv}}"> - <tp:docstring> - A map from contacts to their locations. - </tp:docstring> - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring>A contact</tp:docstring> - </tp:member> - <tp:member name="Location" type="a{sv}" tp:type="Location"> - <tp:docstring>The contact's location, which MAY be empty to indicate - that the contact's location is unknown</tp:docstring> - </tp:member> - </tp:mapping> - - <method name="GetLocations" tp:name-for-bindings="Get_Locations"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Return the current locations of the given contacts, if they are - already known. If any of the given contacts' locations are not known, - request their current locations, but return immediately without waiting - for a reply; if a reply with a non-empty location is later received - for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref> - signal will be emitted for them.</p> - - <tp:rationale> - <p>This method is appropriate for "lazy" location finding, for instance - displaying the location (if available) of everyone in your contact - list.</p> - </tp:rationale> - - <p>For backwards compatibility, if this method is called by a client - whose "interest count" for this interface, as defined by <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref>, is zero, the - Connection SHOULD behave as if AddClientInterest had been called for - this interface just before that method call. Clients that do not - explicitly call AddClientInterest SHOULD NOT call <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> - </tp:docstring> - - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The contacts whose locations should be returned or signalled. - </tp:docstring> - </arg> - - <arg direction="out" name="Locations" type="a{ua{sv}}" - tp:type="Contact_Locations"> - <tp:docstring> - The contacts' locations, if already known. Contacts whose locations - are not already known are omitted from the mapping; contacts known - to have no location information appear in the mapping with an empty - Location dictionary. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <method name="RequestLocation" tp:name-for-bindings="Request_Location"> - <tp:docstring> - Return the current location of the given contact. If necessary, make - a request to the server for up-to-date information, and wait for a - reply. - - <tp:rationale> - This method is appropriate for use in a "Contact Information..." - dialog; it can be used to show progress information (while waiting - for the method to return), and can distinguish between various error - conditions. - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact whose location should be returned. - </tp:docstring> - </arg> - - <arg direction="out" name="Location" type="a{sv}" tp:type="Location"> - <tp:docstring> - The contact's location. It MAY be empty, indicating that no location - information was found. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> - <tp:docstring> - The requested contact does not allow the local user to see their - location information. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated"> - <tp:docstring> - Emitted when a contact's location changes or becomes known. - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact - </tp:docstring> - </arg> - <arg name="Location" type="a{sv}" tp:type="Location"> - <tp:docstring> - The contact's location, or empty to indicate that nothing is known - about the contact's location. - </tp:docstring> - </arg> - </signal> - - <method name="SetLocation" tp:name-for-bindings="Set_Location"> - <tp:docstring> - Set the local user's own location. - </tp:docstring> - - <arg direction="in" name="Location" type="a{sv}"> - <tp:docstring> - The location to advertise. If the user wants to obscure their - exact location by reducing the precision or accuracy, clients - MUST do this themselves, rather than relying on the connection - manager to do so. Clients that interact with more than one - connection SHOULD advertise the same reduced-accuracy location - to all of them, so that contacts cannot obtain an undesirably - accurate location by assuming that random errors have been added - and averaging the locations advertised on multiple connections. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The user's server does not support publishing their own location. - If it is possible to determine this ahead of time, the - <code>Can_Set</code> flag will not be set in - <tp:member-ref>SupportedLocationFeatures</tp:member-ref>. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <property name="LocationAccessControlTypes" type="au" access="read" - tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types"> - <tp:docstring>The types of access control that are supported by this - connection.</tp:docstring> - </property> - - <property name="LocationAccessControl" type="(uv)" access="readwrite" - tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control"> - <tp:docstring>The current access control mechanism and settings - for this connection. Before publishing location for the first time, - if this has not been set by a client, implementations SHOULD - set it to be as restrictive as possible (an empty whitelist, if - supported).</tp:docstring> - </property> - - <property name="SupportedLocationFeatures" - tp:name-for-bindings="Supported_Location_Features" - type="u" tp:type="Location_Features" access="read"> - <tp:added version="0.19.6"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Indicates the Location features supported by this connection. This - property MAY be undefined before <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref> - becomes <code>Connected</code>, but MUST remain constant thereafter. - </tp:docstring> - </property> - - <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature"> - <tp:flag suffix="Can_Set" value="1"> - <tp:docstring> - Indicates that setting your own location with - <tp:member-ref>SetLocation</tp:member-ref> is supported on this - connection. - </tp:docstring> - </tp:flag> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Flags describing the Location features which may be supported on any - given connection. - </tp:docstring> - </tp:flags> - - <tp:contact-attribute name="location" - type="a{sv}" tp:type="Location"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same mapping that would be returned by - <tp:member-ref>GetLocations</tp:member-ref> for this contact. - Omitted from the result if the contact's location - is not known.</p> - - <p>For backwards compatibility, if contact attributes that include - this interface are requested - by a client whose "interest count" for this interface, as defined by - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref>, is zero, the - Connection SHOULD behave as if AddClientInterest was called for this - interface just before that request. Clients that do not explicitly - call AddClientInterest SHOULD NOT call <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Mail_Notification.xml b/qt4/spec/Connection_Interface_Mail_Notification.xml deleted file mode 100644 index 395e1019d..000000000 --- a/qt4/spec/Connection_Interface_Mail_Notification.xml +++ /dev/null @@ -1,624 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Mail_Notification" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" - > - <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Connection.Interface.MailNotification"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.21.3">(as stable API)</tp:added> - - <tp:client-interest> - <tp:docstring> - A client MUST notify interest in this feature before it will be - enabled. - </tp:docstring> - </tp:client-interest> - - <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" > - <tp:flag suffix="Supports_Unread_Mail_Count" value="1"> - <tp:docstring> - This Connection provides the number of unread e-mails (or e-mail - threads) in the main folder of your e-mail account, as the - <tp:member-ref>UnreadMailCount</tp:member-ref> property. The - connection manager will update this value by emitting the - <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Supports_Unread_Mails" value="2"> - <tp:docstring> - This Connection provides a detailed list of unread e-mails, as the - <tp:member-ref>UnreadMails</tp:member-ref> property. If this flag - is set, <tt>Supports_Unread_Mail_Count</tt> MUST be set, and - <tt>Emits_Mails_Received</tt> MUST NOT be set. - The Connection will update the list by emitting the - <tp:member-ref>UnreadMailsChanged</tp:member-ref> signals. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Emits_Mails_Received" value="4"> - <tp:docstring> - This Connection emits the <tp:member-ref>MailsReceived</tp:member-ref> - signal, which provides details about newly arrived e-mails but does - not maintain their read/unread status afterwards. This flag MUST NOT - be combined with <tt>Supports_Unread_Mails</tt>. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Supports_Request_Inbox_URL" value="8"> - <tp:docstring> - This Connection can provide a URL (with optional POST data) to - open the the inbox of the e-mail account in a web-based client, via - the <tp:member-ref>RequestInboxURL</tp:member-ref> method. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Supports_Request_Mail_URL" value="16"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This Connection can provide a URL (with optional POST data) to open - a specific mail in a web-based client, via the - <tp:member-ref>RequestMailURL</tp:member-ref> method. This feature - is not useful unless either Emits_Mails_Received or - Supports_Unread_Mails is set.</p> - - <p>If this flag is not set, clients SHOULD fall back to using - <tp:member-ref>RequestInboxURL</tp:member-ref> if available.</p> - </tp:docstring> - </tp:flag> - <tp:flag suffix="Thread_Based" value="32"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Each <tp:type>Mail</tp:type> represents a thread of e-mails, which - MAY have more than one sender.</p> - - <tp:rationale> - <p>Google Talk notifies users about new mail in terms of unread - threads, rather than unread e-mails.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:docstring> - <p>Flags representing capabilities provided by a connection manager. - Those values can be used as bitfield. Some flags depend on, or - conflict with, each other.</p> - - <p>Connections SHOULD implement as many of these features as the - underlying protocol allows, preferring to implement - Supports_Unread_Mails instead of Emits_Mails_Received if both are - possible.</p> - </tp:docstring> - </tp:flags> - - <tp:enum name="HTTP_Method" type="u"> - <tp:enumvalue suffix="Get" value="0"> - <tp:docstring> - Use the GET method when opening the URL. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Post" value="1"> - <tp:docstring> - Use the POST method when opening the URL. Refer to - <tp:type>HTTP_Post_Data</tp:type> for more details. - </tp:docstring> - </tp:enumvalue> - <tp:docstring> - The HTTP Method with which to request a URL. - </tp:docstring> - </tp:enum> - - <tp:struct name="HTTP_Post_Data" array-name="HTTP_Post_Data_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A pair (key, value) representing POST data compatible with the - application/x-www-form-urlencoded MIME type. The strings MUST be - valid UTF-8 strings, and the characters used in the key MUST obey - the requirements of the - <a href="http://www.w3.org/TR/html401/types.html#type-cdata"> - HTML CDATA type</a>. The value MUST NOT be - encoded with HTML entities.</p> - - <p>For example, if the POST data should contain a key "less-than" with value - "<", and a key "percent" with value "%", this should be represented as - two HTTP_Post_Data structures, ("less-than", "<") and ("percent", "%"), - resulting in a POST request whose request body is "less-than=&lt;&percent=%25". - If a client passes this to a browser by writing it into an HTML form, it - could do so by representing it as:</p> - - <pre> - <input type="hidden" name="less-than">&lt;</input> - <input type="hidden" name="percent">%</input> - </pre> - - <tp:rationale> - <p>This data can be used to generate a HTML file that will - automatically load the URL with appropriate POST data, in which case - the client MUST convert any characters that are special within HTML - into HTML entities. Alternatively, it can be used in an API that will - instruct the browser how to load the URL (like the Netscape Plug-in - API), in which case the client MUST escape - <a href="http://www.ietf.org/rfc/rfc1738.txt">characters that are - reserved in URLs</a>, if appropriate for that API.</p> - - <p>An array of pairs is used instead of a map from keys to values, - because it's valid to repeat keys in both HTML and - x-www-form-urlencoded data.</p> - </tp:rationale> - </tp:docstring> - <tp:member type="s" name="Key"> - <tp:docstring>The key, corresponding to a HTML control - name</tp:docstring> - </tp:member> - <tp:member type="s" name="Value"> - <tp:docstring>The value</tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Mail_Address" array-name="Mail_Address_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A pair (name, address) representing an e-mail address, - such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At - least one of name and address MUST be provided. A missing element will - be represented by the empty string.</p> - <tp:rationale> - <p>The CM should provide as much information as possible, but not all - protocols provide both the displayed name and the address. (If a - protocol doesn't provide either, it should omit the appropriate - field from the <tp:type>Mail</tp:type> entirely.)</p> - </tp:rationale> - </tp:docstring> - <tp:member type="s" name="Name"> - <tp:docstring>The displayed name corresponding to the e-mail - address</tp:docstring> - </tp:member> - <tp:member type="s" name="Address"> - <tp:docstring>The actual e-mail address</tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Mail_URL"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A structure containing the required information to open a web-based - e-mail UI, without needing re-authentication (if possible).</p> - - <p>Because the URL and POST data frequently contain short-lived - credential tokens, a new URL should be requested (by calling one of - the methods that returns a Mail_URL) for each visit to the web-based - UI, and the URL should be visited soon after it is returned.</p> - </tp:docstring> - <tp:member type="s" name="URL"> - <tp:docstring> - The URL to which to send a request. - </tp:docstring> - </tp:member> - <tp:member type="u" name="Method" tp:type="HTTP_Method"> - <tp:docstring> - The HTTP method of the request. - </tp:docstring> - </tp:member> - <tp:member type="a(ss)" name="Post_Data" tp:type="HTTP_Post_Data[]"> - <tp:docstring> - An array of name-value pairs containing the POST data to use when - opening the URL. This MUST be an empty array if the Method is not - POST. - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Mail" array-name="Mail_List"> - <tp:docstring> - An extensible map representing a mail, or (on protocols where - <tt>Thread_Based</tt> appears in - <tp:member-ref>MailNotificationFlags</tp:member-ref>) a thread of - mails. All keys are optional where not otherwise stated; however, at - least one of "senders" and "subject" must be included. - </tp:docstring> - - <tp:member type="s" name="Key"> - <tp:docstring> - <p>A key providing information about the mail or thread. Well-known - keys are as follows:</p> - - <dl> - <dt>id — s</dt> - <dd> - <p>A unique ID for this e-mail. CMs with - <tt>Supports_Unread_Mails</tt> set in - <tp:member-ref>MailNotificationFlags</tp:member-ref> MUST provide - this key in each <tp:type>Mail</tp:type>.</p> - - <p>If provided, the ID SHOULD be unique to a Mail at least until - that mail is removed with the - <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal - (in protocols with <tt>Supports_Unread_Emails</tt>), or - unique for the duration of a session (otherwise).</p> - - <tp:rationale> - <p>In protocols with Supports_Unread_Mails, this key is used to - indicate which mail was removed. In protocols without that - feature, it's impossible to tell when a mail has been removed - (and hence how long the identifier will remain valid for use - with <tp:member-ref>RequestMailURL</tp:member-ref>).</p> - </tp:rationale> - </dd> - - <dt>url-data — any type</dt> - <dd>An opaque identifier (typically a string or list of strings) - provided to the Connection when calling - <tp:member-ref>RequestMailURL</tp:member-ref>, - containing information used by the Connection to build the URL. - </dd> - - <dt>senders — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> - <dd> - An array of sender display name and e-mail address pairs. Note that - only e-mails represented as a thread can have multiple senders. - </dd> - - <dt>to-addresses — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> - <dd> - An array of display name and e-mail address pairs representing - the recipients. - </dd> - - <dt>cc-addresses — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> - <dd> - An array of display name and e-mail address pairs representing - the carbon-copy recipients. - </dd> - - <dt>sent-timestamp — x (<tp:type>Unix_Timestamp64</tp:type>)</dt> - <dd>A UNIX timestamp indicating when the message was sent, or for - a thread, when the most recent message was sent. - </dd> - - <dt>received-timestamp — x (<tp:type>Unix_Timestamp64</tp:type>)</dt> - <dd>A UNIX timestamp indicating when the message was received, or for - a thread, when the most recent message was received. - </dd> - - <dt>has-attachments — b</dt> - <dd>If true, this mail has attachments.</dd> - - <dt>subject — s</dt> - <dd> - The subject of the message. This MUST be encoded in UTF-8. - </dd> - - <dt>content-type — s</dt> - <dd> - <p>The MIME type of the message content. Two types are currently - supported: "text/plain" for plain text, and "text/html" for a - HTML document. If omitted, "text/plain" MUST be assumed. - Regardless of MIME type, the content MUST be valid UTF-8 (which - may require that the Connection transcodes it from a legacy - encoding).</p> - - <tp:rationale> - <p>All strings on D-Bus must be UTF-8.</p> - </tp:rationale> - </dd> - - <dt>truncated — b</dt> - <dd> - If true, the content is only a partial message; if false or - omitted, the content is the entire message. - </dd> - - <dt>content — s</dt> - <dd> - The body of the message, possibly truncated, encoded as appropriate - for "content-type". - </dd> - - <dt>folder — s</dt> - <dd> - The name of the folder containing this e-mails. - If omitted, the inbox SHOULD be assumed. - </dd> - </dl> - </tp:docstring> - </tp:member> - - <tp:member name="Value" type="v"> - <tp:docstring>The value, of whatever type is appropriate for the - key.</tp:docstring> - </tp:member> - </tp:mapping> - - <property name="MailNotificationFlags" type="u" access="read" - tp:type="Mail_Notification_Flags" - tp:name-for-bindings="Mail_Notification_Flags"> - <tp:docstring> - Integer representing the bitwise-OR of supported features for e-mails - notification on this server. This property MUST NOT change after the - Connection becomes CONNECTED. - - <tp:rationale> - This property indicates the behavior and availability - of the other properties and signals within this interface. A - connection manager that cannot at least set one of the flags - in the <tp:type>Mail_Notification_Flags</tp:type> - SHOULD NOT provide this interface. - </tp:rationale> - </tp:docstring> - </property> - - <property name="UnreadMailCount" type="u" access="read" - tp:name-for-bindings="Unread_Mail_Count"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The number of unread messages in the Inbox. Change notification is - via <tp:member-ref>UnreadMailsChanged</tp:member-ref>.</p> - - <p>This property is only useful if <tt>Supports_Unread_Mail_Count</tt> - is set in the <tp:member-ref>MailNotificationFlags</tp:member-ref>; - otherwise, it MUST be zero.</p> - - <p>If <tt>Thread_Based</tt> appears in the - <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property - counts the number of threads, not the number of mails.</p> - - <p>Note that this count MAY be bigger than the number of items in - <tp:member-ref>UnreadMails</tp:member-ref>. See - <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p> - </tp:docstring> - </property> - - <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]" - tp:name-for-bindings="Unread_Mails" access="read"> - <tp:docstring> - <p>An array of unread <tp:type>Mail</tp:type>s. Change notification is - via <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property - is only useful if <tt>Supports_Unread_Mails</tt> is set in - <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it - MUST be an empty list.</p> - <p>The array size MAY be shorter than - <tp:member-ref>UnreadMailCount</tp:member-ref>.</p> - <tp:rationale> - <p>Some servers may limits the amount of detailed e-mails sent. This - can significantly reduce the network traffic for large inbox. For - this reason, it is normal that - <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal - to the size of this array.</p> - </tp:rationale> - </tp:docstring> - </property> - - <property name="MailAddress" type="s" - tp:name-for-bindings="Mail_Address" access="read"> - <tp:docstring> - A string representing the e-mail address of the account. The CMs MUST - provide this information. - <tp:rationale> - In close integration of MailNotification with other e-mail services, - the e-mail address can be used has a unique identifier for the - account. Possible integration could be between Telepathy and - Evolution where the e-mail address is the common information in - both interfaces. - </tp:rationale> - </tp:docstring> - </property> - - <signal name="MailsReceived" tp:name-for-bindings="Mails_Received"> - <arg name="Mails" type="aa{sv}" tp:type="Mail[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of <tp:type>Mail</tp:type>s. Those e-mail MUST NOT have - the "id" key.</p> - - <tp:rationale> - <p>On connections that emit this signal, it's impossible to tell - when a mail has been removed, and hence when "id" has become - invalid.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <tp:docstring> - Emitted when new e-mails messages arrive to the inbox associated with - this connection. This signal is used for protocols that are not able - to maintain the <tp:member-ref>UnreadMails</tp:member-ref> list, but - do provide real-time notification about newly arrived e-mails. It MUST - NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in - <tp:member-ref>MailNotificationFlags</tp:member-ref>. - </tp:docstring> - </signal> - - <signal name="UnreadMailsChanged" - tp:name-for-bindings="Unread_Mails_Changed"> - <arg name="Count" type="u"> - <tp:docstring> - Number of unread messages in the inbox (the new value of - <tp:member-ref>UnreadMailCount</tp:member-ref>). - </tp:docstring> - </arg> - <arg name="Mails_Added" type="aa{sv}" tp:type="Mail[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of <tp:type>Mail</tp:type> that are being added or updated - in <tp:member-ref>UnreadMails</tp:member-ref>.</p> - - <tp:rationale> - <p>Mails may be updated when the URL information (URL and POST data) - have changed, or senders were added or removed from an e-mail - thread.</p> - </tp:rationale> - - <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list - MUST be empty, even if Count has increased.</p> - </tp:docstring> - </arg> - <arg name="Mails_Removed" type="as"> - <tp:docstring> - A list of e-mail IDs that are being removed from - <tp:member-ref>UnreadMails</tp:member-ref>. - If the <tt>Supports_Unread_Mails</tt> flag is not set, this list - MUST be empty, even if Count has decreased. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or - <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST - NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set - in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p> - - <p><tt>Mails_Added</tt> and - <tt>Mails_Removed</tt> MUST be empty if the - <tt>Supports_Unread_Mails</tt> flag is not set.</p> - </tp:docstring> - </signal> - - <method name="RequestInboxURL" - tp:name-for-bindings="Request_Inbox_URL"> - <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" > - <tp:docstring> - A struture containing a URL and optional additional data to open a - webmail client, without re-authentication if possible. - </tp:docstring> - </arg> - <tp:docstring> - This method creates and returns a URL and an optional POST data that - allow opening the Inbox folder of a webmail account. This URL MAY - contain tokens with a short lifetime, so clients SHOULD request a new - URL for each visit to the webmail interface. This method is implemented - only if the <tt>Supports_Request_Inbox_URL</tt> flag is set in - <tp:member-ref>MailNotificationFlags</tp:member-ref>. - - <tp:rationale> - We are not using properties here because the tokens are unsuitable - for sharing between clients, and network round-trips may be required - to obtain the information that leads to authentication free webmail - access. - </tp:rationale> - </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.NotImplemented"/> - </tp:possible-errors> - </method> - - <method name="RequestMailURL" - tp:name-for-bindings="Request_Mail_URL"> - <arg direction="in" name="ID" type="s"> - <tp:docstring> - The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type> - structure, or the empty string if no <tt>id</tt> key was provided. - </tp:docstring> - </arg> - <arg direction="in" name="URL_Data" type="v"> - <tp:docstring> - Whatever <tt>url-data</tt> was found in the <tp:type>Mail</tp:type> - structure, or the boolean value False (D-Bus type 'b') if no - <tt>url-data</tt> was provided in the Mail. - </tp:docstring> - </arg> - <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" > - <tp:docstring> - A struture that contains a URL and optional additional data to open a - webmail client, without re-authentication if possible. - </tp:docstring> - </arg> - <tp:docstring> - This method creates and returns a URL and optional POST data that - allow opening a specific mail in a webmail interface. This - method is implemented only if <tt>Supports_Request_Mail_URL</tt> flag - is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>. - <tp:rationale> - See <tp:member-ref>RequestInboxURL</tp:member-ref> for design - rationale. - </tp:rationale> - </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.NotImplemented"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - </tp:possible-errors> - </method> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface to support receiving notifications about a e-mail - account associated with this connection.</p> - - <p>In protocols where this is possible, this interface also allows the - connection manager to provide the necessary information for clients - to open a web-based mail client without having to re-authenticate.</p> - - <p>To use this interface, a client MUST first subscribe by passing the - name of this interface to the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref> method. The subscription - mechanic aims at reducing network traffic and memory footprint in the - situation where nobody is currently interesting in provided - information. When done with this interface, clients SHOULD call - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> to allow the CM to - release resources.</p> - - <p>Protocols have various different levels of Mail Notification support. - To describe the level of support, the interface provides a property - called <tp:member-ref>MailNotificationFlags</tp:member-ref>. - Not all combinations are valid; protocols can be divided into four - categories as follows.</p> - - <p>Connections to the most capable protocols, such as Google's XMPP Mail - Notification extension, have the Supports_Unread_Mails flag (this - implies that they must also have Supports_Unread_Mail_Count, but not - Emits_Mails_Received). On these connections, clients - requiring change notification MUST monitor the - <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and - either recover the initial state from the - <tp:member-ref>UnreadMails</tp:member-ref> property (if they require - details other than the number of mails) or the - <tp:member-ref>UnreadMailCount</tp:member-ref> property (if they - are only interested in the number of unread mails). The - <tp:member-ref>MailsReceived</tp:member-ref> signal is never emitted - on these connections, so clients that will display a short-term - notification for each new mail MUST do so in response to emission of - the <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.</p> - - <p>The most common situation, seen in protocols like MSN and Yahoo, is - that the number of unread mails is provided and kept up-to-date, - and a separate notification is emitted with some details of each new - mail. This is a combination of the following two features, and clients - SHOULD implement one or both as appropriate for their requirements.</p> - - <p>On protocols that have the Emits_Mails_Received flag (which implies - that they do not have Supports_Unread_Mails), the CM does not keep - track of any mails; it simply emits a notification whenever new mail - arrives. Those events may be used for short term display (like a - notification popup) to inform the user. No protocol is known to support - only this feature, but it is useful for integration with libraries that - that do not implement tracking of the number of mails. Clients - requiring these notifications MUST monitor the - <tp:member-ref>MailsReceived</tp:member-ref> signal on any connections - with this flag.</p> - - <p>On protocols that have the Supports_Unread_Mail_Count flag but not - the Supports_Unread_Mails flag, clients cannot display complete - details of unread email, but can display an up-to-date count of the - <em>number</em> of unread mails. To do this, they must monitor the - <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and - retrieve the initial state from the - <tp:member-ref>UnreadMailCount</tp:member-ref> property.</p> - - <p> - Orthogonal features described by the - <tp:member-ref>MailNotificationFlags</tp:member-ref> property include the - RequestSomethingURL methods, which are used to obtain URLs allowing - clients to open a webmail client. Connections SHOULD support as many - of these methods as possible.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> - diff --git a/qt4/spec/Connection_Interface_Power_Saving.xml b/qt4/spec/Connection_Interface_Power_Saving.xml deleted file mode 100644 index 571bf6d51..000000000 --- a/qt4/spec/Connection_Interface_Power_Saving.xml +++ /dev/null @@ -1,109 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Power_Saving" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" - > - <tp:copyright> Copyright © 2007-2010 Collabora Limited </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> - </tp:license> - <interface - name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving"> - <tp:added version="0.21.5">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Some protocols support mechanisms for reducing bandwidth usage—and - hence power usage, on mobile devices—when the user is not directly - interacting with their IM client. For instance, Google Talk's XMPP - server supports queueing incoming presence updates at the client's - instruction; the client can instruct the server to deliver all - outstanding presence updates at a later time. This interface may be - used to instruct the connection manager to enable and disable such - protocol-level features when a screensaver is activated, the device - screen is locked, and so on, by calling the - <tp:member-ref>SetPowerSaving</tp:member-ref> method.</p> - - <p>Enabling power saving SHOULD NOT change behaviour in any way - that is noticable to a user not actively interacting with their client. - For example, delaying presence updates somewhat is unlikely to be - noticed by a user not staring at their device waiting for a contact to - come online; on the other hand, requesting that the server queue - incoming messages would be noticable by the user, so is not an - acceptable effect of calling - <tp:member-ref>SetPowerSaving</tp:member-ref>.</p> - </tp:docstring> - - <method name="SetPowerSaving" tp:name-for-bindings="Set_Power_Saving"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Turn power saving mode on or off.</p> - - <tp:rationale> - <p>Depending on the device's activity level, the - connection can have its power saving mode turned on or off.</p> - </tp:rationale> - - <p>Errors raised by this method indicate that power saving could not be - enabled, which SHOULD NOT generally be treated as fatal.</p> - - <tp:rationale> - If the CM cannot switch modes, either because of the - protocol (<code>NotImplemented</code>), or because of the service - (<code>NotAvailable</code>), Mission Control (or whoever manages this) - should be made aware. The error could be ignored or, in the extreme, - be fascist and disconnect the account. - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Activate" type="b"> - <tp:docstring> - <code>True</code> if protocol-level power saving features should be - activated; <code>False</code> if they should be de-activated. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The current connection has no power saving features. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> - </tp:possible-errors> - </method> - - <property name="PowerSavingActive" type="b" access="read" - tp:name-for-bindings="Power_Saving_Active"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p><code>True</code> if protocol-level power saving features are - currently activated. This property can be changed using the - <tp:member-ref>SetPowerSaving</tp:member-ref> method; change - notifications is via the - <tp:member-ref>PowerSavingChanged</tp:member-ref> signal.</p> - </tp:docstring> - </property> - - <signal name="PowerSavingChanged" - tp:name-for-bindings="Power_Saving_Changed"> - <arg name="Active" type="b"> - <tp:docstring> - The new state of the power saving feature. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The <tp:member-ref>PowerSavingActive</tp:member-ref> - property changed. - </tp:docstring> - </signal> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Presence.xml b/qt4/spec/Connection_Interface_Presence.xml deleted file mode 100644 index 8a344d416..000000000 --- a/qt4/spec/Connection_Interface_Presence.xml +++ /dev/null @@ -1,346 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> - Copyright (C) 2005, 2006 Collabora Limited - </tp:copyright> - <tp:copyright> -Copyright (C) 2005, 2006 Nokia Corporation - </tp:copyright> - <tp:copyright> -Copyright (C) 2006 INdT - </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.Presence"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> - - <tp:mapping name="Multiple_Status_Map"> - <tp:docstring>Mapping used in - <tp:type>Last_Activity_And_Statuses</tp:type> and passed to - <tp:member-ref>SetStatus</tp:member-ref>, representing a collection of - statuses. Use of this mapping with more than one member is - deprecated.</tp:docstring> - <tp:member type="s" name="Status"/> - <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> - </tp:mapping> - <tp:struct name="Last_Activity_And_Statuses" array-name=""> - <tp:docstring>Structure representing a contact's presence, containing - a last-activity time (deprecated) and a Multiple_Status_Map. - </tp:docstring> - <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/> - <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map" - name="Statuses"/> - </tp:struct> - <tp:mapping name="Contact_Presences"> - <tp:docstring>Mapping returned by - <tp:member-ref>GetPresence</tp:member-ref> and signalled by - <tp:member-ref>PresenceUpdate</tp:member-ref>, where the keys are - contacts and the values represent their presences.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> - <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses" - name="Presence"/> - </tp:mapping> - <tp:struct name="Status_Spec" array-name=""> - <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/> - <tp:member type="b" name="May_Set_On_Self"/> - <tp:member type="b" name="Exclusive"/> - <tp:member type="a{ss}" tp:type="String_String_Map" - name="Parameter_Types"/> - </tp:struct> - <tp:mapping name="Status_Spec_Map"> - <tp:member type="s" name="Identifier"/> - <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/> - </tp:mapping> - - <method name="AddStatus" tp:name-for-bindings="Add_Status"> - <arg direction="in" name="Status" type="s"> - <tp:docstring> - The string identifier of the desired status - </tp:docstring> - </arg> - <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring> - A dictionary of optional parameter names mapped to their variant-boxed values - </tp:docstring> - </arg> - <tp:docstring> - Request that a single presence status is published for the user, along - with any desired parameters. Changes will be indicated by - <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. - </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.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - <method name="ClearStatus" tp:name-for-bindings="Clear_Status"> - <tp:docstring> - Request that all of a user's presence statuses be removed. Be aware - that this request may simply result in the statuses being replaced by a - default available status. Changes will be indicated by - <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. - </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.PermissionDenied"/> - </tp:possible-errors> - </method> - <method name="GetPresence" tp:name-for-bindings="Get_Presence"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of the contacts whose presence should be obtained - </tp:docstring> - </arg> - <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}" - tp:type="Contact_Presences"> - <tp:docstring> - Presence information in the same format as for the - <tp:member-ref>PresenceUpdate</tp:member-ref> signal - </tp:docstring> - </arg> - <tp:docstring> - Get presence previously emitted by - <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts. - Data is returned in the same structure as the PresenceUpdate signal. - Using this method in favour of - <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that - it will not wake up each client connected to the PresenceUpdate signal. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - <method name="GetStatuses" tp:name-for-bindings="Get_Statuses"> - <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map" - name="Available_Statuses"> - <tp:docstring> - A dictionary of string identifiers mapped to a struct for each status, containing: - <ul> - <li>a type value from one of the values above</li> - <li>a boolean to indicate if this status may be set on yourself</li> - <li>a boolean to indicate if this is an exclusive status which you - may not set alongside any other</li> - <li>a dictionary of valid optional string argument names mapped to - their types</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - Get a dictionary of the valid presence statuses for this connection. - This is only available when online because only some statuses will - be available on some servers. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - <signal name="PresenceUpdate" tp:name-for-bindings="Presence_Update"> - <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences"> - <tp:docstring> - A dictionary of contact handles mapped to a struct containing - a UNIX timestamp of the last activity time (in UTC), and - a dictionary mapping the contact's current status identifiers to - a dictionary of optional parameter names mapped to their - variant-boxed values - </tp:docstring> - </arg> - <tp:docstring> - This signal should be emitted when your own presence has been changed, - or the presence of the member of any of the connection's channels has - been changed, or when the presence requested by - <tp:member-ref>RequestPresence</tp:member-ref> is available. - </tp:docstring> - </signal> - <method name="RemoveStatus" tp:name-for-bindings="Remove_Status"> - <arg direction="in" name="Status" type="s"> - <tp:docstring> - The string identifier of the status not to publish anymore for the user - </tp:docstring> - </arg> - <tp:docstring> - Request that the given presence status is no longer published for the - user. Changes will be indicated by - <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As - with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may - actually result in it being replaced by a default available status. - </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.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring>The status requested is not currently set</tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - <method name="RequestPresence" tp:name-for-bindings="Request_Presence"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of the contacts whose presence should be obtained - </tp:docstring> - </arg> - <tp:docstring> - Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref> - signal will be emitted when they are received. This is not the same as - subscribing to the presence of a contact, which must be done using the - 'subscription' <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>, - and on some protocols presence information may not be available unless - a subscription exists. - </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.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The presence of the requested contacts is not reported to this connection - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - <method name="SetLastActivityTime" - tp:name-for-bindings="Set_Last_Activity_Time"> - <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - A UNIX timestamp of the user's last activity time (in UTC) - </tp:docstring> - </arg> - <tp:docstring> - Request that the recorded last activity time for the user be updated on - the server. - </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.NotImplemented"> - <tp:docstring> - This protocol has no concept of idle time - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - <method name="SetStatus" tp:name-for-bindings="Set_Status"> - <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map"> - <tp:docstring> - A dictionary mapping status identifiers to dictionaries, which - map optional parameter names to their variant-boxed values - </tp:docstring> - </arg> - <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"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp: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 is for services which have a concept of presence which - can be published for yourself and monitored on your contacts. - Telepathy's definition of presence is based on that used by - <a href="http://www.galago-project.org/">the Galago project</a>.</p> - - <p>Presence on an individual (yourself or one of your contacts) is modelled as - a last activity time along with a set of zero or more statuses, each of - which may have arbitrary key/value parameters. Valid statuses are defined - 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 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 - <tp:type>Connection_Presence_Type</tp:type> which can be used by the client - to classify even unknown statuses into different fundamental types.</p> - - <p>These numerical types exist so that even if a client does not understand - the string identifier being used, and hence cannot present the presence to - the user to set on themselves, it may display an approximation of the - presence if it is set on a contact.</p> - - <p>The dictionary of variant types allows the connection manager to exchange - further protocol-specific information with the client. It is recommended - that the string (s) argument 'message' be interpreted as an optional - message which can be associated with a presence status.</p> - - <p>If the connection has a 'subscribe' contact list, - <tp:member-ref>PresenceUpdate</tp:member-ref> signals should be emitted to - indicate changes of contacts on this list, and should also be emitted for - changes in your own presence. Depending on the protocol, the signal may - also be emitted for others such as people with whom you are communicating, - and any user interface should be updated accordingly.</p> - - <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> may - only succeed on contacts on your 'subscribe' list, and other contacts will - cause a PermissionDenied error. On protocols where there is no 'subscribe' - list, and RequestPresence succeeds, a client may poll the server - intermittently to update any display of presence information.</p> - </tp:docstring> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Privacy.xml b/qt4/spec/Connection_Interface_Privacy.xml deleted file mode 100644 index b89d968f4..000000000 --- a/qt4/spec/Connection_Interface_Privacy.xml +++ /dev/null @@ -1,94 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Privacy" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.Privacy" - tp:causes-havoc='not well-tested'> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <method name="GetPrivacyMode" tp:name-for-bindings="Get_Privacy_Mode"> - <arg direction="out" type="s"> - <tp:docstring> - A string representing the current privacy mode - </tp:docstring> - </arg> - <tp:docstring> - Return the current privacy mode, which must be one of the values - returned by GetPrivacyModes. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - <method name="GetPrivacyModes" tp:name-for-bindings="Get_Privacy_Modes"> - <arg direction="out" type="as"> - <tp:docstring> - An array of valid privacy modes for this connection - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Returns the privacy modes available on this connection. The following - well-known names should be used where appropriate: - <dl> - <dt>allow-all</dt><dd>any contact may initiate communication</dd> - <dt>allow-specified</dt><dd>only contacts on your 'allow' list may initiate communication</dd> - <dt>allow-subscribed</dt><dd>only contacts on your subscription list may initiate communication</dd> - </dl> - </tp:docstring> - </method> - <signal name="PrivacyModeChanged" - tp:name-for-bindings="Privacy_Mode_Changed"> - <arg name="Mode" type="s"> - <tp:docstring> - The current privacy mode - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the privacy mode is changed or the value has been - initially received from the server. - </tp:docstring> - </signal> - <method name="SetPrivacyMode" tp:name-for-bindings="Set_Privacy_Mode"> - <arg direction="in" name="Mode" type="s"> - <tp:docstring> - The desired privacy mode - </tp:docstring> - </arg> - <tp:docstring> - Request that the privacy mode be changed to the given value, which - must be one of the values returned by GetPrivacyModes. Success is - indicated by the method returning and the PrivacyModeChanged - signal being emitted. - </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.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - </tp:possible-errors> - </method> - <tp:docstring> - An interface to support getting and setting privacy modes to configure - situations such as not being contactable by people who are not on your - subscribe list. If this interface is not implemented, the default can be - presumed to be allow-all (as defined in GetPrivacyModes). - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Renaming.xml b/qt4/spec/Connection_Interface_Renaming.xml deleted file mode 100644 index d08b748d9..000000000 --- a/qt4/spec/Connection_Interface_Renaming.xml +++ /dev/null @@ -1,98 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Renaming" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Connection.Interface.Renaming" - tp:causes-havoc='not well-tested'> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <signal name="Renamed" tp:name-for-bindings="Renamed"> - <arg name="Original" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the original identifier - </tp:docstring> - </arg> - <arg name="New" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the new identifier - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the unique identifier of a contact on the server - changes.</p> - - <p>Any channels associated with the contact's original handle will - continue to be to that handle, and so are no longer useful (unless - the contact renames back, or another contact connects with that - unique ID). Clients may open a similar channel associated with the - new handle to continue communicating with the contact.</p> - - <p>For example, if a GUI client associates text - channels with chat windows, it should detach the old channel - from the chat window, closing it, and associate a channel to the - new handle with the same window.</p> - - <p>If the contact's old handle is in any of the member lists of - a channel which has the groups interface, it will be removed from - the channel and the new handle will be added. The resulting - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> - signal must be emitted <em>after</em> the - <tp:member-ref>Renamed</tp:member-ref> signal; the reason should be - RENAMED. - </p> - - <p>The handles may be either general-purpose or channel-specific. - If the original handle is general-purpose, the new handle must be - general-purpose; if the original handle is channel-specific, the - new handle must be channel-specific in the same channel. - </p> - </tp:docstring> - </signal> - <method name="RequestRename" tp:name-for-bindings="Request_Rename"> - <arg direction="in" name="Identifier" type="s"> - <tp:docstring> - The desired identifier - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that the user's own identifier is changed on the server. - If successful, a <tp:member-ref>Renamed</tp:member-ref> signal will - be emitted for the current "self handle" as returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>.</p> - <p>It is protocol-dependent how the identifier that's actually - used will be derived from the supplied identifier; some sort of - normalization might take place.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - <tp:docstring> - An interface on connections to support protocols where the unique - identifiers of contacts can change. Because handles are immutable, - this is represented by a pair of handles, that representing the - old name, and that representing the new one. - </tp:docstring> - </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 deleted file mode 100644 index 2f233fa53..000000000 --- a/qt4/spec/Connection_Interface_Requests.xml +++ /dev/null @@ -1,628 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Requests" - 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: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.Connection.Interface.Requests"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.17.11">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An enhanced version of the Telepathy connection interface, which can - represent bundles of channels that should be dispatched together, and - does not assume any particular properties by which channels are - uniquely identifiable.</p> - - <p>If this interface is implemented on a connection, then - <tp:member-ref>NewChannels</tp:member-ref> MUST be emitted for - all new channels, even those created with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection" - >RequestChannel</tp:dbus-ref>.</p> - </tp:docstring> - - <tp:struct name="Channel_Details" array-name="Channel_Details_List"> - <tp:added version="0.17.11">(as stable API)</tp:added> - - <tp:docstring> - Enough details of a channel that clients can work out how to dispatch - or handle it. - </tp:docstring> - - <tp:member name="Channel" type="o"> - <tp:docstring> - The object path of the channel. - </tp:docstring> - </tp:member> - - <tp:member name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties of the channel.</p> - - <p>Connection managers MUST NOT include properties in this mapping - if their values can change. Clients MUST ignore properties - that appear in this mapping if their values can change.</p> - - <tp:rationale> - <p>If properties that could change were included, the following - race condition would be likely to exist in some cases:</p> - - <ul> - <li>NewChannels or Get("Channels") includes a property P with - value V1</li> - <li>Client creates a proxy object for the channel</li> - <li>The value of P changes to V2</li> - <li>Client connects to PChanged signal</li> - <li>Client should call Get("P") or GetAll here, to avoid the - race, but client's author has forgotten to do so</li> - <li>Proxy object thinks P == V1, but actually P == V2</li> - </ul> - - <p>We've taken the opportunity to make the API encourage the - client author to get it right. Where possible, we intend that - properties whose value will be used in channel dispatching - or other "early" processing will be defined so that they are - immutable (can never change).</p> - </tp:rationale> - - <p>Each dictionary MUST contain the keys - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>, - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>, - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>, - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref> - and - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>. - </p> - - <tp:rationale> - <p>We expect these to be crucial to the channel-dispatching - process.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:changed version="0.17.14">It is now guaranteed that - CreateChannel returns the channel before NewChannels announces it - (the reverse was previously guaranteed).</tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that an entirely new channel is created.</p> - - <tp:rationale> - <p>There is deliberately no flag corresponding to the - suppress_handler argument to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>, - because passing a FALSE value for that argument is deprecated. - Requests made using this interface always behave as though - suppress_handler was TRUE.</p> - </tp:rationale> - - </tp:docstring> - - <arg direction="in" name="Request" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties, which MUST include - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>. - Some properties - are defined such that only an exact match makes sense, and - connection managers MUST NOT satisfy a request with a channel - where that property does not match; some properties are defined - such that the connection manager MAY treat the request as merely - a hint, and make a best-effort attempt to satisfy it. This is - documented separately for each property.</p> - - <p>If this dictionary contains a property whose semantics - are not known to the connection manager, this method MUST fail - without side-effects (in particular it must not create a new - channel).</p> - - <tp:rationale> - <p>This is necessary if we want to be able to invent properties - in future that, when used in a request, are hard requirements - rather than just hints. A connection manager that did not know - the semantics of those properties could incorrectly return a - new channel that did not satisfy the requirements.</p> - </tp:rationale> - - <p>The connection manager MUST NOT respond successfully, - and SHOULD NOT create a new channel or cause any other - side-effects, unless it can create a new channel that satisfies - the client's requirements.</p> - - <p>Properties that will be set by this argument need not have write - access after the channel has been created - indeed, it is - expected that most will be read-only.</p> - </tp:docstring> - </arg> - - <arg name="Channel" direction="out" type="o"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The Channel object, which MUST NOT be signalled with - <tp:member-ref>NewChannels</tp:member-ref> until after this method - returns.</p> - - <tp:rationale> - <p>This allows the requester to alter its handling of - NewChannels by knowing whether one of the channels satisfied - a request it made.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="Properties" direction="out" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties of the channel that was produced, equivalent to - the properties in <tp:type>Channel_Details</tp:type>. - Connection managers MUST NOT include properties here whose - values can change, for the same reasons as in - <tp:type>Channel_Details</tp:type>.</p> - </tp:docstring> - </arg> - - <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.NotImplemented"> - <tp:docstring> - The channel request was one that can never succeed, - such as requesting an unsupported channel type, or requesting - a channel type which this connection manager does not support with - the given target handle type. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - An invalid handle was requested as the value of a property whose - value is a handle (like - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), - or a syntactically invalid identifier was requested as the value - of a property whose value is the string corresponding to a handle - (like <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The request matched the fixed properties of a - <tp:type>Requestable_Channel_Class</tp:type> in - <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the - allowed arguments did not make sense; for example, a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> - was requested, but the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> - property provided was not a valid DNS name. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> - <tp:docstring> - The requested channel cannot be created because the requested - 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 - principle, a similar request might succeed in future. - For instance, this might be because:</p> - - <ul> - <li>a channel matching the request already exists and the - protocol requires that only one such channel can exist at a - time</li> - <li>a channel matching the request has already been requested - (by a previous call to CreateChannel, - <tp:member-ref>EnsureChannel</tp:member-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> - or similar) and the protocol requires that only one such - channel can exist at a time</li> - </ul> - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> - <tp:added version="0.17.12"/> - <tp:changed version="0.17.14">It is now guaranteed that if - the channel was created by this call to EnsureChannel, it's returned - before NewChannels announces it (the reverse was previously - guaranteed).</tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that channels are ensured to exist.</p> - - <tp:rationale> - <p>The connection manager is in the best position to determine which - existing channels could satisfy which requests.</p> - </tp:rationale> - - </tp:docstring> - - <arg direction="in" name="Request" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A dictionary containing desirable properties, with the same - semantics as the corresponding parameter to - <tp:member-ref>CreateChannel</tp:member-ref>.</p> - </tp:docstring> - </arg> - - <arg name="Yours" direction="out" type="b"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If false, the caller of EnsureChannel MUST assume that some - other process is handling this channel; if true, the caller of - EnsureChannel SHOULD handle it themselves or delegate it to another - client.</p> - - <p>If the creation of a channel makes several calls to EnsureChannel - (and no other requests) successful, exactly one of those calls MUST - return a true value for this argument.</p> - - <p>If the creation of a channel makes other requests successful, - the value returned for this argument MUST be such that exactly - one of the clients making requests ends up responsible for the - channel. In particular, if - <tp:member-ref>CreateChannel</tp:member-ref> returns a channel - <em>C</em>, any EnsureChannel calls that also return <em>C</em> - MUST return a false value for this argument.</p> - </tp:docstring> - </arg> - - <arg name="Channel" direction="out" type="o"> - <tp:docstring> - The Channel object. If it was created as a result of this method - call, it MUST NOT be signalled by - <tp:member-ref>NewChannels</tp:member-ref> until after this method - returns. - - <tp:rationale> - <p>This allows the requester to alter its handling of - NewChannels by knowing whether one of the channels satisfied - a request it made.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <arg name="Properties" direction="out" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties of the channel that was produced, equivalent to - the properties in <tp:type>Channel_Details</tp:type>. - Connection managers MUST NOT include properties here whose - values can change, for the same reasons as in - <tp:type>Channel_Details</tp:type>.</p> - </tp:docstring> - </arg> - - <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.NotImplemented"> - <tp:docstring> - The channel request was one that can never succeed, - such as requesting an unsupported channel type, or requesting - a channel type which this connection manager does not support with - the given target handle type. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> - <tp:docstring> - An invalid handle was requested as the value of a property whose - value is a handle (like - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), - or a syntactically invalid identifier was requested as the value - of a property whose value is the string corresponding to a handle - (like <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The request matched the fixed properties of a - <tp:type>Requestable_Channel_Class</tp:type> in - <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the - allowed arguments did not make sense; for example, a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> - was requested, but the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> - property provided was not a valid DNS name. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> - <tp:docstring> - The requested channel cannot be created because the requested - 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 - principle, a similar request might succeed in future. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> - <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </method> - - <signal name="NewChannels" tp:name-for-bindings="New_Channels"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:changed version="0.17.14">Added a guarantee of ordering - relative to NewChannel</tp:changed> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>New channels have been created. The connection manager SHOULD emit - a single signal for any group of closely related channels that are - created at the same time, so that the channel dispatcher can try to - dispatch them to a handler as a unit.</p> - - <p>In particular, if additional channels are created as a side-effect - of a call to <tp:member-ref>CreateChannel</tp:member-ref>, - these channels SHOULD appear in the same NewChannels signal as - the channel that satisfies the request.</p> - - <tp:rationale> - <p>Joining a MUC Tube in XMPP requires joining the corresponding - MUC (chatroom), so a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> - channel can be created as a side-effect.</p> - </tp:rationale> - - <p>Every time NewChannels is emitted, it MUST be followed by - a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> - signal for each channel.</p> - - <tp:rationale> - <p>The double signal emission is for the benefit of older Telepathy - clients, which won't be listening for NewChannels.</p> - - <p>The more informative NewChannels signal comes first so that - clients that did not examine the connection to find - out whether Requests is supported will see the more informative - signal for each channel first, and then ignore the less - informative signal because it announces a new channel of which - they are already aware.</p> - </tp:rationale> - </tp:docstring> - - <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"> - <tp:docstring> - The channels and their details. All channels that are signalled - together like this MUST have the same - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> - property, which may - either refer to an existing bundle, or establish a new bundle. - </tp:docstring> - </arg> - </signal> - - <property name="Channels" tp:name-for-bindings="Channels" - type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring> - A list of all the channels which currently exist on this connection. - Change notification is via the - <tp:member-ref>NewChannels</tp:member-ref> and - <tp:member-ref>ChannelClosed</tp:member-ref> signals. - </tp:docstring> - </property> - - <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring> - Emitted when a channel is closed and hence disappears from the - <tp:member-ref>Channels</tp:member-ref> property. - - <tp:rationale> - This is redundant with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref> - signal on the channel itself, but it does provide full change - notification for the Channels property. - </tp:rationale> - </tp:docstring> - - <arg name="Removed" type="o"> - <tp:docstring> - The channel which has been removed from the Channels property - </tp:docstring> - </arg> - </signal> - - <tp:mapping name="Channel_Class" array-name="Channel_Class_List"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Mapping representing a class of channels that can be requested - from a connection manager, can be handled by a user interface, - are supported by a contact, etc.</p> - - <p>Classes of channel are identified by the fixed values of - a subset of their properties.</p> - - <p>Channel classes SHOULD always include the keys - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref> - and - <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>. - </p> - </tp:docstring> - - <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> - <tp:docstring> - A D-Bus interface name, followed by a dot and a D-Bus property name. - </tp:docstring> - </tp:member> - - <tp:member type="v" name="Value"> - <tp:docstring> - The value of the property. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:struct name="Requestable_Channel_Class" - array-name="Requestable_Channel_Class_List"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Structure representing a class of channels that can be requested, - identified by a set of properties that identify that class of - channel.</p> - - <tp:rationale> - <p>This will often just be the channel type and the handle type, - but can include other properties of the channel - for instance, - encrypted channels might require properties that - unencrypted channels do not, like an encryption key.</p> - </tp:rationale> - - <p>In some cases, these classes of channel may overlap, in the sense - that one class fixes all the properties that another class does, - plus some more properties.</p> - - <tp:rationale> - <p>For older clients to still be able to understand how to request - channels in the presence of a hypothetical "encryption" interface, - we'd need to represent it like this:</p> - - <ul> - <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li> - <li>class 2: Channel.ChannelType = Text, - Channel.TargetHandleType = CONTACT, - Encryption.Encrypted = TRUE</li> - </ul> - </tp:rationale> - </tp:docstring> - - <tp:member name="Fixed_Properties" type="a{sv}" - tp:type="Channel_Class"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The property values that identify this requestable channel class. - These properties MUST be included in requests for a channel of this - class, and MUST take these values.</p> - - <p>Clients that do not understand the semantics of all the - Fixed_Properties MUST NOT request channels of this class, since - they would be unable to avoid making an incorrect request.</p> - - <p>This implies that connection managers wishing to make channels - available to old or minimal clients SHOULD have a channel class - with the minimum number of Fixed_Properties, and MAY additionally - have channel classes with extra Fixed_Properties.</p> - - <p>Interface designers SHOULD avoid introducing fixed properties - whose types are not serializable in a <code>.manager</code> - file.</p> - - <tp:rationale> - <p>Connection managers with a fixed property that is not - serializable cannot have a complete <code>.manager</code> - file.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - - <tp:member name="Allowed_Properties" type="as" - tp:type="DBus_Qualified_Member[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties that MAY be set when requesting a channel of this - channel type and handle type.</p> - - <p>This array MUST NOT include properties that are in the - Fixed_Properties mapping.</p> - - <p>Properties in this array may either be required or optional, - according to their documented semantics.</p> - - <tp:rationale> - <p>For instance, if - TargetHandleType takes a value that is not Handle_Type_None, - one or the other of TargetHandle and TargetID is required. - Clients are expected to understand the documented relationship - between the properties, so we do not have separate arrays - of required and optional properties.</p> - </tp:rationale> - - <p>If this array contains the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> - property, then this class of channel can be combined with other - channels with that property in a request, or added to an existing - bundle. If not, this signifies that the connection manager is - unable to mark channels of this class as part of a bundle - this - means that to the remote contact they are likely to be - indistinguishable from channels requested separately.</p> - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="RequestableChannelClasses" access="read" - type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" - tp:name-for-bindings="Requestable_Channel_Classes"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The classes of channel that are expected to be available on this - connection, i.e. those for which - <tp:member-ref>CreateChannel</tp:member-ref> can reasonably - be expected to succeed. User interfaces can use this information - to show or hide UI components.</p> - - <p>This property cannot change after the connection has gone to - state Connection_Status_Connected, so there is no change - notification (if the connection has context-dependent capabilities, - it SHOULD advertise support for all classes of channel that it might - support during its lifetime). Before this state has been reached, - the value of this property is undefined.</p> - - <tp:rationale> - <p>This is not on an optional interface, because connection - managers can always offer some sort of clue about the channel - classes they expect to support (at worst, they can announce - support for everything for which they have code).</p> - </tp:rationale> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Resources.xml b/qt4/spec/Connection_Interface_Resources.xml deleted file mode 100644 index 716089cd6..000000000 --- a/qt4/spec/Connection_Interface_Resources.xml +++ /dev/null @@ -1,212 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Resources" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Connection.Interface.Resources.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.1">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface on connections to show contact attributes for - specific resources of a contact, if the protocol supports - multiple resources. Resources are most common in XMPP, hence the - name of this interface, but they are also present in MSN, where - they are called points of presence.</p> - - <p>When a client requests some attribute of a contact using its - handle on the connection, the CM uses an algorithm to choose the - most appropriate resource for the job. If there is only one - resource, then the choice is obvious. If, however, there is more - than one resource connected at any one time, the CM either - aggregates all appropriate information to return (in the case of - capabilities), or chooses one specific resource (in the case of - presence).</p> - - <p>Resources in XMPP have names, and it can be extremely useful - for the user to be able to know which resources of a contact are - online, providing the names are human-readable. Before now, - resources have not been exposed in Telepathy, but this interface - attempts to change this.</p> - - <p>When using this interface, it is a little like using the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface" - >Contacts</tp:dbus-ref> interface, but only resource-specific - attributes are ever returned. The resource-specific contact - attributes are decided on by the CM, but XMPP's are listed - below:</p> - - <ul> - <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li> - <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li> - <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/client-types</tp:dbus-ref></li> - </ul> - - </tp:docstring> - - <method name="GetResources" tp:name-for-bindings="Get_Resources"> - <tp:docstring> - Return the resource information of the given contacts. If any - of the contact attributes for specific resources of the given - contacts' are not known return immediately without waiting for - a reply. - </tp:docstring> - - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The contacts whose resource attributes should be returned. - </tp:docstring> - </arg> - - <arg direction="out" name="Resources" type="a{ua{sa{sv}}}" - tp:type="Resources_Attributes_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contacts' resources and the contact attributes specific - to each resource. If contact attributes are not immediately - known, the behaviour is defined by the interface; the - attribute should either be omitted from the result or - replaced with a default value.</p> - - <p>For every contact handle passed into this method, it is - guaranteed that there will be a key in the returned map - that corresponds to said handle. If there is no information - regarding the contact the resource information map will be - empty.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> - </method> - - <tp:enum name="Resources_Human_Readability" type="u"> - <tp:enumvalue suffix="Never" value="0"> - <tp:docstring> - The resource string is never human-readable. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Maybe" value="1"> - <tp:docstring> - The resource string might be human-readable. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="ResourcesHumanReadable" type="u" access="read" - tp:type="Resources_Human_Readability" - tp:name-for-bindings="Resources_Human_Readable"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref> - are human readable or not.</p> - - <p>If the connection manager knows that all resource names are - automatically generated, then the resource strings mean - nothing to the user. Showing these strings in the UI would - be confusing, so by setting this to - Resources_Human_Readability_Never, the UI is advised not to - show resources.</p> - - <p>If on the other hand, all resources are set to nice names - (such as "office" or "home") then it might be wise to expose - these strings in the UI, so this property would be set to - Resources_Human_Readability_Maybe. This is the case in XMPP -- - most resources are set in a way that the user can deduce some - information from them. The absence of an Always enum value is - because in the case of XMPP, the resource string could be - partially human-readable (as on Google Talk, where a resource - of "home" is changed by the server to a unique string like - "home_1234fdec") or not at all human-readable.</p> - - </tp:docstring> - </property> - - <signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated"> - <tp:docstring> - Emitted when a contact has a resource added or removed, or any - contact attribute for any resource changes. - </tp:docstring> - - <arg name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact. - </tp:docstring> - </arg> - <arg name="Resources" tp:type="Resource_Information_Map" - type="a{sa{sv}}"> - <tp:docstring> - The contact's resource information. All resource information - is given, not just the details which have changed. - </tp:docstring> - </arg> - </signal> - - <tp:mapping name="Resource_Information_Map"> - <tp:docstring> - A map of a contact's resources to their resource-specific - information. - </tp:docstring> - - <tp:member name="Key" type="s"> - <tp:docstring> - <p>The name of the resource.</p> - </tp:docstring> - </tp:member> - - <tp:member name="Contact_Attributes" type="a{sv}" - tp:type="Single_Contact_Attributes_Map"> - <tp:docstring> - A map of contact attributes whose data is specific to this - resource. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:mapping name="Resources_Attributes_Map"> - <tp:docstring>Mapping returned by - <tp:member-ref>GetResources</tp:member-ref>, representing a - collection of Contacts, their resources, and their - resource-specific contact attributes.</tp:docstring> - - <tp:member type="u" tp:type="Contact_Handle" name="Contact"> - <tp:docstring> - A contact. - </tp:docstring> - </tp:member> - - <tp:member type="a{sa{sv}}" tp:type="Resource_Information_Map" - name="Resources"> - <tp:docstring> - A map of the contact's resources to their resource-specific - information. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:contact-attribute name="resources" type="a{sa{sv}}" - tp:type="Resource_Information_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same mapping that would be returned by - <tp:member-ref>GetResources</tp:member-ref> for this contact.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Service_Point.xml b/qt4/spec/Connection_Interface_Service_Point.xml deleted file mode 100644 index b135c04c7..000000000 --- a/qt4/spec/Connection_Interface_Service_Point.xml +++ /dev/null @@ -1,136 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2005-2010 Collabora Ltd </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.Connection.Interface.ServicePoint"> - <tp:added version="0.19.7">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connections whose channels may be able to indicate - specific they are connected to some form - of service station. For example, when - dialing 9-1-1 in the US, a GSM modem/network will recognize that as - an emergency call, and inform higher levels of the stack that the - call is being handled by an emergency service. In this example, - the call is handled by a Public Safety Answering Point (PSAP) which is labeled - as "urn:service:sos". Other networks and protocols may handle this - differently while still using this interface.</p> - </tp:docstring> - - <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List"> - <tp:member type="(us)" tp:type="Service_Point" name="Service_Point"> - <tp:docstring> - The service point. - </tp:docstring> - </tp:member> - <tp:member type="as" name="Service_IDs"> - <tp:docstring> - A list of IDs that are mapped to this service. This is provided as - a convenience for the UIs, but the preferred method for - requesting channel to a service is by setting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint">InitialServicePoint</tp:dbus-ref> - property in a channel request. - </tp:docstring> - </tp:member> - <tp:docstring> - <p>Description of a service point and IDs which are mapped to it.</p> - - <p>An example Service Point info for GSM emergency calls (callable - through "911" and "112") could look like:</p> - -<pre> - ServicePointInfo = ( - Service_Point: ( - Service_Point_Type: 1 (Emergency), - Service_Point: "urn:service:sos" - ), - Service_IDs: [ "911", "112" ] - ) -</pre> - </tp:docstring> - </tp:struct> - - <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points" - type="a((us)as)" tp:type="Service_Point_Info[]" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The list of all (known) service points. - </tp:docstring> - </property> - - <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed"> - <arg name="Service_Points" type="a((us)as)" tp:type="Service_Point_Info[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The new value of - <tp:member-ref>KnownServicePoints</tp:member-ref>.</p> - </tp:docstring> - </arg> - <tp:docstring> - Emitted when the list of known service points (or their IDs) has - changed. - </tp:docstring> - </signal> - - <tp:struct name="Service_Point"> - <tp:docstring>A service point.</tp:docstring> - <tp:member type="u" name="Service_Point_Type" - tp:type="Service_Point_Type"> - <tp:docstring> - The service type. - </tp:docstring> - </tp:member> - <tp:member type="s" name="Service"> - <tp:docstring> - String representation of the service point. The representation is - service specific; it may be a 'service' Uniform Resource Name as - specified by <a - href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>, - or may be in some other form. Empty, unused or unknown value is - represented by "". - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:enum name="Service_Point_Type" type="u"> - <tp:docstring> - The various types of service points a channel might connect to. - </tp:docstring> - - <tp:enumvalue value="0" suffix="None"> - <tp:docstring> - The channel is not communicating with a service point, or it is not - known whether it is communicating with a service point (e.g. an - ordinary call). - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="1" suffix="Emergency"> - <tp:docstring> - The service point is a generic emergency point. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue value="2" suffix="Counseling"> - <tp:docstring> - The service point is some kind of counseling service (ie, mental health - or child-services counseling). - </tp:docstring> - </tp:enumvalue> - </tp:enum> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Simple_Presence.xml b/qt4/spec/Connection_Interface_Simple_Presence.xml deleted file mode 100644 index 7788161e1..000000000 --- a/qt4/spec/Connection_Interface_Simple_Presence.xml +++ /dev/null @@ -1,634 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Simple_Presence" 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, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or (at - your option) any later version.</p> - - <p>This library is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 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.Connection.Interface.SimplePresence"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - - <tp:struct name="Simple_Presence"> - <tp:docstring> - A struct representing the presence of a contact. - </tp:docstring> - <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"> - <tp:docstring> - The presence type, e.g. Connection_Presence_Type_Away. - </tp:docstring> - </tp:member> - <tp:member type="s" name="Status"> - <tp:docstring> - The string identifier of the status, e.g. "brb", as defined in the - <tp:member-ref>Statuses</tp:member-ref> property. - </tp:docstring> - </tp:member> - <tp:member type="s" name="Status_Message"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The user-defined status message, e.g. "Back soon!".</p> - - <p>Clients SHOULD set the status message for the local - user to the empty string, unless the user has actually provided - a specific message (i.e. one that conveys more information than the - Status).</p> - - <p>User interfaces SHOULD regard an empty status message as unset, - and MAY replace it with a localized string corresponding to the - Status or Type.</p> - - <tp:rationale> - Use case: Daf sets his status in Empathy by choosing the Welsh - translation of "Available" from a menu. - It is more informative for his English-speaking colleagues - to see the English translation of "Available" (as localized - by their own clients) than to see "Ar Gael" (which they don't - understand anyway). - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Simple_Contact_Presences"> - <tp:docstring> - Mapping returned by <tp:member-ref>GetPresences</tp:member-ref> - and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>, - indicating the presence of a number of contacts. - </tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Contact"> - <tp:docstring> - A contact - </tp:docstring> - </tp:member> - <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence"> - <tp:docstring> - The contact's presence - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:struct name="Simple_Status_Spec"> - <tp:docstring> - A struct containing information about a status. - </tp:docstring> - <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"> - <tp:docstring> - The type of a presence. This SHOULD NOT be used as a way to set - statuses that the client does not recognise (as explained in - <tp:member-ref>SetPresence</tp:member-ref>), but MAY be used to check - that the client's assumptions about a particular status name - match the connection manager's. - </tp:docstring> - </tp:member> - <tp:member type="b" name="May_Set_On_Self"> - <tp:docstring> - If true, the user can set this status on themselves using - <tp:member-ref>SetPresence</tp:member-ref>. - </tp:docstring> - </tp:member> - <tp:member type="b" name="Can_Have_Message"> - <tp:docstring> - If true, a non-empty message can be set for this status. Otherwise, - the empty string is the only acceptable message. - - <tp:rationale> - On IRC you can be Away with a status message, but if you are - available you cannot set a status message. - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:mapping name="Simple_Status_Spec_Map"> - <tp:docstring> - A mapping describing possible statuses. - </tp:docstring> - - <tp:member type="s" name="Identifier"> - <tp:docstring> - The string identifier of this status. - </tp:docstring> - </tp:member> - <tp:member type="(ubb)" tp:type="Simple_Status_Spec" name="Spec"> - <tp:docstring> - Details of this status. - </tp:docstring> - </tp:member> - </tp:mapping> - - <method name="SetPresence" tp:name-for-bindings="Set_Presence"> - <arg direction="in" name="Status" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The string identifier of the desired status. Possible status - identifiers are defined in the - <tp:member-ref>Statuses</tp:member-ref> property.</p> - - <p>Clients MUST NOT set a status whose string value they do not - recognise, even if its presence type in Statuses - matches what the user requested.</p> - - <tp:rationale> - <p>Suppose a protocol has statuses that include 'phone' (of type - BUSY) and 'in-a-meeting' (of type BUSY), but there is no - generic 'busy' status.</p> - - <p>If the user requests "Busy" status from a menu, a - client author might be tempted to pick an arbitrary status - that has type BUSY. However, on this protocol, neither of - 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"> - <tp:docstring> - The status message associated with the current status. - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request that the presence status and status message are published for - the connection. Changes will be indicated by - <tp:member-ref>PresencesChanged</tp:member-ref> - signals being emitted.</p> - - <p>This method may be called on a newly-created connection while it - is still in the DISCONNECTED state, to request that when the - connection connects, it will do so with the selected status.</p> - - <p>In DISCONNECTED state the - <tp:member-ref>Statuses</tp:member-ref> - property will indicate which statuses are allowed to be set - while DISCONNECTED (none, if the Connection Manager doesn't allow - this). This value MUST NOT be cached, as the set of allowed - presences might change upon connecting.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - Either the specified status is not supported, the specified - status cannot be set on the user themselves, or a non-empty - message was supplied for a status that does not - accept a message. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <method name="GetPresences" tp:name-for-bindings="Get_Presences"> - <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - An array of the contacts whose presence should be obtained. - </tp:docstring> - </arg> - <arg direction="out" name="Presence" type="a{u(uss)}" - tp:type="Simple_Contact_Presences"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Presence information in the same format as for the - <tp:member-ref>PresencesChanged</tp:member-ref> signal. - The returned mapping MUST include an entry for each contact - in the method's argument.</p> - - <p>The definition of the connection presence types Unknown - and Offline means that if a connection manager will return - Unknown for contacts not on the subscribe list, it MUST delay - the reply to this method call until it has found out which - contacts are, in fact, on the subscribe list.</p> - </tp:docstring> - </arg> - <tp:docstring> - Get presence previously emitted by - <tp:member-ref>PresencesChanged</tp:member-ref> for the given - contacts. Data is returned in the same structure as the - PresencesChanged signal; no additional network requests are made. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"> - <tp:docstring> - While discovering the subscribe list in order to distinguish - between Unknown and Offline statuses, a network error occurred. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - - <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 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. - The connection manager will attempt to set the appropriate status - when the connection becomes connected, but cannot necessarily - guarantee it. The available statuses cannot change until the - connection status changes, so there is no change notification.</p> - - <p>While the connection is in the CONNECTED state, this property - contains the set of presence statuses which are actually available - on this protocol. This set is constant for the remaining lifetime - of the connection, so again, there is no change notification.</p> - - <p>While the connection is in the CONNECTING state, the value of - this property is undefined and SHOULD NOT be used. It can change - at any time without notification (in particular, any cached values - from when the connection was in the DISCONNECTED or CONNECTING - state MUST NOT be assumed to still be correct when the state has - become CONNECTED).</p> - - <p>This property MUST include the special statuses "unknown" and - "error" if and only if the connection manager can emit them - as a contact's status.</p> - - <tp:rationale> - For instance, connection managers for local-xmpp (XEP-0174) would - omit "unknown" since there is no such concept. - </tp:rationale> - </tp:docstring> - </property> - - <signal name="PresencesChanged" tp:name-for-bindings="Presences_Changed"> - <arg name="Presence" type="a{u(uss)}" tp:type="Simple_Contact_Presences"> - <tp:docstring> - A dictionary of contact handles mapped to the status, - presence type and status message. - </tp:docstring> - </arg> - <tp:docstring> - This signal should be emitted when your own presence has been changed, - or the presence of the member of any of the connection's channels has - been changed. - </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="Access_Control_Type" type="u" - array-name="Access_Control_Type_List"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A type for communication access control. These control - policies are used in - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">CommunicationPolicy.DRAFT</tp:dbus-ref> - as well as most rich presence interfaces.</p> - - <p>New interfaces should use this type, and NOT - <tp:type>Rich_Presence_Access_Control_Type</tp:type>.</p> - </tp:docstring> - <tp:enumvalue suffix="Whitelist" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Only allow contacts that are in a certain whitelist.</p> - - <p>The associated variant - in <tp:type>Access_Control</tp:type> is a list of - <tp:type>Contact_Handle</tp:type> representing - the whitelist, with signature <code>au</code>.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Publish_List" value="1"> - <tp:docstring> - Allow contacts in the user's 'publish' list. The associated - variant in <tp:type>Access_Control</tp:type> is ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Group" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Only allow contacts that are in a certain group.</p> - - <p>The associated variant in <tp:type>Access_Control</tp:type> is a - <tp:type>Group_Handle</tp:type> representing the permitted - group.</p> - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="3"> - <tp:docstring> - Allow all contacts. The associated - variant in <tp:type>Access_Control</tp:type> is ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Subscribe_Or_Publish_List" value="4"> - <tp:docstring> - Allow all contacts in the user's 'subscribe' or 'publish' - list. The associated variant in <tp:type>Access_Control</tp:type> is - ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Closed" value="5"> - <tp:docstring> - Forbid all contacts. The associated variant in - <tp:type>Access_Control</tp:type> is ignored. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Not_Understood" value="6"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The access control rule is too complex to be represented - in the current Telepathy API. The associated variant is - meaningless. Setting this mode is never valid; the - connection manager MUST raise an error if this is attempted.</p> - - <tp:rationale> - XEP-0016 Privacy Lists can easily produce access control - mechanisms that can't be expressed in a simpler API. We - need to be able to at least indicate that fact. - </tp:rationale> - - <p>The associated variant in <tp:type>Access_Control</tp:type> is - ignored.</p> - </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 xmlns="http://www.w3.org/1999/xhtml"> - <p>A type of access control for Rich_Presence_Access_Control. - For most types, the exact access control is given by an associated - variant.</p> - - <tp:rationale> - <p>These are the access control types from XMPP publish/subscribe - (XEP-0060).</p> - </tp:rationale> - - <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref> - uses this for historical reasons, new interfaces will use - <tp:type>Access_Control_Type</tp:type>.</p> - </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="Access_Control"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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.</p> - - <p>New interfaces should use this type, and NOT - <tp:type>Rich_Presence_Access_Control</tp:type>.</p> - </tp:docstring> - - <tp:member name="Type" type="u" tp:type="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>Access_Control_Type</tp:type>. - </tp:docstring> - </tp:member> - </tp:struct> - - <tp:struct name="Rich_Presence_Access_Control"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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</tp:dbus-ref>.</p> - - <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref> - uses this for historical reasons, new interfaces will use - <tp:type>Access_Control_Type</tp:type>.</p> - </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:contact-attribute name="presence" - type="(uss)" tp:type="Simple_Presence"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same struct that would be returned by - <tp:member-ref>GetPresences</tp:member-ref> - (always present with some value if information from the - SimplePresence interface was requested)</p> - </tp:docstring> - </tp:contact-attribute> - - <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> - - <p>Presence on an individual (yourself or one of your contacts) is - modelled as a status and a status message. Valid statuses are defined - per connection, and a list of those that can be set on youself - can be obtained from the - <tp:member-ref>Statuses</tp:member-ref> - property.</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 should be - used where possible to allow clients to identify common choices:</p> - - <table> - <tr> - <th>status identifier</th> - <th>Connection_Presence_Type</th> - <th>comments</th> - </tr> - <tr> - <td>available</td> - <td>Connection_Presence_Type_Available</td> - <td></td> - </tr> - <tr> - <td>away</td> - <td>Connection_Presence_Type_Away</td> - <td></td> - </tr> - <tr> - <td>brb</td> - <td>Connection_Presence_Type_Away</td> - <td>Be Right Back (a more specific form of Away)</td> - </tr> - <tr> - <td>busy</td> - <td>Connection_Presence_Type_Busy</td> - <td></td> - </tr> - <tr><td>dnd</td> - <td>Connection_Presence_Type_Busy</td> - <td>Do Not Disturb (a more specific form of Busy)</td> - </tr> - <tr> - <td>xa</td> - <td>Connection_Presence_Type_Extended_Away</td> - <td>Extended Away</td> - </tr> - <tr> - <td>hidden</td> - <td>Connection_Presence_Type_Hidden</td> - <td>Also known as "Invisible" or "Appear Offline"</td> - </tr> - <tr> - <td>offline</td> - <td>Connection_Presence_Type_Offline</td> - <td></td> - </tr> - <tr> - <td>unknown</td> - <td>Connection_Presence_Type_Unknown</td> - <td>special, see below</td> - </tr> - <tr> - <td>error</td> - <td>Connection_Presence_Type_Error</td> - <td>special, see below</td> - </tr> - </table> - - <p>As well as these well-known status identifiers, every status also has - a numerical type value chosen from - <tp:type>Connection_Presence_Type</tp:type> which can be - used by the client to classify even unknown statuses into different - fundamental types.</p> - - <p>These numerical types exist so that even if a client does not - understand the string identifier being used, and hence cannot present - the presence to the user to set on themselves, it may display an - approximation of the presence if it is set on a contact.</p> - - <p>As well as the normal status identifiers, there are two special ones - that may be present: 'unknown' with type Unknown and 'error' with type - Error. 'unknown' indicates that it is impossible to determine the - presence of a contact at this time, for example because it's not on the - 'subscribe' list and the protocol only allows one to determine the - presence of contacts you're subscribed to. 'error' indicates that there - was a failure in determining the status of a contact.</p> - - <p>If the connection has a 'subscribe' contact list, - <tp:member-ref>PresencesChanged</tp:member-ref> - signals should be emitted to indicate changes of contacts on this list, - and should also be emitted for changes in your own presence. Depending - on the protocol, the signal may also be emitted for others such as - people with whom you are communicating, and any user interface should - be updated accordingly.</p> - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Manager.xml b/qt4/spec/Connection_Manager.xml deleted file mode 100644 index 3683fcadf..000000000 --- a/qt4/spec/Connection_Manager.xml +++ /dev/null @@ -1,619 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Manager" 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: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.ConnectionManager"> - - <tp:simple-type name="Connection_Manager_Name" type="s"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of a connection manager, found in its well-known - bus name and object path. This must be a non-empty string of - ASCII letters, digits and underscores, starting with a letter. - This is typically the name of the executable with any "telepathy-" - prefix removed, and any hyphen/minus signs replaced by - underscores.</p> - - <p>Connection manager names SHOULD NOT be the same as the name of - the protocol they implement.</p> - - <tp:rationale> - <p>This is likely to lead to conflicts between different - implementations of the same protocol (or indeed inability - to distinguish between the different implementations!). The - Telepathy project traditionally uses some sort of pun (Haze is - based on libpurple, Salut implements a protocol often called - Bonjour, and Wilde implements the OSCAR protocol).</p> - </tp:rationale> - - <p>Connection manager names SHOULD NOT be the same as the name of - a library on which they are based.</p> - - <tp:rationale> - <p>We often abbreviate, for instance, <i>telepathy-haze</i> as - “Haze”, but abbreviating <i>telepathy-sofiasip</i>—since renamed to - <i>telepathy-rakia</i> for exactly this reason—to “Sofia-SIP” - caused confusion between the connection manager and the library it - uses. Please don't repeat that mistake.</p> - </tp:rationale> - </tp:docstring> - <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed - characters were not specified</tp:changed> - </tp:simple-type> - - <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 - with a letter. Where possible, this SHOULD be - chosen from the following well-known values:</p> - - <ul> - <li>aim - AOL Instant Messenger (OSCAR or TOC)</li> - <li>gadugadu - Gadu-Gadu</li> - <li>groupwise - Novell Groupwise</li> - <li>icq - ICQ (OSCAR)</li> - <li>irc - Internet Relay Chat (RFC 1459, 2810-2813)</li> - <li>jabber - XMPP (RFC 3920, 3921) or Jabber</li> - <li>local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)</li> - <li>msn - MSNP (Windows Live Messenger)</li> - <li>myspace - MySpaceIM</li> - <li>mxit - MXit</li> - <li>napster - Napster</li> - <li>qq - Tencent QQ</li> - <li>sametime - IBM Lotus Sametime</li> - <li>silc - SILC</li> - <li>sip - Session Initiation Protocol (SIP), with or without - SIMPLE support</li> - <li>skype - Skype</li> - <li>tel - telephony (the - <abbr title="Public Switched Telephone Network">PSTN</abbr>, - including GSM, CDMA and fixed-line telephony)</li> - <li>trepia - Trepia</li> - <li>yahoo - YMSG (Yahoo! Messenger)</li> - <li>yahoojp - Japanese version of YMSG</li> - <li>zephyr - Zephyr</li> - </ul> - </tp:docstring> - <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed - characters were not specified</tp:changed> - </tp:simple-type> - - <tp:struct name="Param_Spec" array-name="Param_Spec_List"> - <tp:docstring>A struct representing an allowed parameter, as returned - by GetParameters on the ConnectionManager interface.</tp:docstring> - <tp:member type="s" name="Name"> - <tp:docstring>A string parameter name</tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Conn_Mgr_Param_Flags" name="Flags"> - <tp:docstring>A bitwise OR of the parameter flags</tp:docstring> - </tp:member> - <tp:member type="s" tp:type="DBus_Signature" name="Signature"> - <tp:docstring>A string containing the D-Bus type signature - for this parameter</tp:docstring> - </tp:member> - <tp:member type="v" name="Default_Value"> - <tp:docstring>The default value (if the Has_Default flag is not - present, there is no default and this takes some dummy value, - which SHOULD be of the appropriate D-Bus type)</tp:docstring> - </tp:member> - </tp:struct> - - <tp:flags name="Conn_Mgr_Param_Flags" value-prefix="Conn_Mgr_Param_Flag" type="u"> - <tp:flag suffix="Required" value="1"> - <tp:docstring> - This parameter is required for connecting to the server. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Register" value="2"> - <tp:docstring> - This parameter is required for registering an account on the - server. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Has_Default" value="4"> - <tp:docstring> - This parameter has a default value, which is returned in - GetParameters; not providing this parameter is equivalent to - providing the default. - </tp:docstring> - </tp:flag> - <tp:flag suffix="Secret" value="8"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This parameter should be considered private or secret; for - instance, clients should store it in a "password safe" like - gnome-keyring or kwallet, omit it from debug logs, and use a - text input widget that hides the value of the parameter.</p> - - <p>(Clients that support older connection managers may also treat - any parameter whose name contains "password" as though it had this - flag.)</p> - </tp:docstring> - <tp:added version="0.17.2"/> - </tp:flag> - <tp:flag suffix="DBus_Property" value="16"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This parameter is also a D-Bus property on the resulting - <tp:dbus-ref - namespace="ofdT">Connection</tp:dbus-ref>; a - parameter named <code>com.example.Duck.Macaroni</code> with this - flag corresponds to the <code>Macaroni</code> property on the - <code>com.example.Duck</code> interface. Its value can be queried - and possibly changed on an existing Connection using methods on the - <code>org.freedesktop.DBus.Properties</code> interface.</p> - - <p>When a new value for a parameter with this flag is passed to - <tp:dbus-ref namespace="ofdT">Account.UpdateParameters</tp:dbus-ref>, - the account manager will attempt to update its value on any running - connections. Similarly, if the parameter also has the - <code>Has_Default</code> flag, and is passed in the second argument - to <code>UpdateParameters</code>, the default value will be applied - to any running - connections. Thus, clients generally do not need to directly access - or update the connection property; instead, they SHOULD manipulate - <tp:dbus-ref namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> - - <tp:rationale> - <p>This allows runtime-configurable options to be stored and - maintained by the <tp:dbus-ref - namespace='ofdT'>AccountManager</tp:dbus-ref>, without needing to - invent a separate account preference for “properties that should - be set on the connection as soon as it is created”. It was - originally invented to manage <tp:dbus-ref - namespace='ofdT.Connection.Interface'>Cellular</tp:dbus-ref> - preferences.</p> - </tp:rationale> - </tp:docstring> - <tp:added version="0.17.16"/> - </tp:flag> - </tp:flags> - - <method name="GetParameters" tp:name-for-bindings="Get_Parameters"> - <arg direction="in" name="Protocol" type="s" tp:type="Protocol"> - <tp:docstring> - The required protocol name - </tp:docstring> - </arg> - <arg direction="out" type="a(susv)" tp:type="Param_Spec[]" - name="Parameters"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs representing possible parameters. - </tp:docstring> - </arg> - <tp:docstring> - Get a list of the parameters which must or may be provided to the - <tp:member-ref>RequestConnection</tp:member-ref> method when connecting - to the given protocol, - or registering (the boolean "register" parameter is available, - and set to true). - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The requested protocol is not supported by this manager - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:mapping name="Protocol_Properties_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from protocol identifiers supported by a connection - manager to the immutable properties of the corresponding - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Protocol</tp:dbus-ref> objects.</p> - </tp:docstring> - - <tp:member name="Protocol" type="s" tp:type="Protocol"> - <tp:docstring>A protocol name</tp:docstring> - </tp:member> - - <tp:member name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring>The immutable properties of the corresponding - Protocol object</tp:docstring> - </tp:member> - </tp:mapping> - - <property name="Protocols" tp:name-for-bindings="Protocols" - access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from protocol identifiers supported by this connection - manager to the immutable properties of the corresponding - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Protocol</tp:dbus-ref> objects.</p> - - <tp:rationale> - <p>Providing the immutable properties here means that - when the API of Protocol objects has been finalized, - most clients will only need one D-Bus round trip to interrogate - the ConnectionManager about all its protocols.</p> - </tp:rationale> - - <p>If this map is empty or missing, clients SHOULD fall back to - calling <tp:member-ref>ListProtocols</tp:member-ref> and - <tp:member-ref>GetParameters</tp:member-ref>.</p> - </tp:docstring> - </property> - - <method name="ListProtocols" tp:name-for-bindings="List_Protocols"> - <arg direction="out" type="as" tp:type="Protocol[]" name="Protocols"> - <tp:docstring> - The keys of the <tp:member-ref>Protocols</tp:member-ref> map. - </tp:docstring> - </arg> - <tp:docstring> - Get a list of protocol identifiers that are implemented by this - connection manager. - </tp:docstring> - </method> - - <signal name="NewConnection" tp:name-for-bindings="New_Connection"> - <arg name="Bus_Name" type="s" tp:type="DBus_Bus_Name"> - <tp:docstring> - The D-Bus service where the connection object can be found - </tp:docstring> - </arg> - <arg name="Object_Path" type="o"> - <tp:docstring> - The object path of the Connection object on this service - </tp:docstring> - </arg> - <arg name="Protocol" type="s" tp:type="Protocol"> - <tp:docstring> - The identifier for the protocol this connection uses - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a new <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object - is created. - </tp:docstring> - </signal> - - <method name="RequestConnection" tp:name-for-bindings="Request_Connection"> - <arg direction="in" name="Protocol" type="s" tp:type="Protocol"> - <tp:docstring> - The protocol identifier - </tp:docstring> - </arg> - <arg direction="in" name="Parameters" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring> - A dictionary mapping parameter names to values of the appropriate - type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> - and the well-known list of names and value types documented on the - <tp:type>Connection_Parameter_Name</tp:type> type. - </tp:docstring> - </arg> - <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name"> - <tp:docstring> - A D-Bus service name where the new Connection object can be found - </tp:docstring> - </arg> - <arg direction="out" type="o" name="Object_Path"> - <tp:docstring> - The D-Bus object path to the Connection on this service - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request a - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> - object representing a given account on a given - protocol with the given parameters. The method returns the bus name - and the object path where the new Connection object can be found, - which should have the status of Connection_Status_Disconnected, to - allow signal handlers to be attached before connecting is started - with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref> - method.</p> - - <p>The parameters which must and may be provided in the parameters - dictionary can be discovered with the - <tp:member-ref>GetParameters</tp:member-ref> method. These - parameters, their types, and their default values may be cached - in files so that all available connection managers do not need to be - started to discover which protocols are available.</p> - - <p>To request values for these parameters from the user, a client must - have prior knowledge of the meaning of the parameter names, so the - well-known names and types defined by the - <tp:type>Connection_Parameter_Name</tp:type> type should be used where - appropriate.</p> - - <p>Connection manager authors SHOULD avoid introducing parameters - whose default values would not be serializable in a - <code>.manager</code> file.</p> - - <tp:rationale> - <p>The same serialization format is used in Mission Control - to store accounts.</p> - </tp:rationale> - - <p>Every successful RequestConnection call will cause the emission of a - <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly - created connection. The - requester can use the returned object path and service name - independently of the emission of that signal. In that case this signal - emission is most useful for, e.g. other processes that are monitoring - the creation of new connections.</p> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The requested protocol is not supported by this manager - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The requested connection already appears to exist - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - Unrecognised connection parameters - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:simple-type name="Connection_Parameter_Name" type="s"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Well-known connection parameter names, along with their expected - type. Where possible, connection managers should use names and types - from this list in the <tp:dbus-ref - namespace='ofdT.Protocol'>Parameters</tp:dbus-ref> that may be passed - to <tp:member-ref>RequestConnection</tp:member-ref>.</p> - - <dl> - <dt>account (s)</dt> - <dd>The identifier for the user's account on the server</dd> - - <dt>server (s)</dt> - <dd>A fully qualified domain name or numeric IPv4 or IPv6 address. - Using the fully-qualified domain name form is recommended whenever - possible. If this parameter is specified and the account for that - protocol also specifies a server, this parameter should override - that in the user id.</dd> - - <dt>port (q)</dt> - <dd>A TCP or UDP port number. If this parameter is specified and the - account for that protocol also specifies a port, this parameter - should override that in the account.</dd> - - <dt>password (s)</dt> - <dd>A password associated with the account.</dd> - - <dt>require-encryption (b)</dt> - <dd>Require encryption for this connection. A connection should fail - to connect if require-encryption is set and an encrypted connection - is not possible.</dd> - - <dt>register (b)</dt> - <dd>This account should be created on the server if it does not - already exist.</dd> - - <dt>ident (s)</dt> - <dd>The local username to report to the server if necessary, such as - in IRC.</dd> - - <dt>fullname (s)</dt> - <dd>The user's full name if the service requires this when - authenticating or registering.</dd> - - <dt>stun-server (s)</dt> - <dd>The IP address or FQDN of a STUN server to use for NAT traversal, - without any ":port" suffix.</dd> - - <dt>stun-port (q)</dt> - <dd>The UDP port number on the stun-server to use for STUN. Only - significant if the stun-server is also supplied.</dd> - - <dt>keepalive-interval (u)</dt> - <dd> - <p>The time in seconds between pings sent to the server to ensure - that the connection is still alive, or <tt>0</tt> to disable such - pings.</p> - - <p>This parameter is superseded by the <tp:dbus-ref - namespace='ofdT.Connection.Interface.Keepalive.DRAFT'>KeepaliveInterval</tp:dbus-ref> - property, which can be updated on an already-established - connection as well as being specified when requesting the - connection. Clients SHOULD provide that parameter instead, if - allowed; new connection managers SHOULD implement it in - preference to this one.</p> - </dd> - </dl> - - <p>The following well-known parameter names correspond to D-Bus - properties, and thus their <tp:type>Conn_Mgr_Param_Flags</tp:type> - should include DBus_Property. See that flag for more details on this - kind of parameter.</p> - - <tp:list-dbus-property-parameters/> - </tp:docstring> - </tp:simple-type> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of the extra interfaces provided by this connection manager - (i.e. extra functionality that can be provided even before a - connection has been created).</p> - - <p>No interfaces suitable for listing in this property are currently - defined; it's provided as a hook for possible future - functionality.</p> - - <p>To be compatible with older connection managers, if retrieving - this property fails, clients SHOULD assume that its value is - an empty list.</p> - - <p>Connection managers with a non-empty list of Interfaces MUST - represent them in the <code>.manager</code> file, if they have one, - as an <code>Interfaces</code> key in the - group headed <code>[ConnectionManager]</code>, whose value is a list - of strings each followed by a semicolon.</p> - </tp:docstring> - <tp:added version="0.17.8"/> - </property> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A D-Bus service which allows connections to be created. The manager - processes are intended to be started by D-Bus service activation.</p> - - <p>For service discovery, each Telepathy connection manager must have - a <em>connection manager name</em> (see - <tp:type>Connection_Manager_Name</tp:type> for syntax).</p> - - <p>The connection manager must then provide a well-known bus name of - <code>org.freedesktop.Telepathy.ConnectionManager.<em>cmname</em></code> - where <em>cmname</em> is its connection manager name. If it makes sense - to start the connection manager using D-Bus service activation, it - must register that well-known name for service activation by installing - a .service file.</p> - - <p>Clients can list the running connection managers by calling the - ListNames method on the D-Bus daemon's org.freedesktop.DBus interface - and looking for names matching the above pattern; they can list the - activatable connection managers by calling ListActivatableNames, and - they should usually combine the two lists to get a complete list of - running or activatable connection managers.</p> - - <p>When the connection manager is running, it must have an object - implementing the ConnectionManager interface at the object path - <code>/org/freedesktop/Telepathy/ConnectionManager/<em>cmname</em></code>. - </p> - - <p>Connection managers' capabilities can be determined dynamically by - calling their <tp:member-ref>ListProtocols</tp:member-ref> method, then - for each protocol of interest, calling - <tp:member-ref>GetParameters</tp:member-ref> to discover the required and - optional parameters. - However, since it is inefficient to activate all possible connection - managers on the system just to find out what they can do, there - is a standard mechanism to store static information about CMs in - ".manager files".</p> - - <p>To look up a connection manager's supported protocols, clients - should search the data directories specified by - <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">the - freedesktop.org XDG Base Directory Specification</a> ($XDG_DATA_HOME, - defaulting to $HOME/.local/share if unset, followed by - colon-separated paths from $XDG_DATA_DIRS, defaulting to - /usr/local/share:/usr/share if unset) for the first file named - <code>telepathy/managers/<em>cmname</em>.manager</code> that can be - read without error. This file has the same syntax as a - <a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p> - - <p>Clients must still support connection managers for which no - <code>.manager</code> file can be found, which they can do by activating - the connection manager and calling its methods; the - <code>.manager</code> file is merely an optimization. Connection managers - whose list of protocols can change at any time (for instance, via - a plugin architecture) should not install a <code>.manager</code> - file.</p> - - <p>The <code>.manager</code> file SHOULD have a group headed - <code>[ConnectionManager]</code>, containing a key - <code>Interfaces</code> representing - <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings - each followed by a semicolon (the "localestrings" type from the Desktop - Entry Specification).</p> - - <p>The <code>[ConnectionManager]</code> group SHOULD NOT contain keys - <code>ObjectPath</code> or <code>BusName</code>. If it does, they MUST - be ignored.</p> - - <tp:rationale> - <p>The object path and bus name are derivable from the connection - manager's name, which is part of the filename, so these keys are - redundant. They were required in very old versions of Telepathy.</p> - </tp:rationale> - - <p>For each protocol name <em>proto</em> that would be returned by - ListProtocols, the .manager file contains a group - headed <code>[Protocol <em>proto</em>]</code>. For each parameter - <em>p</em> that would be returned by GetParameters(<em>proto</em>), the - .manager file contains a key <code>param-<em>p</em></code> with a value - consisting of a D-Bus signature (a single complete type), optionally - followed by a space and a space-separated list of flags. The supported - flags are:</p> - - <ul> - <li><code>required</code>, corresponding to - Conn_Mgr_Param_Flag_Required</li> - <li><code>register</code>, corresponding - to Conn_Mgr_Param_Flag_Register</li> - <li><code>secret</code>, corresponding - to Conn_Mgr_Param_Flag_Secret</li> - <li><code>dbus-property</code>, corresponding - to Conn_Mgr_Param_Flag_DBus_Property</li> - </ul> - - <p>The group may also contain a key <code>default-<em>p</em></code> - whose value is a string form of the default value for the parameter. - If this key exists, it sets the default, and also sets the flag - Conn_Mgr_Param_Flag_Has_Default. The default value is formatted - according to the D-Bus signature as follows:</p> - - <dl> - <dt>s (string)</dt> - <dd>The UTF-8 string, with the standard backslash escape - sequences supported by the Desktop Entry Specification - (the "localestring" type from the Desktop Entry Specification)</dd> - <dt>o (object path)</dt> - <dd>The object path as an ASCII string</dd> - <dt>b (boolean)</dt> - <dd>"true" (case-insensitively) or "1" means True, "false" - (case-insensitively) or "0" means False; when writing a file, - "true" and "false" SHOULD be used</dd> - <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt> - <dd>ASCII decimal integer</dd> - <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt> - <dd>ASCII decimal integer, optionally prefixed with "-"</dd> - <dt>d (double-precision floating point)</dt> - <dd>ASCII decimal number</dd> - <dt>as (array of string)</dt> - <dd>A sequence of UTF-8 strings each followed by a semicolon, with - any semicolons they contain escaped with a backslash - (the "localestrings" type from the Desktop Entry Specification)</dd> - </dl> - - <p>Currently, no other D-Bus signatures are allowed to have default values, - but clients parsing the .manager file MUST ignore defaults - that they cannot parse, and treat them as if the - <code>default-<em>p</em></code> key was not present at all.</p> - - <p>It is not required that a connection manager be able to support multiple - protocols, or even multiple connections. When a connection is made, a - service name where the connection object can be found is returned. A - manager which can only make one connection may then remove itself from its - well-known bus name, causing a new connection manager to be activated when - somebody attempts to make a new connection.</p> - </tp:docstring> - - <tp:changed version="0.17.2">Prior to version 0.17.2, support for - CMs with no .manager file was not explicitly required.</tp:changed> - <tp:changed version="0.17.16">Prior to version 0.17.16 the serialization - of string arrays (signature 'as') was not defined</tp:changed> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Manager_Interface_Account_Storage.xml b/qt4/spec/Connection_Manager_Interface_Account_Storage.xml deleted file mode 100644 index 2f4f4bf78..000000000 --- a/qt4/spec/Connection_Manager_Interface_Account_Storage.xml +++ /dev/null @@ -1,120 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Manager_Interface_Account_Storage" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2011 Collabora Ltd.</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.ConnectionManager.Interface.AccountStorage.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.10">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.ConnectionManager"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for connection managers that store account details - internally. At the moment this consists only of storing an account's - credentials, but other functionality may be added in the future.</p> - - <p><tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> objects - representing accounts on a connection manager that implements this - interface should implement the - <tp:dbus-ref namespace="ofdT.Account.Interface">ExternalPasswordStorage.DRAFT</tp:dbus-ref> - interface.</p> - </tp:docstring> - - <tp:flags name="Account_Flags" value-prefix="Account_Flag" type="u"> - <tp:docstring> - A set of flags representing the status of the Account stored in the - Connection Manager. - </tp:docstring> - - <tp:flag suffix="Credentials_Stored" value="1"> - <tp:docstring> - The associated account has its authentication credentials (password) - stored in the connection manager - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:mapping name="Account_Flags_Map" array-name="Account_Flags_Map_List"> - <tp:docstring>A mapping from Account_Ids to account flags. - </tp:docstring> - <tp:member type="s" name="Account_Id"/> - <tp:member type="u" tp:type="Account_Flags" name="Flags"/> - </tp:mapping> - - <property name="Accounts" - tp:name-for-bindings="Accounts" - type="a{su}" tp:type="Account_Flags_Map" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The set of Accounts stored in this Connection Manager, and flags - indicating their status.</p> - - <p>Change notification for this property is provided by the standard - D-Bus <code>PropertiesChanged</code> signal.</p> - </tp:docstring> - </property> - - <method name="ForgetCredentials" tp:name-for-bindings="Forget_Credentials"> - <tp:docstring> - Clears any saved credentials associated with the specified Account_Id. - Any other saved data related to the account will be unaffected. - </tp:docstring> - - <arg direction="in" name="Account_Id" - type="s"> - <tp:docstring> - An account id as returned from - <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The account id is invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="RemoveAccount" tp:name-for-bindings="Remove_Account"> - <tp:docstring> - Completely removes all data associated with an account from the - connection manager's internal storage. - </tp:docstring> - - <arg direction="in" name="Account_Id" - type="s"> - <tp:docstring> - An account id as returned from - <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The account id is invalid. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> diff --git a/qt4/spec/Debug.xml b/qt4/spec/Debug.xml deleted file mode 100644 index 70a82e903..000000000 --- a/qt4/spec/Debug.xml +++ /dev/null @@ -1,165 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Debug" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2009 Collabora Ltd.</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.Debug"> - <tp:added version="0.17.27">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for providing debug messages.</p> - - <p>This interface is primarily provided by one object per - service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.</p> - </tp:docstring> - - <property name="Enabled" type="b" access="readwrite" - tp:name-for-bindings="Enabled"> - <tp:docstring> - TRUE if the <tp:member-ref>NewDebugMessage</tp:member-ref> signal - should be emitted when a new debug message is generated. - </tp:docstring> - </property> - - <method name="GetMessages" tp:name-for-bindings="Get_Messages"> - <tp:docstring> - Retrieve buffered debug messages. An implementation could have a - limit on how many message it keeps and so the array returned from - this method should not be assumed to be all of the messages in - the lifetime of the service. - </tp:docstring> - - <arg direction="out" name="Messages" type="a(dsus)" - tp:type="Debug_Message[]"> - <tp:docstring> - A list of debug messages. - </tp:docstring> - </arg> - </method> - - <signal name="NewDebugMessage" tp:name-for-bindings="New_Debug_Message"> - <tp:docstring> - Emitted when a debug messages is generated if the - <tp:member-ref>Enabled</tp:member-ref> property is set to TRUE. - </tp:docstring> - - <arg name="time" type="d"> - <tp:docstring> - Timestamp of the debug message. - </tp:docstring> - </arg> - <arg name="domain" type="s"> - <tp:docstring> - Domain of the debug message, as described in the Debug_Message struct. - </tp:docstring> - </arg> - <arg name="level" type="u" tp:type="Debug_Level"> - <tp:docstring> - Level of the debug message. - </tp:docstring> - </arg> - <arg name="message" type="s"> - <tp:docstring> - The text of the debug message. - </tp:docstring> - </arg> - </signal> - - <tp:enum name="Debug_Level" type="u"> - <tp:enumvalue suffix="Error" value="0"> - <tp:docstring> - Log level for errors. Error messages are always fatal, resulting - in the service terminating after something completely - unexpected occurred. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Critical" value="1"> - <tp:docstring> - Log level for critical messages. Critical messages are messages - that the service might predict and it is up to the service itself - to decide whether to terminate following a critical message. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Warning" value="2"> - <tp:docstring> - Log level for warnings. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Message" value="3"> - <tp:docstring> - Log level for messages. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Info" value="4"> - <tp:docstring> - Log level for information messages. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Debug" value="5"> - <tp:docstring> - Log level for debug messages. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Debug_Message" array-name="Debug_Message_List"> - <tp:docstring> - A struct representing a debug message, as returned by - <tp:member-ref>GetMessages</tp:member-ref>. - </tp:docstring> - - <tp:member type="d" name="Timestamp"> - <tp:docstring> - Timestamp of the debug message. This is a double to allow - more accuracy in the time the message was logged. - </tp:docstring> - </tp:member> - - <tp:member type="s" name="Domain"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Domain of the debug message. This is used to identify - the source of debug messages. For example, debug messages - from a connection manager could have this Domain struct - member be the name of the connection manager, and logs - from any helper library could have the name of the helper - library.</p> - - <p>The domain could also contain a category as to where - the log message originated separated by a forward-slash. - For example, if a debug message was output in a connection - manager called "dummy", in the file-transfer code, this - Domain struct member might be <tt>dummy/file-transfer</tt>.</p> - </tp:docstring> - </tp:member> - - <tp:member type="u" tp:type="Debug_Level" name="Level"> - <tp:docstring> - Level of the debug message. This states the severity of the - debug message. - </tp:docstring> - </tp:member> - - <tp:member type="s" name="Message"> - <tp:docstring> - The text of the debug message. - </tp:docstring> - </tp:member> - </tp:struct> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Media_Session_Handler.xml b/qt4/spec/Media_Session_Handler.xml deleted file mode 100644 index 70aa75073..000000000 --- a/qt4/spec/Media_Session_Handler.xml +++ /dev/null @@ -1,81 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Media_Session_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Media.SessionHandler"> - <method name="Error" tp:name-for-bindings="Error"> - <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> - 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 <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> - 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"> - <tp:docstring> - The unique ID of the new stream - </tp:docstring> - </arg> - <arg name="Media_Type" type="u" tp:type="Media_Stream_Type"> - <tp:docstring> - Type of media that this stream should handle - </tp:docstring> - </arg> - <arg name="Direction" type="u" tp:type="Media_Stream_Direction"> - <tp:docstring> - Direction of this stream - </tp:docstring> - </arg> - <tp:docstring> - Emitted when a new stream handler has been created for this - session. - </tp:docstring> - </signal> - <method name="Ready" tp:name-for-bindings="Ready"> - <tp:docstring> - Inform the connection manager that a client is ready to handle - this session handler (i.e. that it has connected to the - <tp:member-ref>NewStreamHandler</tp:member-ref> signal and done any - other necessary setup). - </tp:docstring> - </method> - <tp:docstring> - An media session handler is an object that handles a number of synchronised - media streams. - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Media_Stream_Handler.xml b/qt4/spec/Media_Stream_Handler.xml deleted file mode 100644 index 123ea8be7..000000000 --- a/qt4/spec/Media_Stream_Handler.xml +++ /dev/null @@ -1,725 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Media_Stream_Handler" 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: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.Media.StreamHandler"> - - <tp:struct name="Media_Stream_Handler_Candidate" - array-name="Media_Stream_Handler_Candidate_List"> - <tp:member type="s" name="Name"/> - <tp:member type="a(usuussduss)" name="Transports" - tp:type="Media_Stream_Handler_Transport[]"/> - </tp:struct> - - <tp:struct name="Media_Stream_Handler_Transport" - array-name="Media_Stream_Handler_Transport_List"> - <tp:member type="u" name="Component_Number"/> - <tp:member type="s" name="IP_Address"/> - <tp:member type="u" name="Port"/> - <tp:member type="u" tp:type="Media_Stream_Base_Proto" name="Protocol"/> - <tp:member type="s" name="Subtype"/> - <tp:member type="s" name="Profile"/> - <tp:member type="d" name="Preference_Value"/> - <tp:member type="u" tp:type="Media_Stream_Transport_Type" - name="Transport_Type"/> - <tp:member type="s" name="Username"/> - <tp:member type="s" name="Password"/> - </tp:struct> - - <tp:struct name="Media_Stream_Handler_Codec" - array-name="Media_Stream_Handler_Codec_List"> - <tp:docstring> - Information about a codec supported by a client or a peer's client. - </tp:docstring> - - <tp:member type="u" name="Codec_ID"> - <tp:docstring> - The codec's payload identifier, as per RFC 3551 (static or dynamic) - </tp:docstring> - </tp:member> - <tp:member type="s" name="Name"> - <tp:docstring>The codec's name</tp:docstring> - </tp:member> - <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type"> - <tp:docstring>Type of stream this codec supports</tp:docstring> - </tp:member> - <tp:member type="u" name="Clock_Rate"> - <tp:docstring>Sampling frequency in Hertz</tp:docstring> - </tp:member> - <tp:member type="u" name="Number_Of_Channels"> - <tp:docstring>Number of supported channels</tp:docstring> - </tp:member> - <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map"> - <tp:docstring>Codec-specific optional parameters</tp:docstring> - </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"> - <tp:docstring> - String identifier for this candidate - </tp:docstring> - </arg> - <arg name="Transports" type="a(usuussduss)" - tp:type="Media_Stream_Handler_Transport[]"> - <tp:docstring> - Array of transports for this candidate with fields, - as defined in NewNativeCandidate - </tp:docstring> - </arg> - <tp:docstring> - Signal emitted when the connection manager wishes to inform the - client of a new remote candidate. - </tp:docstring> - </signal> - <signal name="Close" tp:name-for-bindings="Close"> - <tp:docstring> - Signal emitted when the connection manager wishes the stream to be - closed. - </tp:docstring> - </signal> - <method name="CodecChoice" tp:name-for-bindings="Codec_Choice"> - <arg direction="in" name="Codec_ID" type="u"/> - <tp:docstring> - Inform the connection manager of codec used to receive data. - </tp:docstring> - </method> - <method name="Error" tp:name-for-bindings="Error"> - <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error"> - <tp:docstring> - ID of error, from the MediaStreamError enumeration - </tp:docstring> - </arg> - <arg direction="in" name="Message" type="s"> - <tp:docstring> - String describing the error - </tp:docstring> - </arg> - <tp:docstring> - Inform the connection manager that an error occured in this stream. The - connection manager should emit the StreamError signal for the stream on - the relevant channel, and remove the stream from the session. - </tp:docstring> - </method> - <tp:enum name="Media_Stream_Error" type="u"> - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring> - An unknown error occured. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="EOS" value="1"> - <tp:docstring> - The end of the stream was reached. - </tp:docstring> - <tp:deprecated version="0.17.27"> - This error has no use anywhere. In Farsight 1 times, it was used to - indicate a GStreamer EOS (when the end of a file is reached). But - since this is for live calls, it makes no sense. - </tp:deprecated> - </tp:enumvalue> - <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2"> - <tp:added version="0.17.27"/> - <tp:docstring> - There are no common codecs between the local side - and the other particpants in the call. The possible codecs are not - signalled here: the streaming implementation is assumed to report - them in an implementation-dependent way, e.g. Farsight should use - GstMissingElement. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Connection_Failed" value="3"> - <tp:added version="0.17.27"/> - <tp:docstring> - A network connection for the Media could not be established or was - lost. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Network_Error" value="4"> - <tp:added version="0.17.27"/> - <tp:docstring> - There was an error in the networking stack - (other than the connection failure). - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="No_Codecs" value="5"> - <tp:added version="0.17.27"/> - <tp:docstring> - There are no installed codecs for this media type. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Invalid_CM_Behavior" value="6"> - <tp:added version="0.17.27"/> - <tp:docstring> - The CM is doing something wrong. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Media_Error" value="7"> - <tp:added version="0.17.27"/> - <tp:docstring> - There was an error in the media processing stack. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - <method name="NativeCandidatesPrepared" - tp:name-for-bindings="Native_Candidates_Prepared"> - <tp:docstring> - Informs the connection manager that all possible native candisates - have been discovered for the moment. - </tp:docstring> - </method> - <method name="NewActiveCandidatePair" - tp:name-for-bindings="New_Active_Candidate_Pair"> - <arg direction="in" name="Native_Candidate_ID" type="s"/> - <arg direction="in" name="Remote_Candidate_ID" type="s"/> - <tp:docstring> - Informs the connection manager that a valid candidate pair - has been discovered and streaming is in progress. - </tp:docstring> - </method> - <method name="NewActiveTransportPair" - tp:name-for-bindings="New_Active_Transport_Pair"> - <arg direction="in" name="Native_Candidate_ID" type="s"/> - <arg direction="in" name="Native_Transport" type="(usuussduss)" - tp:type="Media_Stream_Handler_Transport"/> - <arg direction="in" name="Remote_Candidate_ID" type="s"/> - <arg direction="in" name="Remote_Transport" type="(usuussduss)" - tp:type="Media_Stream_Handler_Transport"/> - <tp:docstring> - <p>Informs the connection manager that a valid transport pair - has been discovered and streaming is in progress. Component - id MUST be the same for both transports and the pair is - only valid for that component.</p> - - <tp:rationale> - <p>The connection manager might need to send the details of - the active transport pair (e.g. c and o parameters of SDP - body need to contain address of selected native RTP transport - as stipulated by RFC 5245). However, the candidate ID might - not be enough to determine these info if the transport was - found after <tp:member-ref>NativeCandidatesPrepared</tp:member-ref> - has been called (e.g. peer reflexive ICE candidate). </p> - </tp:rationale> - - <p>This method must be called before - <tp:member-ref>NewActiveCandidatePair</tp:member-ref>.</p> - - <tp:rationale> - <p>This way, connection managers supporting this method can - safely ignore subsequent - <tp:member-ref>NewActiveCandidatePair</tp:member-ref> call.</p> - </tp:rationale> - - <p>Connection managers SHOULD NOT implement this method unless - they need to inform the peer about selected transports. As a - result, streaming implementations MUST NOT treat errors raised - by this method as fatal.</p> - - <tp:rationale> - <p>Usually, connection managers only need to do one answer/offer - round-trip. However, some protocols give the possibility to - to send an updated offer (e.g. ICE defines such mechanism to - avoid some race conditions and to properly set the state of - gateway devices).</p> - </tp:rationale> - </tp:docstring> - </method> - <tp:enum name="Media_Stream_Base_Proto" type="u"> - <tp:enumvalue suffix="UDP" value="0"> - <tp:docstring>UDP (User Datagram Protocol)</tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="TCP" value="1"> - <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring> - </tp:enumvalue> - </tp:enum> - <method name="NewNativeCandidate" - tp:name-for-bindings="New_Native_Candidate"> - <arg direction="in" name="Candidate_ID" type="s"> - <tp:docstring> - String identifier for this candidate - </tp:docstring> - </arg> - <arg direction="in" name="Transports" type="a(usuussduss)" - tp:type="Media_Stream_Handler_Transport[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Array of transports for this candidate, with fields: - <ul> - <li>component number</li> - <li>IP address (as a string)</li> - <li>port</li> - <li>base network protocol (one of the values of MediaStreamBaseProto)</li> - <li>proto subtype (e.g. RTP)</li> - <li>proto profile (e.g. AVP)</li> - <li>our preference value of this transport (double in range 0.0-1.0 - inclusive); 1 signals the most preferred transport</li> - <li>transport type, one of the values of MediaStreamTransportType</li> - <li>username if authentication is required</li> - <li>password if authentication is required</li> - </ul> - </tp:docstring> - </arg> - <tp:docstring> - Inform this MediaStreamHandler that a new native transport candidate - has been ascertained. - </tp:docstring> - </method> - <tp:enum name="Media_Stream_Transport_Type" type="u"> - <tp:enumvalue suffix="Local" value="0"> - <tp:docstring> - A local address - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Derived" value="1"> - <tp:docstring> - An external address derived by a method such as STUN - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Relay" value="2"> - <tp:docstring> - An external stream relay - </tp:docstring> - </tp:enumvalue> - </tp:enum> - <method name="Ready" tp:name-for-bindings="Ready"> - <arg direction="in" name="Codecs" type="a(usuuua{ss})" - tp:type="Media_Stream_Handler_Codec[]"> - <tp:docstring> - Locally-supported codecs. - </tp:docstring> - </arg> - <tp:docstring> - Inform the connection manager that a client is ready to handle - this StreamHandler. Also provide it with info about all supported - codecs. - </tp:docstring> - </method> - <method name="SetLocalCodecs" tp:name-for-bindings="Set_Local_Codecs"> - <arg name="Codecs" type="a(usuuua{ss})" direction="in" - tp:type="Media_Stream_Handler_Codec[]"> - <tp:docstring> - Locally-supported codecs - </tp:docstring> - </arg> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Used to provide codecs after Ready(), so the media client can go - ready for an incoming call and exchange candidates/codecs before - knowing what local codecs are available.</p> - - <p>This is useful for gatewaying calls between two connection managers. - Given an incoming call, you need to call - <tp:member-ref>Ready</tp:member-ref> to get the remote codecs before - you can use them as the "local" codecs to place the outgoing call, - and hence receive the outgoing call's remote codecs to use as the - incoming call's "local" codecs.</p> - - <p>In this situation, you would pass an empty list of codecs to the - incoming call's Ready method, then later call SetLocalCodecs on the - incoming call in order to respond to the offer.</p> - </tp:docstring> - </method> - <signal name="RemoveRemoteCandidate" - tp:name-for-bindings="Remove_Remote_Candidate"> - <arg name="Candidate_ID" type="s"> - <tp:docstring> - String identifier for remote candidate to drop - </tp:docstring> - </arg> - <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>). - </tp:deprecated> - <tp:docstring> - Signal emitted when the connection manager wishes to inform the - client that the remote end has removed a previously usable - candidate. - - <tp:rationale> - It seemed like a good idea at the time, but wasn't. - </tp:rationale> - </tp:docstring> - </signal> - <signal name="SetActiveCandidatePair" - tp:name-for-bindings="Set_Active_Candidate_Pair"> - <arg name="Native_Candidate_ID" type="s"/> - <arg name="Remote_Candidate_ID" type="s"/> - <tp:docstring> - Emitted by the connection manager to inform the client that a - valid candidate pair has been discovered by the remote end - and streaming is in progress. - </tp:docstring> - </signal> - <signal name="SetRemoteCandidateList" - tp:name-for-bindings="Set_Remote_Candidate_List"> - <arg name="Remote_Candidates" type="a(sa(usuussduss))" - tp:type="Media_Stream_Handler_Candidate[]"> - <tp:docstring> - A list of candidate id and a list of transports - as defined in NewNativeCandidate - </tp:docstring> - </arg> - <tp:docstring> - Signal emitted when the connection manager wishes to inform the - client of all the available remote candidates at once. - </tp:docstring> - </signal> - <signal name="SetRemoteCodecs" tp:name-for-bindings="Set_Remote_Codecs"> - <arg name="Codecs" type="a(usuuua{ss})" - tp:type="Media_Stream_Handler_Codec[]"> - <tp:docstring> - Codecs supported by the remote peer. - </tp:docstring> - </arg> - <tp:docstring> - Signal emitted when the connection manager wishes to inform the - client of the codecs supported by the remote end. - If these codecs are compatible with the remote codecs, then the client - must call <tp:member-ref>SupportedCodecs</tp:member-ref>, - otherwise call <tp:member-ref>Error</tp:member-ref>. - </tp:docstring> - </signal> - <signal name="SetStreamPlaying" tp:name-for-bindings="Set_Stream_Playing"> - <arg name="Playing" type="b"/> - <tp:docstring> - If emitted with argument TRUE, this means that the connection manager - wishes to set the stream playing; this means that the streaming - implementation should expect to receive data. If emitted with argument - FALSE this signal is basically meaningless and should be ignored. - - <tp:rationale> - We're very sorry. - </tp:rationale> - </tp:docstring> - </signal> - <signal name="SetStreamSending" tp:name-for-bindings="Set_Stream_Sending"> - <arg name="Sending" type="b"/> - <tp:docstring> - Signal emitted when the connection manager wishes to set whether or not - the stream sends to the remote end. - </tp:docstring> - </signal> - <signal name="StartTelephonyEvent" - tp:name-for-bindings="Start_Telephony_Event"> - <arg name="Event" type="y" tp:type="DTMF_Event"> - <tp:docstring> - A telephony event code. - </tp:docstring> - </arg> - <tp:docstring> - Request that a telephony event (as defined by RFC 4733) is transmitted - over this stream until StopTelephonyEvent is called. - </tp:docstring> - </signal> - <signal name="StartNamedTelephonyEvent" - tp:name-for-bindings="Start_Named_Telephony_Event"> - <tp:added version="0.21.2"/> - <arg name="Event" type="y" tp:type="DTMF_Event"> - <tp:docstring> - A telephony event code as defined by RFC 4733. - </tp:docstring> - </arg> - <arg name="Codec_ID" type="u"> - <tp:docstring> - The payload type to use when sending events. The value 0xFFFFFFFF - means to send with the already configured event type instead of using - the specified one. - </tp:docstring> - </arg> - <tp:docstring> - Request that a telephony event (as defined by RFC 4733) is transmitted - over this stream until StopTelephonyEvent is called. This differs from - StartTelephonyEvent in that you force the event to be transmitted - as a RFC 4733 named event, not as sound. You can also force a specific - Codec ID. - </tp:docstring> - </signal> - <signal name="StartSoundTelephonyEvent" - tp:name-for-bindings="Start_Sound_Telephony_Event"> - <tp:added version="0.21.2"/> - <arg name="Event" type="y" tp:type="DTMF_Event"> - <tp:docstring> - A telephony event code as defined by RFC 4733. - </tp:docstring> - </arg> - <tp:docstring> - Request that a telephony event (as defined by RFC 4733) is transmitted - over this stream until StopTelephonyEvent is called. This differs from - StartTelephonyEvent in that you force the event to be transmitted - as sound instead of as a named event. - </tp:docstring> - </signal> - <signal name="StopTelephonyEvent" - tp:name-for-bindings="Stop_Telephony_Event"> - <tp:docstring> - Request that any ongoing telephony events (as defined by RFC 4733) - being transmitted over this stream are stopped. - </tp:docstring> - </signal> - <method name="StreamState" tp:name-for-bindings="Stream_State"> - <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"/> - <tp:docstring> - Informs the connection manager of the stream's current state, as - as specified in Channel.Type.StreamedMedia::ListStreams. - </tp:docstring> - </method> - - <method name="SupportedCodecs" tp:name-for-bindings="Supported_Codecs"> - <arg direction="in" name="Codecs" type="a(usuuua{ss})" - tp:type="Media_Stream_Handler_Codec[]"> - <tp:docstring> - Locally supported codecs. - </tp:docstring> - </arg> - <tp:docstring> - Inform the connection manager of the supported codecs for this session. - This is called after the connection manager has emitted SetRemoteCodecs - to notify what codecs are supported by the peer, and will thus be an - intersection of all locally supported codecs (passed to Ready) - and those supported by the peer. - </tp:docstring> - </method> - - <method name="CodecsUpdated" tp:name-for-bindings="Codecs_Updated"> - <arg direction="in" name="Codecs" type="a(usuuua{ss})" - tp:type="Media_Stream_Handler_Codec[]"> - <tp:docstring> - Locally supported codecs, which SHOULD be the same as were previously - in effect, but possibly with different parameters. - </tp:docstring> - </arg> - <tp:docstring> - Inform the connection manager that the parameters of the supported - codecs for this session have changed. The connection manager should - send the new parameters to the remote contact. - - <tp:rationale> - This is required for H.264 and Theora, for example. - </tp:rationale> - </tp:docstring> - </method> - - <signal name="SetStreamHeld" tp:name-for-bindings="Set_Stream_Held"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the connection manager wishes to place the stream on - hold (so the streaming client should free hardware or software - resources) or take the stream off hold (so the streaming client - should reacquire the necessary resources).</p> - - <p>When placing a channel's streams on hold, the connection manager - SHOULD notify the remote contact that this will be done (if - appropriate in the protocol) before it emits this signal.</p> - - <tp:rationale> - <p>It is assumed that relinquishing a resource will not fail. - If it does, the call is probably doomed anyway.</p> - </tp:rationale> - - <p>When unholding a channel's streams, the connection manager - SHOULD emit this signal and wait for success to be indicated - via HoldState before it notifies the remote contact that the - channel has been taken off hold.</p> - - <tp:rationale> - <p>This means that if a resource is unavailable, the remote - contact will never even be told that we tried to acquire it.</p> - </tp:rationale> - </tp:docstring> - <tp:added version="0.17.3"/> - - <arg name="Held" type="b"> - <tp:docstring> - If true, the stream is to be placed on hold. - </tp:docstring> - </arg> - </signal> - - <method name="HoldState" tp:name-for-bindings="Hold_State"> - <tp:docstring> - Notify the connection manager that the stream's hold state has - been changed successfully in response to SetStreamHeld. - </tp:docstring> - <tp:added version="0.17.3"/> - <arg direction="in" name="Held" type="b"> - <tp:docstring> - If true, the stream is now on hold. - </tp:docstring> - </arg> - </method> - - <method name="UnholdFailure" tp:name-for-bindings="Unhold_Failure"> - <tp:docstring> - Notify the connection manager that an attempt to reacquire the - necessary hardware or software resources to unhold the stream, - in response to SetStreamHeld, has failed. - </tp:docstring> - <tp:added version="0.17.3"/> - </method> - - <tp:docstring> - Handles signalling the information pertaining to a specific media stream. - A client should provide information to this handler as and when it is - available. - </tp:docstring> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Properties_Interface.xml b/qt4/spec/Properties_Interface.xml deleted file mode 100644 index bc9c8b260..000000000 --- a/qt4/spec/Properties_Interface.xml +++ /dev/null @@ -1,194 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Properties_Interface" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005-2007 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> - <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -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.Properties"> - - <tp:struct name="Property_Spec" array-name="Property_Spec_List"> - <tp:docstring>A struct (property ID, property name, D-Bus signature, - flags) representing a property, as returned by ListProperties on the - Properties interface.</tp:docstring> - <tp:member type="u" name="Property_ID"/> - <tp:member type="s" name="Name"/> - <tp:member type="s" tp:type="DBus_Signature" name="Signature"/> - <tp:member type="u" tp:type="Property_Flags" name="Flags"/> - </tp:struct> - - <tp:struct name="Property_Flags_Change" - array-name="Property_Flags_Change_List"> - <tp:docstring>A struct (property ID, flags) representing a change to - a property's flags, as seen in the PropertyFlagsChanged signal on - the Properties interface.</tp:docstring> - <tp:member type="u" name="Property_ID"/> - <tp:member type="u" name="New_Flags"/> - </tp:struct> - - <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> - </tp:simple-type> - - <tp:struct name="Property_Value" array-name="Property_Value_List"> - <tp:docstring>A struct (property ID, value) representing a - property's value, as seen in the PropertiesChanged signal on - the Properties interface, returned by the GetProperties method - and passed to the SetProperties method.</tp:docstring> - <tp:member type="u" tp:type="Property_ID" name="Identifier"/> - <tp:member type="v" name="Value"/> - </tp:struct> - - <method name="GetProperties" tp:name-for-bindings="Get_Properties"> - <tp:docstring> - Returns an array of (identifier, value) pairs containing the current - values of the given properties. - </tp:docstring> - <arg direction="in" name="Properties" type="au" tp:type="Property_ID[]"> - <tp:docstring>An array of property identifiers</tp:docstring> - </arg> - <arg direction="out" type="a(uv)" tp:type="Property_Value[]" - name="Values"> - <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of structs containing:</p> - <ul> - <li>integer identifiers</li> - <li>variant boxed values</li> - </ul> - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - Some property identifier requested is invalid - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> - <tp:docstring> - Some property requested does not have the PROPERTY_FLAG_READ flag - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - <method name="ListProperties" tp:name-for-bindings="List_Properties"> - <tp:docstring> - Returns a dictionary of the properties available on this channel. - </tp:docstring> - <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]" - name="Available_Properties"> - <!-- XXX: if we're ever breaking API compatibility, make this - a{u(ssu)} ? --> - <tp:docstring> - An array of structs containing: - <ul> - <li>an integer identifier</li> - <li>a string property name</li> - <li>a string representing the D-Bus signature of this property</li> - <li>a bitwise OR of the flags applicable to this property</li> - </ul> - </tp:docstring> - </arg> - </method> - <signal name="PropertiesChanged" tp:name-for-bindings="Properties_Changed"> - <tp:docstring> - Emitted when the value of readable properties has changed. - </tp:docstring> - <arg name="Properties" type="a(uv)" tp:type="Property_Value[]"> - <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of structs containing:</p> - <ul> - <li>integer identifiers</li> - <li>variant boxed values</li> - </ul> - <p>The array should contain only properties whose values have - actually changed.</p> - </tp:docstring> - </arg> - </signal> - <signal name="PropertyFlagsChanged" - tp:name-for-bindings="Property_Flags_Changed"> - <tp:docstring> - Emitted when the flags of some room properties have changed. - </tp:docstring> - <arg name="Properties" type="a(uu)" tp:type="Property_Flags_Change[]"> - <!-- XXX: if we're ever breaking API compatibility, make this a{uu} --> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of structs containing:</p> - <ul> - <li>integer identifiers</li> - <li>a bitwise OR of the current flags</li> - </ul> - <p>The array should contain only properties whose flags have actually - changed.</p> - </tp:docstring> - </arg> - </signal> - <method name="SetProperties" tp:name-for-bindings="Set_Properties"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Takes an array of (identifier, value) pairs containing desired - values to set the given properties. In the case of any errors, no - properties will be changed. When the changes have been acknowledged - by the server, the PropertiesChanged signal will be emitted.</p> - - <p>All properties given must have the PROPERTY_FLAG_WRITE flag, or - PermissionDenied will be returned. If any variants are of the wrong - type, NotAvailable will be returned. If any given property identifiers - are invalid, InvalidArgument will be returned.</p> - </tp:docstring> - - <arg direction="in" name="Properties" type="a(uv)" - tp:type="Property_Value[]"> - <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> - <tp:docstring> - An array mapping integer property identifiers to boxed values - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - </tp:possible-errors> - </method> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for channels and other objects, to allow querying and setting - properties. ListProperties returns which properties are valid for - the given channel, including their type, and an integer handle used to - refer to them in GetProperties, SetProperties, and the PropertiesChanged - signal. The values are represented by D-Bus variant types, and are - accompanied by flags indicating whether or not the property is readable or - writable.</p> - - <p>Each property also has a flags value to indicate what methods are - available. This is a bitwise OR of PropertyFlags values.</p> - </tp:docstring> - <tp:flags name="Property_Flags" value-prefix="Property_Flag" type="u"> - <tp:flag suffix="Read" value="1"> - <tp:docstring>The property can be read</tp:docstring> - </tp:flag> - <tp:flag suffix="Write" value="2"> - <tp:docstring>The property can be written</tp:docstring> - </tp:flag> - </tp:flags> - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Protocol.xml b/qt4/spec/Protocol.xml deleted file mode 100644 index 5e2c9b197..000000000 --- a/qt4/spec/Protocol.xml +++ /dev/null @@ -1,485 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Protocol" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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.Protocol"> - <tp:added version="0.19.10">(as stable API)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An object representing a protocol for which this <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref> - can create <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s.</p> - - <p>Each Protocol object has the same well-known bus name as its parent - ConnectionManager. Its object path is formed by taking the - ConnectionManager's object path and appending '/', followed by the - <tp:type>Protocol</tp:type> name with any hyphen/minus '-' converted - to underscores '_'.</p> - - <tp:rationale> - <p>This is the same as the representation of protocol names - in Account object paths, and in Connection object paths and bus - names. For instance, telepathy-gabble and telepathy-salut would - implement objects at - <code>/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber</code> - and - <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>, - respectively.</p> - </tp:rationale> - - <p>If the ConnectionManager has a <tt>.manager</tt> file, each - Protocol's immutable properties must be represented in that file; - the representation is described as part of the documentation for - each property. For instance, a very simple ConnectionManager with one - Protocol might be represented like this:</p> - -<pre> -[ConnectionManager] -Interfaces= - -[Protocol example] -Interfaces= -ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests; -param-account=s required -param-password=s required secret -RequestableChannelClasses=text; -VCardField=x-example -EnglishName=Example -Icon=im-example -AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication; - -[text] -org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text -org.freedesktop.Telepathy.Channel.TargetHandleType u=1 -allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; -</pre> - </tp:docstring> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - access="read" type="as" tp:type="DBus_Interface[]" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of interfaces supported by this Protocol object.</p> - - <p>This property should not be confused with - <tp:member-ref>ConnectionInterfaces</tp:member-ref>, - which refers to the interfaces of <em>connections</em> to this - protocol.</p> - - <p>Connection managers with a <code>.manager</code> file - (as described as part of the - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >ConnectionManager</tp:dbus-ref> interface) MUST cache this - property in the protocol's section of the <code>.manager</code> - file, using the key <code>Interfaces</code>. The corresponding value - is a list of D-Bus interface names, each followed by a semicolon.</p> - </tp:docstring> - </property> - - <property name="Parameters" tp:name-for-bindings="Parameters" - access="read" type="a(susv)" tp:type="Param_Spec[]" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The parameters which must or may be provided to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" - >RequestConnection</tp:dbus-ref> method when connecting to the - given protocol.</p> - - <p>Connection managers with a <code>.manager</code> file - (as described as part of the - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >ConnectionManager</tp:dbus-ref> interface) MUST cache this - property in the protocol's section of the <code>.manager</code> - file via keys of the form <code>param-<em>p</em></code> and - <code>default-<em>p</em></code>, as documented in the - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >ConnectionManager</tp:dbus-ref> interface.</p> - </tp:docstring> - </property> - - <property name="ConnectionInterfaces" - tp:name-for-bindings="Connection_Interfaces" - access="read" type="as" tp:type="DBus_Interface[]" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of interface names which might be in the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection" - >Interfaces</tp:dbus-ref> property of a - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection</tp:dbus-ref> to this protocol. Whether a Connection - will have all, some or none of these interfaces depends on server - capabilities.</p> - - <p>This property should not be confused with - <tp:member-ref>Interfaces</tp:member-ref>.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file, using the key - <code>ConnectionInterfaces</code>. The corresponding value - is a list of D-Bus interface names, each followed by a semicolon.</p> - </tp:docstring> - </property> - - <property name="RequestableChannelClasses" - tp:name-for-bindings="Requestable_Channel_Classes" - access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" - tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of channel classes which might be requestable from a - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection</tp:dbus-ref> to this protocol (i.e. they will, - or might, appear in the Connection's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref> property).</p> - - <p>Whether a Connection will have all, some or none of these - requestable channel classes depends on server capabilities; - similarly, individual contacts are not guaranteed to support - all of these channel classes.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file, using the key - <code>RequestableChannelClasses</code>. The corresponding value - is a list of opaque strings, each followed by a semicolon; each - of those strings is the name of a group in the <code>.manager</code> - file which represents a channel class.</p> - - <p>The names of the groups representing channel classes are not - significant, and MUST NOT be interpreted. When writing - <tt>.manager</tt> files, authors MAY choose mnemonic group names, - generate group names mechanically (e.g. with an incrementing - integer), or use some combination of these.</p> - - <p>Each group representing a channel class has a key - <code>allowed</code> which is a list of D-Bus property names - representing allowed parameters. Any other keys that do not contain - a space MUST be ignored. Any key containing a space represents - a fixed property; the key has the form - "<code><em>propertyname</em> <em>type</em></code>", and the value - is encoded in the same way as for the <code>default-<em>p</em></code> - keys described in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >ConnectionManager</tp:dbus-ref> documentation.</p> - - <p>Connection managers that have channel classes whose fixed - properties are not representable in this form SHOULD NOT have - <code>.manager</code> files.</p> - - <p>For instance, this <code>.manager</code> file could represent - a connection manager that supports 1-1 Text messages and - StreamedMedia audio calls:</p> - -<pre>[Protocol jabber] -param-account=s required -param-password=s required -RequestableChannelClasses=rcc0;rcc1; - -[rcc0] -org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text -org.freedesktop.Telepathy.Channel.TargetHandleType u=1 -allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; - -[rcc1] -org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia -org.freedesktop.Telepathy.Channel.TargetHandleType u=1 -allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio; -</pre> - </tp:docstring> - </property> - - <property name="VCardField" tp:name-for-bindings="VCard_Field" - access="read" type="s" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of the most common vCard field used for this protocol's - contact identifiers, normalized to lower case, or the empty string - if there is no such field.</p> - - <p>For example, this would be <code>x-jabber</code> for - Jabber/XMPP (including Google Talk), or <code>tel</code> for - the <abbr title="Public Switched Telephone Network">PSTN</abbr>.</p> - - <p>A more exhaustive list of addressable vCard fields can be found in - the Protocol's Addressing interface's - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p> - - <p>It is not necessarily valid to interpret contacts' identifiers - as values of this vCard field. For instance, telepathy-sofiasip - supports contacts whose identifiers are of the form - sip:jenny@example.com or tel:8675309, which would not normally - both be represented by any single vCard field. Arbitrary - handles/identifiers as vCard fields are represented - through the Connection's - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Addressing.DRAFT</tp:dbus-ref> - contact attributes.</p> - - <tp:rationale> - <p>This is taken from Mission Control profiles as used on Maemo 5. - One valid use of this field is to answer the question: given a - contact's vCard containing an X-JABBER field, how can you - communicate with the contact? By iterating through protocols - looking for an x-jabber VCardField, one can build up a list of - protocols that handle x-jabber, then offer the user a list of - accounts for those protocols and/or the option to create a new - account for one of those protocols.</p> - </tp:rationale> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file if it is non-empty, using the key - <code>VCardField</code>. The corresponding value - is a string, following the syntax of the "localestring" type from - the Desktop Entry Specification.</p> - </tp:docstring> - </property> - - <property name="EnglishName" tp:name-for-bindings="English_Name" - access="read" type="s" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of the protocol in a form suitable for display to users, - such as "AIM" or "Yahoo!", or the empty string if none is - available.</p> - - <p>This is effectively in the C locale (international English); - user interfaces requiring a localized protocol name SHOULD look - one up in their own message catalog based on either the Telepathy - <tp:type>Protocol</tp:type> name or this property, but SHOULD use - this English version as a fallback if no translated version can be - found.</p> - - <tp:rationale> - <p>Many protocols are named after a company or product which isn't - translated in non-English locales. This also provides a fallback - display name, for UIs with no prior knowledge of a particular - protocol.</p> - </tp:rationale> - - <p>If this property's value is empty, clients MAY fall back to using - the Telepathy <tp:type>Protocol</tp:type> name, possibly with its - capitalization adjusted.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file if it is non-empty, using the key - <code>EnglishName</code>. The corresponding value - is a string, following the syntax of the "localestring" type from - the Desktop Entry Specification.</p> - </tp:docstring> - </property> - - <property name="Icon" tp:name-for-bindings="Icon" - access="read" type="s" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of an icon in the system's icon theme, such as "im-msn", or - the empty string.</p> - - <tp:rationale> - <p>This can be used as a default if the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref> - property is not set on an Account, or used by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref> - to choose a default icon if none is set during account - creation.</p> - </tp:rationale> - - <p>If this property's value is empty, clients MAY fall back to - generating a name based on the <tp:type>Protocol</tp:type> name.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file if it is non-empty, using the key - <code>Icon</code>. The corresponding value - is a string, following the syntax of the "localestring" type from - the Desktop Entry Specification.</p> - </tp:docstring> - </property> - - <method name="IdentifyAccount" - tp:name-for-bindings="Identify_Account"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Return a string which uniquely identifies the account to which the - given parameters would connect.</p> - - <tp:rationale> - <p>For many protocols, this would return the well-known 'account' - parameter. However, for IRC the returned string would be composed - from the 'account' (i.e. nickname) and 'server' parameters. - AccountManager implementations can use this to form the - account-specific part of an Account's object path.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Parameters" - type="a{sv}" tp:type="String_Variant_Map"> - <tp:docstring> - A set of parameters as would be provided to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ConnectionManager" - >RequestConnection</tp:dbus-ref> - </tp:docstring> - </arg> - - <arg direction="out" name="Account_ID" type="s"> - <tp:docstring> - <p>An opaque string suitable for use as the account-specific part of - an <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Account</tp:dbus-ref>'s object path. This is not necessarily - globally unique, but should represent a "best-effort" - identification of the account.</p> - - <tp:rationale> - <p>For a pathological case, consider a user signing in as - 'me@example.com' with 'server' set to either jabber1.example.com - or jabber2.example.com. Both of these should result in - me@example.com being returned from this method, even if the user - can actually be signed in to those two servers - simultaneously.</p> - </tp:rationale> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The IdentifyAccount method is not supported by this connection - manager. The caller SHOULD fall back to deriving identification - from the parameters. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="NormalizeContact" - tp:name-for-bindings="Normalize_Contact"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Attempt to normalize the given contact ID. Where possible, this - SHOULD return the same thing that would be returned by - InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection</tp:dbus-ref>.</p> - - <p>If full normalization requires network activity or is otherwise - impossible to do without a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, - this method SHOULD perform a best-effort normalization.</p> - - <tp:rationale> - <p>One common example of a best-effort offline normalization - differing from the ideal normalization is XMPP.</p> - - <p>On XMPP, contacts' JIDs should normally have the resource removed - during normalization, but for contacts in a MUC (chatroom), the - resource is an integral part of the JID - so the contact JID - alice@example.com/Empathy should normalize to alice@example.com, - but the in-MUC JID wonderland@conference.example.com/Alice should - normalize to itself.</p> - - <p>While online, the connection manager has enough context to know - which chatrooms the user is in, and can infer from that whether - to remove resources, but the best-effort normalization performed - while offline does not have this context, so the best that can be - done is to remove the resource from all JIDs.</p> - </tp:rationale> - - <p>This method MAY simply raise NotImplemented on some protocols.</p> - - <tp:rationale> - <p>In link-local XMPP, you can't talk to someone who isn't present - on your local network, so normalizing identifiers in advance is - meaningless.</p> - </tp:rationale> - </tp:docstring> - - <arg direction="in" name="Contact_ID" type="s"> - <tp:docstring> - The identifier of a contact in this protocol - </tp:docstring> - </arg> - - <arg direction="out" name="Normalized_Contact_ID" type="s"> - <tp:docstring> - The identifier of a contact in this protocol, normalized as much - as possible - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The NormalizeContact method is not supported by this connection - manager. The caller MAY recover by using the contact ID as-is. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <property name="AuthenticationTypes" - tp:name-for-bindings="Authentication_Types" access="read" type="as" - tp:type="DBus_Interface[]" tp:immutable="yes"> - <tp:added version="0.21.7"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A list of D-Bus interfaces which provide information as to - what kind of authentication channels can possibly appear - before the connection reaches the CONNECTED state.</p> - - <p>These can either be channel types, or where the channel - type isn't enough information to be useful, interfaces - indicating a specific use of a channel type. For example, - <tp:dbus-ref namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> - channels are obviously about TLS certificates so the channel - type would appear in this list. However, a - <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channel type alone does not explain enough about the authentication type - in use as it is merely a base for the channel interfaces that appear in - said channels. In this case, CMs should use the value of the - <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref> - property in this list.</p> - - <p>For example, if a protocol's - <tp:member-ref>AuthenticationTypes</tp:member-ref> contains - two values:</p> - - <blockquote> - <pre> -[ ...<tp:dbus-ref namespace="ofdT">Channel.Type.ServerTLSConnection</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT">Channel.Interface.SASLAuthentication</tp:dbus-ref> ]</pre></blockquote> - - <p>This tells a client that before the connection status - reached CONNECTED, a <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> - could appear carrying a TLS certificate. It also tells the - client that before the connection status reaches CONNECTED, a - <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> - channel could also appear, where <tp:dbus-ref - namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>=<tp:dbus-ref - namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>. A - hypothetical future Channel.Interface.Captcha interface would - also appear in this list if the CM might require the user - solve a captcha before connecting.</p> - - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Protocol_Interface_Addressing.xml b/qt4/spec/Protocol_Interface_Addressing.xml deleted file mode 100644 index 3722c3b81..000000000 --- a/qt4/spec/Protocol_Interface_Addressing.xml +++ /dev/null @@ -1,300 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Protocol_Interface_Addressing" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Protocol.Interface.Addressing.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for protocols that support multiple forms of - addressing contacts, for example through vCard addresses and URIs.</p> - - <p>If the ConnectionManager has a <tt>.manager</tt> file, and it - supports this interface, the interface's immutable properties - must be represented in the file; the representation is described as - part of the documentation for each property.</p> - - <p>For instance, a SIP connection manager might have the - following lines in the <tt>.manager</tt> file.</p> - -<pre> -[Protocol sip] -AddressableVCardFields=tel;x-sip; -AddressableURISchemes=tel;sip; -</pre> - </tp:docstring> - - <property name="AddressableVCardFields" - tp:name-for-bindings="Addressable_VCard_Fields" - access="read" type="as"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The vCard fields that can be used to request a contact with - normalized to lower case. If the <code>URL</code> vCard - field is addressable, a colon, followed by the supported URI - schemes will be concatenated.</p> - - <p>For example: <code>["tel", "x-sip"]</code>.</p> - - <p>The <code>url</code> vCard field MUST NOT appear here; see - <tp:member-ref>AddressableURISchemes</tp:member-ref> instead.</p> - - <tp:rationale> - <p>In practice, protocols have a limited set of URI - schemes that make sense to resolve as a contact.</p> - </tp:rationale> - - <p>This property should only be used when the connection is - offline. When it is connected the addressable fields should be - retrieved from the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s - TargetVCardField fixed-property instead.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file if it is non-empty, using the key - <code>AddressableVCardFields</code>. The corresponding value - is a list of strings, each followed with a semicolon and in the - syntax of the "localestring" type from the Desktop Entry - Specification.</p> - - <p>Well-known vCard fields:</p> - - <dl> - <dt><code>tel</code></dt> - <dd>The TEL vCard field. Used for phone numbers.</dd> - <dt><code>x-sip</code></dt> - <dd>The X-SIP vCard field. Used for SIP addresses.</dd> - <dt><code>x-aim</code></dt> - <dd>The X-AIM vCard field. Used for AIM user IDs.</dd> - <dt><code>x-icq</code></dt> - <dd>The X-ICQ vCard field. Used for ICQ UINs.</dd> - <dt><code>x-skype</code></dt> - <dd>The X-SKYPE vCard field. Used for Skype user names or - telephone numbers. There is also a X-SKYPE-USERNAME field, - but for Telepathy purposes, <code>x-skype</code> is preferred</dd> - <dt><code>x-groupwise</code></dt> - <dd>The X-GROUPWISE vCard field. Used for Groupwise contacts.</dd> - <dt><code>x-gadugadu</code></dt> - <dd>The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.</dd> - <dt><code>x-jabber</code></dt> - <dd>The X-JABBER vCard field. Used for XMPP JIDs.</dd> - <dt><code>x-msn</code></dt> - <dd>The X-MSN vCard field. Used for MSN contacts.</dd> - <dt><code>x-yahoo</code></dt> - <dd>The X-YAHOO vCard field. Used for Yahoo! IDs.</dd> - </dl> - - </tp:docstring> - </property> - - <property name="AddressableURISchemes" - tp:name-for-bindings="Addressable_URI_Schemes" - access="read" type="as"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The URI schemes that are supported by this protocol.</p> - - <p>For example: <code>["tel", "sip"]</code>.</p> - - <p>This property should only be used when the connection is - offline. When it is connected the addressable URI schemes should be - retrieved from the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s - TargetURIScheme fixed-property instead.</p> - - <p>Connection managers with a <code>.manager</code> file - MUST cache this property in the protocol's section of the - <code>.manager</code> file if it is non-empty, using the key - <code>AddressableURISchemes</code>. The corresponding value - is a list of strings, each followed with a semicolon and in the - syntax of the "localestring" type from the Desktop Entry - Specification.</p> - - <p>Well-known URI schemes:</p> - - <dl> - <dt><code>sip</code></dt> - <dd>SIP protocol. - For example: <code>sip:julien@example.com</code>.</dd> - <dt><code>sips</code></dt> - <dd>Secure (encrypted) SIP protocol. - For example: <code>sips:julien@example.com</code>.</dd> - <dt><code>tel</code></dt> - <dd>Used for telephone numbers. - For example: <code>tel:+12065551234</code>.</dd> - <dt><code>xmpp</code></dt> - <dd>XMPP protocol. - For example: <code>xmpp:julien@example.com</code>.</dd> - <dt><code>msnim</code></dt> - <dd>For the purposes of - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, - and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, - the verb part is ignored, and SHOULD be <code>add</code>; the - <code>contact</code> field in the query string is used to - identify the contact. - For example: <code>msnim:add?contact=julien</code>.</dd> - <dt><code>aim</code></dt> - <dd>For the purposes of - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, - and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, - the verb part is ignored, and SHOULD be <code>addbuddy</code>; the - <code>screenname</code> field in the query string is used to - identify the contact. - For example: <code>aim:addbuddy?screenname=julien</code>.</dd> - <dt><code>skype</code></dt> - <dd>Skype protocol. - For example: <code>skype:julien</code>.</dd> - <dt><code>ymsgr</code></dt> - <dd>For the purposes of - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, - and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, - the verb part is ignored, and SHOULD be <code>addfriend</code>; the - query string is used to identify the contact. - For example: <code>ymsgr:addfriend?julien</code>.</dd> - <dt><code>gg</code></dt> - <dd>Gadu-Gadu protocol. - For example: <code>gg:julien</code>.</dd> - </dl> - </tp:docstring> - </property> - - <method name="NormalizeVCardAddress" - tp:name-for-bindings="Normalize_VCard_Address"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Attempt to normalize the given vCard address. Where possible, this - SHOULD return an address that would appear in the - <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses</code> - attribute for a contact on a connected - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. - </p> - - <p>If full normalization requires network activity or is otherwise - impossible to do without a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, - this method SHOULD perform a best-effort normalization.</p> - - <p>An example would be a vCard TEL field with a formatted - number in the form of <code>+1 (206) 555 1234</code>, this would be - normalized to <code>+12065551234</code>.</p> - - <p>This method MAY simply raise NotImplemented on some - protocols, if it has no use.</p> - </tp:docstring> - - <arg direction="in" name="VCard_Field" type="s"> - <tp:docstring> - The vCard field of the address we are normalizing. The - field name SHOULD be in lower case, and MUST appear in - <tp:member-ref>AddressableVCardFields</tp:member-ref>. - </tp:docstring> - </arg> - - <arg direction="in" name="VCard_Address" type="s"> - <tp:docstring> - The address to normalize. - </tp:docstring> - </arg> - - <arg direction="out" name="Normalized_VCard_Address" type="s"> - <tp:docstring> - The vCard address, normalized as much as possible. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The vCard field is not supported (it is not in - <tp:member-ref>AddressableVCardFields</tp:member-ref>). - </tp:docstring> - </tp:error> - - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The address is syntactically incorrect. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="NormalizeURI" - tp:name-for-bindings="Normalize_URI"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Attempt to normalize the given contact URI. Where possible, this - SHOULD return an address that would appear in the - <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris</code> - attribute for a contact on a connected - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. - </p> - - <p>If full normalization requires network activity or is otherwise - impossible to do without a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, - this method SHOULD perform a best-effort normalization.</p> - - <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to - <code>xmpp:eitan@example.com</code>.</p> - - <p>This method MAY simply raise NotImplemented on some - protocols, if it has no use.</p> - </tp:docstring> - - <arg direction="in" name="URI" type="s"> - <tp:docstring> - The URI to normalize. The URI's scheme (i.e. the part before - the first colon) MUST appear in - <tp:member-ref>AddressableURISchemes</tp:member-ref>. - </tp:docstring> - </arg> - - <arg direction="out" name="Normalized_URI" type="s"> - <tp:docstring> - A URI, normalized as much as possible. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The URI scheme is not supported (it is not in - <tp:member-ref>AddressableURISchemes</tp:member-ref>). - </tp:docstring> - </tp:error> - - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The URI is syntactically incorrect. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Protocol_Interface_Avatars.xml b/qt4/spec/Protocol_Interface_Avatars.xml deleted file mode 100644 index cd913510d..000000000 --- a/qt4/spec/Protocol_Interface_Avatars.xml +++ /dev/null @@ -1,157 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Protocol_Interface_Avatars" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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.Protocol.Interface.Avatars"> - <tp:added version="0.21.5">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for protocols where it might be possible to set the - user's avatar, and the expected size limits and supported MIME types - are known before connecting.</p> - - <tp:rationale> - <p>If the avatar requirements cannot be discovered while offline, - it's impossible to avoid setting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Account</tp:dbus-ref>'s <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Account.Interface.Avatar" - >Avatar</tp:dbus-ref> property to an unsupported avatar.</p> - </tp:rationale> - - <p>Each property on this interface SHOULD be cached in the - <code>.manager</code> file, using a key of the same name as the - property in the <code>[Protocol <em>proto</em>]</code> - group. All properties are encoded in ASCII decimal in the obvious - way, except for - <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is - encoded as a sequence of strings each followed by a semicolon - (as for the "localestrings" type in the Desktop Entry - Specification).</p> - - <p>For instance, an XMPP connection manager might have this - <code>.manager</code> file:</p> - -<pre>[Protocol jabber] -Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars; -param-account=s required -param-password=s required -SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif; -MinimumAvatarHeight=32 -RecommendedAvatarHeight=64 -MaximumAvatarHeight=96 -MinimumAvatarWidth=32 -RecommendedAvatarWidth=64 -MaximumAvatarWidth=96 -MaximumAvatarBytes=8192 -</pre> - </tp:docstring> - - <property name="SupportedAvatarMIMETypes" - tp:name-for-bindings="Supported_Avatar_MIME_Types" - type="as" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="MinimumAvatarHeight" - tp:name-for-bindings="Minimum_Avatar_Height" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref> - property on connections to this protocol. -</tp:docstring> - </property> - - <property name="MinimumAvatarWidth" - tp:name-for-bindings="Minimum_Avatar_Width" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="RecommendedAvatarHeight" - tp:name-for-bindings="Recommended_Avatar_Height" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="RecommendedAvatarWidth" - tp:name-for-bindings="Recommended_Avatar_Width" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="MaximumAvatarHeight" - tp:name-for-bindings="Maximum_Avatar_Height" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="MaximumAvatarWidth" - tp:name-for-bindings="Maximum_Avatar_Width" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - - <property name="MaximumAvatarBytes" - tp:name-for-bindings="Maximum_Avatar_Bytes" - type="u" access="read"> - <tp:docstring> - The expected value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref> - property on connections to this protocol. - </tp:docstring> - </property> - </interface> -</node> diff --git a/qt4/spec/Protocol_Interface_Presence.xml b/qt4/spec/Protocol_Interface_Presence.xml deleted file mode 100644 index ddff33263..000000000 --- a/qt4/spec/Protocol_Interface_Presence.xml +++ /dev/null @@ -1,113 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Protocol_Interface_Presence" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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.Protocol.Interface.Presence"> - <tp:added version="0.21.3">(as stable API)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for protocols where it might be possible to set the - user's presence, and the supported presence types can be predicted - before connecting.</p> - - <tp:rationale> - <p>This allows UIs to show or hide presence types that aren't - always supported, such as "invisible", while not online.</p> - </tp:rationale> - - <p>The properties on this interface SHOULD be cached in the - <code>.manager</code> file, in the - <code>[Protocol <em>proto</em>]</code> - group. For each status <em>s</em> in - <tp:member-ref>Statuses</tp:member-ref>, that group should - contain a key of the form <code>status-<em>s</em></code> whose value - is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII - decimal integer, followed by a space-separated sequence of tokens - from the following set:</p> - - <dl> - <dt>settable</dt> - <dd>If present, the user can set this status on themselves using - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence" - >SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self - in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd> - - <dt>message</dt> - <dd>If present, the user can set a non-empty message for this status; - this corresponds to Can_Have_Message in the - <tp:type>Simple_Status_Spec</tp:type> struct.</dd> - </dl> - - <p>Unrecognised tokens MUST be ignored.</p> - - <p>For instance, an XMPP connection manager might have this - <code>.manager</code> file:</p> - -<pre>[Protocol jabber] -Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence; -param-account=s required -param-password=s required -status-offline=1 -status-unknown=7 -status-error=8 -status-hidden=5 settable message -status-xa=4 settable message -status-away=3 settable message -status-dnd=6 settable message -status-available=2 settable message -status-chat=2 settable message -</pre> - - <p>which corresponds to these property values (using a Python-like - syntax):</p> - -<pre>Statuses = { - 'offline': (OFFLINE, False, False), - 'unknown': (UNKNOWN, False, False), - 'error': (ERROR, False, False), - 'hidden': (HIDDEN, True, True), - 'xa': (EXTENDED_AWAY, True, True), - 'away': (AWAY, True, True), - 'dnd': (BUSY, True, True), - 'available': (AVAILABLE, True, True), - 'chat': (AVAILABLE, True, True), -} -</pre> - </tp:docstring> - - <property name="Statuses" - tp:name-for-bindings="Statuses" - type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read"> - <tp:docstring> - <p>The statuses that might appear in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.Interface.SimplePresence.Statuses</tp:dbus-ref> - property on a connection to this protocol that supports - SimplePresence. This property is immutable.</p> - - <p>Depending on server capabilities, it is possible that not all - of these will actually appear on the Connection.</p> - </tp:docstring> - </property> - - </interface> -</node> diff --git a/qt4/spec/all.xml b/qt4/spec/all.xml deleted file mode 100644 index 31db78062..000000000 --- a/qt4/spec/all.xml +++ /dev/null @@ -1,313 +0,0 @@ -<tp:spec - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" - xmlns:xi="http://www.w3.org/2001/XInclude"> - -<tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.22.0</tp:version> - -<tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright> -<tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright> -<tp:copyright>Copyright © 2006 INdT</tp:copyright> - -<tp:license xmlns="http://www.w3.org/1999/xhtml"> -<p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> -</tp:license> - -<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"/> - <xi:include href="Connection_Manager_Interface_Account_Storage.xml"/> - <xi:include href="Protocol.xml"/> - <xi:include href="Protocol_Interface_Addressing.xml"/> - <xi:include href="Protocol_Interface_Avatars.xml"/> - <xi:include href="Protocol_Interface_Presence.xml"/> - - <tp:section name="Connection Object"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - Connections represent active protocol sessions. There are a number of core - interfaces which all connections should implement, and a number of optional - interfaces which provide various functionality related to contacts and to - the connection itself. - </p> - </tp:docstring> - <xi:include href="Connection.xml"/> - <xi:include href="Connection_Future.xml"/> - <xi:include href="Connection_Interface_Contacts.xml"/> - <xi:include href="Connection_Interface_Requests.xml"/> - - <tp:section name="Contact list interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - On protocols that support contact lists, these interface expose the user's - contact lists, along with presence subscription information, contact - list groups (if supported), and the ability to block and unblock contacts - (if supported). - </p> - </tp:docstring> - - <xi:include href="Connection_Interface_Contact_List.xml"/> - <xi:include href="Connection_Interface_Contact_Groups.xml"/> - <xi:include href="Connection_Interface_Contact_Blocking.xml"/> - </tp:section> - - <tp:section name="Contact metadata interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - These optional Connection interfaces expose metadata about contacts on - this connection—from their current presence through to the type of client - they're connected with—and allow the local user to publish such metadata - back to their contacts. - </p> - </tp:docstring> - - <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_Client_Types.xml"/> - <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> - <xi:include href="Connection_Interface_Contact_Info.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_Resources.xml"/> - <xi:include href="Connection_Interface_Simple_Presence.xml"/> - </tp:section> - - <tp:section name="Connection feature interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - These optional Connection interfaces expose protocol-specific features, - and allow configuring the running connection. - </p> - </tp:docstring> - - <xi:include href="Connection_Interface_Addressing.xml"/> - <xi:include href="Connection_Interface_Anonymity.xml"/> - <xi:include href="Connection_Interface_Balance.xml"/> - <xi:include href="Connection_Interface_Cellular.xml"/> - <xi:include href="Connection_Interface_Communication_Policy.xml"/> - <xi:include href="Connection_Interface_Forwarding.xml"/> - <xi:include href="Connection_Interface_Keepalive.xml"/> - <xi:include href="Connection_Interface_Mail_Notification.xml"/> - <xi:include href="Connection_Interface_Power_Saving.xml"/> - <xi:include href="Connection_Interface_Service_Point.xml"/> - </tp:section> - </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_Call.xml"/> - <xi:include href="Channel_Type_Contact_List.xml"/> - <xi:include href="Channel_Type_Contact_Search.xml"/> - <xi:include href="Channel_Type_DBus_Tube.xml"/> - <xi:include href="Channel_Type_File_Transfer.xml"/> - <xi:include href="Channel_Type_Room_List.xml"/> - <xi:include href="Channel_Type_Server_Authentication.xml"/> - <xi:include href="Channel_Type_Server_TLS_Connection.xml"/> - <xi:include href="Channel_Type_Stream_Tube.xml"/> - <xi:include href="Channel_Type_Streamed_Media.xml"/> - <xi:include href="Channel_Type_Text.xml"/> - <xi:include href="Channel_Type_Tubes.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. Some interfaces are only applicable to particular - channel types, while others may (in principle) appear on any type of - channel. - </p> - </tp:docstring> - - <xi:include href="Channel_Interface_Addressing.xml"/> - <xi:include href="Channel_Interface_Anonymity.xml"/> - <xi:include href="Channel_Interface_Destroyable.xml"/> - <xi:include href="Channel_Interface_Group.xml"/> - <xi:include href="Channel_Interface_Password.xml"/> - <xi:include href="Channel_Interface_Room.xml"/> - <xi:include href="Channel_Interface_SASL_Authentication.xml"/> - <xi:include href="Channel_Interface_Credentials_Storage.xml"/> - <xi:include href="Channel_Interface_Securable.xml"/> - <xi:include href="Channel_Interface_Service_Point.xml"/> - <xi:include href="Channel_Interface_Tube.xml"/> - - <tp:section name="Text-specific interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>These interfaces may only appear on channels of type <tp:dbus-ref - namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</p> - </tp:docstring> - - <xi:include href="Channel_Interface_Chat_State.xml"/> - <xi:include href="Channel_Interface_HTML.xml"/> - <xi:include href="Channel_Interface_Messages.xml"/> - <xi:include href="Channel_Interface_SMS.xml"/> - </tp:section> - - <tp:section name="Streamed Media/Call-related interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>These interfaces are only applicable to channels of type <tp:dbus-ref - namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref>, with the - exception of the <tp:dbus-ref - namespace='ofdT.Channel.Interface'>Hold</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Channel.Interface">DTMF</tp:dbus-ref> - interfaces, which may also appear on <tp:dbus-ref - namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels.</p> - </tp:docstring> - - <xi:include href="Channel_Interface_Call_State.xml"/> - <xi:include href="Channel_Interface_DTMF.xml"/> - <xi:include href="Channel_Interface_Hold.xml"/> - <xi:include href="Channel_Interface_Media_Signalling.xml"/> - </tp:section> - - <tp:section name="Conference-related interfaces"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>These interfaces provide functionality for ad-hoc conference calls and - chat rooms. They are primarily intended for <tp:dbus-ref - namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>, <tp:dbus-ref - namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> and - <tp:dbus-ref namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> - channels, but may also appear on other types of channel.</p> - </tp:docstring> - - <xi:include href="Channel_Interface_Conference.xml"/> - <xi:include href="Channel_Interface_Splittable.xml"/> - <xi:include href="Channel_Interface_Mergeable_Conference.xml"/> - </tp:section> - </tp:section> - </tp:section> - - <tp:section name="Authentication Objects"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> - A set of objects to be used for authentication purposes, such - as TLS certificates or handshakes for negotiating end-to-end - security. - </p> - </tp:docstring> - <xi:include href="Authentication_TLS_Certificate.xml"/> - </tp:section> - - <tp:section name="Media"> - <xi:include href="Media_Session_Handler.xml"/> - <xi:include href="Media_Stream_Handler.xml"/> - </tp:section> - - <tp:section name="Calls"> - <xi:include href="Call_Content.xml"/> - <xi:include href="Call_Content_Interface_Media.xml"/> - <xi:include href="Call_Content_Interface_Mute.xml"/> - <xi:include href="Call_Content_Interface_Video_Control.xml"/> - <xi:include href="Call_Content_Codec_Offer.xml"/> - <xi:include href="Call_Stream.xml"/> - <xi:include href="Call_Stream_Interface_Media.xml"/> - <xi:include href="Call_Stream_Endpoint.xml"/> - </tp:section> - - <tp:section name="Debugging"> - <xi:include href="Debug.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_Manager_Interface_Hidden.xml"/> - <xi:include href="Account.xml"/> - <xi:include href="Account_Interface_Addressing.xml"/> - <xi:include href="Account_Interface_Avatar.xml"/> - <xi:include href="Account_Interface_Hidden.xml"/> - <xi:include href="Account_Interface_Storage.xml"/> - <xi:include href="Account_Interface_External_Password_Storage.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_Dispatcher_Interface_Messages.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_Handler_Future.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="errors.xml"/> -<xi:include href="generic-types.xml"/> - -<!-- Never implemented, vague -<xi:include href="Connection_Interface_Privacy.xml"/> --> -<!-- Causes havoc, never implemented, unclear requirements -<xi:include href="Channel_Interface_Transfer.xml"/> --> - -</tp:spec> diff --git a/qt4/spec/errors.xml b/qt4/spec/errors.xml deleted file mode 100644 index d63662edb..000000000 --- a/qt4/spec/errors.xml +++ /dev/null @@ -1,601 +0,0 @@ -<?xml version="1.0" ?> -<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The D-Bus errors used in Telepathy all start with - <code>org.freedesktop.Telepathy.Error.</code>. They are used in - D-Bus messages of type ERROR, and also as plain strings annotated with - the <tp:type>DBus_Error_Name</tp:type> type.</p> - - <p>In principle, any method can raise any error (this is a general fact - of IPC). For instance, generic D-Bus errors starting with - <code>org.freedesktop.DBus.Error.</code> will occur in some - situations.</p> - - <p>Telepathy methods can also raise implementation-specific errors to - indicate specialized failure conditions. For better interoperability, - if a suitable Telepathy error exists, it should be preferred.</p> - - <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code> - is reserved for use by the D-Bus client implementation in telepathy-qt4, - which uses it to represent certain error situations that did not involve - a D-Bus ERROR message. These errors are defined and documented as part of - telepathy-qt4's C++ API, and should not be used on D-Bus.</p> - </tp:docstring> - - <tp:error name="Network Error"> - <tp:docstring> - Raised when there is an error reading from or writing to the network. - </tp:docstring> - </tp:error> - - <tp:error name="Not Implemented"> - <tp:docstring> - Raised when the requested method, channel, etc is not available on this connection. - </tp:docstring> - </tp:error> - - <tp:error name="Invalid Argument"> - <tp:docstring> - Raised when one of the provided arguments is invalid. - </tp:docstring> - </tp:error> - - <tp:error name="Not Available"> - <tp:docstring> - Raised when the requested functionality is temporarily unavailable. - </tp:docstring> - </tp:error> - - <tp:error name="Permission Denied"> - <tp:docstring> - The user is not permitted to perform the requested operation. - </tp:docstring> - </tp:error> - - <tp:error name="Disconnected"> - <tp:docstring> - The connection is not currently connected and cannot be used. - This error may also be raised when operations are performed on a - Connection for which - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref> - has signalled status Disconnected for reason None. - - <tp:rationale> - The second usage corresponds to None in the - <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason - is available, the corresponding error should be used instead. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Invalid Handle"> - <tp:docstring> - The handle specified is unknown on this channel or connection. - </tp:docstring> - </tp:error> - - <tp:error name="Channel.Banned"> - <tp:docstring> - You are banned from the channel. - </tp:docstring> - </tp:error> - - <tp:error name="Channel.Full"> - <tp:docstring> - The channel is full. - </tp:docstring> - </tp:error> - - <tp:error name="Channel.Invite Only"> - <tp:docstring> - The requested channel is invite-only. - </tp:docstring> - </tp:error> - - <tp:error name="Not Yours"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The requested channel or other resource already exists, and another - user interface in this session is responsible for it.</p> - - <p>User interfaces SHOULD handle this error unobtrusively, since it - indicates that some other user interface is already processing the - channel.</p> - </tp:docstring> - </tp:error> - - <tp:error name="Cancelled"> - <tp:docstring> - Raised by an ongoing request if it is cancelled by user request before - it has completed, or when operations are performed on an object which - the user has asked to close (for instance, a Connection where the user - has called Disconnect, or a Channel where the user has called Close). - - <tp:rationale> - The second form can be used to correspond to the Requested member in - the <tp:type>Connection_Status_Reason</tp:type> enum, or to - to represent the situation where disconnecting a Connection, - closing a Channel, etc. has been requested by the user but this - request has not yet been acted on, for instance because the - service will only act on the request when it has finished processing - an event queue. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Authentication Failed"> - <tp:docstring> - Raised when authentication with a service was unsuccessful. - <tp:rationale> - This corresponds to Authentication_Failed in the - <tp:type>Connection_Status_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Encryption Not Available"> - <tp:docstring> - Raised if a user request insisted that encryption should be used, - but encryption was not actually available. - - <tp:rationale> - This corresponds to part of Encryption_Error in the - <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated - into a distinct error here because the two concepts that were part - of EncryptionError seem to be things that could reasonably appear - differently in the UI. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Encryption Error"> - <tp:docstring> - Raised if encryption appears to be available, but could not actually be - used (for instance if SSL/TLS negotiation fails). - <tp:rationale> - This corresponds to part of Encryption_Error in the - <tp:type>Connection_Status_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Not Provided"> - <tp:docstring> - Raised if the server did not provide a SSL/TLS certificate. This error - MUST NOT be used to represent the absence of a client certificate - provided by the Telepathy connection manager. - <tp:rationale> - This corresponds to Cert_Not_Provided in the - <tp:type>Connection_Status_Reason</tp:type> enum. That error - explicitly applied only to server SSL certificates, so this one - is similarly limited; having the CM present a client certificate - is a possible future feature, but it should have its own error - handling. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Untrusted"> - <tp:docstring> - Raised if the server provided a SSL/TLS certificate signed by an - untrusted certifying authority. This error SHOULD NOT be used to - represent a self-signed certificate: see the Self Signed error for that. - <tp:rationale> - This corresponds to Cert_Untrusted in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Untrusted in the - <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum, with a clarification - to avoid ambiguity. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Expired"> - <tp:docstring> - Raised if the server provided an expired SSL/TLS certificate. - <tp:rationale> - This corresponds to Cert_Expired in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Expired in - the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Not Activated"> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that will become - valid at some point in the future. - <tp:rationale> - This corresponds to Cert_Not_Activated in the - <tp:type>Connection_Status_Reason</tp:type> enum and to - Not_Activated in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Fingerprint Mismatch"> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that did not have - the expected fingerprint. - <tp:rationale> - This corresponds to Cert_Fingerprint_Mismatch in the - <tp:type>Connection_Status_Reason</tp:type> enum and to - Fingerprint_Mismatch in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Hostname Mismatch"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Raised if the server provided an SSL/TLS certificate that did not match - its hostname.</p> - <p>You MAY be able to get more details about the expected and certified - hostnames by looking up the 'expected-hostname' and 'certificate-hostname' - keys in the details map that came together with this error.</p> - <tp:rationale> - This corresponds to Cert_Hostname_Mismatch in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Hostname_Mismatch - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Self Signed"> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that is self-signed - and untrusted. - <tp:rationale> - This corresponds to Cert_Self_Signed in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Self_Signed - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Revoked"> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that has been - revoked. - <tp:rationale> - This corresponds to Cert_Revoked in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Revoked - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Insecure"> - <tp:added version="0.19.11"/> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that uses an - insecure cipher algorithm or is cryptographically weak. - <tp:rationale> - This corresponds to Cert_Insecure in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Insecure - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Invalid"> - <tp:added version="0.19.11"/> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that is - unacceptable in some way that does not have a more specific error. - <tp:rationale> - This corresponds to Cert_Other_Error in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Unknown - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Cert.Limit Exceeded"> - <tp:added version="0.19.11"/> - <tp:docstring> - Raised if the length in bytes of the server certificate, or the depth of the - server certificate chain exceeds the limits imposed by the crypto - library. - <tp:rationale> - This corresponds to Cert_Limit_Exceeded in the - <tp:type>Connection_Status_Reason</tp:type> enum and to Limit_Exceeded - in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Not Capable"> - <tp:docstring> - Raised when requested functionality is unavailable due to contact - not having required capabilities. - </tp:docstring> - </tp:error> - - <tp:error name="Offline"> - <tp:docstring> - Raised when requested functionality is unavailable because a contact is - offline. - - <tp:rationale> - This corresponds to Offline in the - <tp:type>Channel_Group_Change_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Channel.Kicked"> - <tp:docstring> - Used to represent a user being ejected from a channel by another user, - for instance being kicked from a chatroom. - - <tp:rationale> - This corresponds to Kicked in the - <tp:type>Channel_Group_Change_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Busy"> - <tp:docstring> - Used to represent a user being removed from a channel because of a - "busy" indication. This error SHOULD NOT be used to represent a server - or other infrastructure being too busy to process a request - for that, - see ServerBusy. - - <tp:rationale> - This corresponds to Busy in the - <tp:type>Channel_Group_Change_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="No Answer"> - <tp:docstring> - Used to represent a user being removed from a channel because they did - not respond, e.g. to a StreamedMedia call. - - <tp:rationale> - This corresponds to No_Answer in the - <tp:type>Channel_Group_Change_Reason</tp:type> enum. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Does Not Exist"> - <tp:docstring> - Raised when the requested user does not, in fact, exist. - - <tp:rationale> - This corresponds to Invalid_Contact in the - <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be - used to represent other things not existing (like chatrooms, perhaps). - </tp:rationale> - </tp:docstring> - </tp:error> - - <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:error name="Connection Refused"> - <tp:docstring> - Raised when a connection is refused. - </tp:docstring> - </tp:error> - - <tp:error name="Connection Failed"> - <tp:docstring> - Raised when a connection can't be established. - </tp:docstring> - </tp:error> - - <tp:error name="Connection Lost"> - <tp:docstring> - Raised when a connection is broken. - </tp:docstring> - </tp:error> - - <tp:error name="Already Connected"> - <tp:docstring> - Raised when the user attempts to connect to an account but they are - already connected (perhaps from another client or computer), and the - protocol or account settings do not allow this. - - <tp:rationale> - XMPP can have this behaviour if the user chooses the same resource - in both clients (it is server-dependent whether the result is - AlreadyConnected on the new connection, ConnectionReplaced on the - old connection, or two successful connections). - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Connection Replaced"> - <tp:docstring> - Raised by an existing connection to an account if it is replaced by - a new connection (perhaps from another client or computer). - - <tp:rationale> - In MSNP, when connecting twice with the same Passport, the new - connection "wins" and the old one is automatically disconnected. - XMPP can also have this behaviour if the user chooses the same - resource in two clients (it is server-dependent whether the result is - AlreadyConnected on the new connection, ConnectionReplaced on the - old connection, or two successful connections). - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Registration Exists"> - <tp:docstring> - Raised during in-band registration if the server indicates that the - requested account already exists. - </tp:docstring> - </tp:error> - - <tp:error name="Service Busy"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Raised if a server or some other piece of infrastructure cannot process - the request, e.g. due to resource limitations. Clients MAY try again - later. - - <tp:rationale> - This is not the same error as Busy, which indicates that a - <em>user</em> is busy. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Resource Unavailable"> - <tp:docstring> - Raised if a request cannot be satisfied because a process local to the - user has insufficient resources. Clients MAY try again - later. - - <tp:rationale> - For instance, the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> - might raise this error for some or all channel requests if it has - detected that there is not enough free memory. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Would Break Anonymity"> - <tp:added version="0.19.7"/> - <tp:docstring> - Raised if a request cannot be satisfied without violating an earlier - request for anonymity, and the earlier request specified that raising - an error is preferable to disclosing the user's identity (for instance - via <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref> or - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref>). - </tp:docstring> - </tp:error> - - <tp:error name="Not Yet"> - <tp:added version="0.19.12"/> - <tp:docstring> - Raised when the requested functionality is not yet available, but is - likely to become available after some time has passed. - </tp:docstring> - </tp:error> - - <tp:error name="Rejected"> - <tp:added version="0.21.2"/> - <tp:docstring> - Raised when an incoming or outgoing <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is - rejected by the the receiver. - </tp:docstring> - </tp:error> - - <tp:error name="Picked Up Elsewhere"> - <tp:added version="0.21.3"/> - <tp:docstring> - Raised when a call was terminated as a result of the local user - picking up the call on a different resource. - </tp:docstring> - </tp:error> - - <tp:error name="Service Confused"> - <tp:added version="0.21.5"/> - <tp:docstring> - Raised when a server or other piece of infrastructure indicates an - internal error, or when a message that makes no sense is received from - a server or other piece of infrastructure. - - <tp:rationale> - For instance, this is appropriate for XMPP's - <code>internal-server-error</code>, and is also appropriate if - you receive sufficiently inconsistent information from a server that - you cannot continue. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Confused"> - <tp:added version="0.21.5"/> - <tp:docstring> - Raised if a server rejects protocol messages from a connection manager - claiming that they do not make sense, two local processes fail to - understand each other, or an apparently impossible situation is - reached. - - <tp:rationale> - For instance, this would be an appropriate mapping for XMPP's - errors bad-format, invalid-xml, etc., which can't happen unless - the local (or remote) XMPP implementation is faulty. This is - also analogous to - <tp:type>Media_Stream_Error</tp:type>_Invalid_CM_Behavior, - <code>TP_DBUS_ERROR_INCONSISTENT</code> in telepathy-glib, and - <code>TELEPATHY_QT4_ERROR_INCONSISTENT</code> in telepathy-qt4. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Software Upgrade Required"> - <tp:added version="0.21.12"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Raised as a - <tp:dbus-ref namespace="ofdT.Connection">ConnectionError</tp:dbus-ref> - when a Connection cannot be established because either the Connection - Manager or its support library (e.g. wocky, papyon, sofiasip) requires - upgrading to support a newer protocol version.</p> - - <p>This error corresponds to the - <tp:type>Connection_Status_Reason</tp:type> of Network_Error.</p> - - <tp:rationale> - Some protocols transmit a protocol or library version number to the - server, which will disconnect them if the version isn't appropriate. - This way we can report the error to the user, and if appropriate, the - user's client can check for updates. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:error name="Emergency Calls Not Supported"> - <tp:added version="0.21.12"/> - <tp:docstring> - Raised if a client attempts to dial a number that is recognized as an - emergency number (e.g. '911' in the USA), but the Connection Manager or - provider does not support dialling emergency numbers. - - <tp:rationale> - Many VOIP providers have the ability to dial traditional (PSTN) - telephone numbers, but do not provide the ability to dial emergency - numbers (for instance, Google Voice). This error provides additional - information about why such a call was unsuccessful. - </tp:rationale> - </tp:docstring> - </tp:error> - - <tp:copyright>Copyright © 2005-2010 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 -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> -</tp:errors> diff --git a/qt4/spec/generic-types.xml b/qt4/spec/generic-types.xml deleted file mode 100644 index 014f8ada4..000000000 --- a/qt4/spec/generic-types.xml +++ /dev/null @@ -1,215 +0,0 @@ -<tp:generic-types - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:simple-type name="Unix_Timestamp" type="u"> - <tp:docstring>An unsigned 32-bit integer representing time as the number - of seconds elapsed since the Unix epoch - (1970-01-01T00:00:00Z)</tp:docstring> - </tp:simple-type> - - <tp:simple-type name="Unix_Timestamp64" type="x"> - <tp:docstring>An signed 64-bit integer representing time as the number - of seconds elapsed since the Unix epoch - (1970-01-01T00:00:00Z); negative for times before the epoch</tp:docstring> - - <tp:rationale>The Text interface is the only user of Unix_Timestamp so - far, and we'd like to be Y2038 compatible in future - interfaces.</tp:rationale> - </tp:simple-type> - - <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" - 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" - 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" - 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 - a digit. The maximum total length is 255 characters. For example, - "org.freedesktop.DBus.Peer".</tp:docstring> - </tp:simple-type> - - <tp:simple-type name="DBus_Error_Name" type="s"> - <tp:docstring>An ASCII string representing a D-Bus error. This is - syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the - meaning is different.</tp:docstring> - </tp:simple-type> - - <tp:simple-type name="DBus_Signature" type="s"> - <tp:docstring>A string representing a D-Bus signature - (the 'g' type isn't used because of poor interoperability, particularly - with dbus-glib)</tp:docstring> - </tp:simple-type> - - <tp:simple-type name="DBus_Member" type="s"> - <tp:docstring>An ASCII string representing a D-Bus method, signal - or property name - a non-empty string of ASCII letters, digits and - underscores, not starting with a digit, with a maximum length of 255 - characters. For example, "Ping".</tp:docstring> - </tp:simple-type> - - <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, - "org.freedesktop.DBus.Peer.Ping".</tp:docstring> - </tp:simple-type> - - <tp:mapping name="Qualified_Property_Value_Map" - array-name="Qualified_Property_Value_Map_List"> - <tp:docstring>A mapping from strings representing D-Bus - properties (by their namespaced names) to their values.</tp:docstring> - <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> - <tp:docstring> - A D-Bus interface name, followed by a dot and a D-Bus property name. - </tp:docstring> - </tp:member> - <tp:member type="v" name="Value"> - <tp:docstring> - The value of the property. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:mapping name="String_Variant_Map" array-name="String_Variant_Map_List"> - <tp:docstring>A mapping from strings to variants representing extra - key-value pairs.</tp:docstring> - <tp:member type="s" name="Key"/> - <tp:member type="v" name="Value"/> - </tp:mapping> - - <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:simple-type name="User_Action_Timestamp" type="x"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The time at which an user action occurred. This type has the 2 - following special values:</p> - - <p>0: the action doesn't involve any user action. Clients - SHOULD avoid stealing focus when presenting the channel.</p> - - <p>MAX_INT64: clients SHOULD behave as though the user action happened - at the current time, e.g. a client MAY request that its window gains - focus. - </p> - - <tp:rationale> - <p>This can be used by clients that can't know the X server time like - command line applications for example.</p> - </tp:rationale> - - <p>For all the other values it corresponds to the time of the user - action. Clients SHOULD use this for focus-stealing prevention, - if applicable. - Note that the time is dependant on the local - environment and so is not necessarily a wall-clock time. - For example in an X environment it's expected to be the X timestamp - of events. - This corresponds to the _NET_WM_USER_TIME property in - <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> - </tp:docstring> - </tp:simple-type> - - <tp:mapping name="Object_Immutable_Properties_Map" - array-name="Object_Immutable_Properties_Map_List"> - <tp:added version="0.19.12"/> - <tp:docstring>A mapping from object path to the immutable properties of - the object.</tp:docstring> - <tp:member type="o" name="Path"> - <tp:docstring> - The object path of an object - </tp:docstring> - </tp:member> - <tp:member type="a{sv}" name="Immutable_Properties" tp:type="Qualified_Property_Value_Map"> - <tp:docstring> - The immutable properties of the object - </tp:docstring> - </tp:member> - </tp:mapping> - -</tp:generic-types> diff --git a/qt4/spec/template.xml b/qt4/spec/template.xml deleted file mode 100644 index 726472070..000000000 --- a/qt4/spec/template.xml +++ /dev/null @@ -1,33 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Foo" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Foo.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.UNRELEASED">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Foo.</p> - </tp:docstring> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/tests/lib/glib/future/extensions/all.xml b/qt4/tests/lib/glib/future/extensions/all.xml index 53cedc54a..81413a893 100644 --- a/qt4/tests/lib/glib/future/extensions/all.xml +++ b/qt4/tests/lib/glib/future/extensions/all.xml @@ -6,6 +6,6 @@ <xi:include href="channel.xml"/> <xi:include href="misc.xml"/> -<xi:include href="../../../../../spec/generic-types.xml"/> +<xi:include href="../../../../../../spec/spec/generic-types.xml"/> </tp:spec> diff --git a/qt4/tests/lib/glib/future/extensions/channel.xml b/qt4/tests/lib/glib/future/extensions/channel.xml index 71ec39e8b..e9984c5ad 100644 --- a/qt4/tests/lib/glib/future/extensions/channel.xml +++ b/qt4/tests/lib/glib/future/extensions/channel.xml @@ -4,9 +4,9 @@ <tp:title>Channel extensions from the future</tp:title> -<xi:include href="../../../../../spec/Channel_Interface_Mergeable_Conference.xml"/> -<xi:include href="../../../../../spec/Channel_Interface_Splittable.xml"/> +<xi:include href="../../../../../../spec/spec/Channel_Interface_Mergeable_Conference.xml"/> +<xi:include href="../../../../../../spec/spec/Channel_Interface_Splittable.xml"/> -<xi:include href="../../../../../spec/Channel_Type_Call.xml"/> +<xi:include href="../../../../../../spec/spec/Channel_Type_Call.xml"/> </tp:spec> diff --git a/qt4/tests/lib/glib/future/extensions/misc.xml b/qt4/tests/lib/glib/future/extensions/misc.xml index 061b4d405..48256213a 100644 --- a/qt4/tests/lib/glib/future/extensions/misc.xml +++ b/qt4/tests/lib/glib/future/extensions/misc.xml @@ -4,11 +4,10 @@ <tp:title>Miscellaneous extensions from the future</tp:title> -<xi:include href="../../../../../spec/Call_Content.xml"/> -<xi:include href="../../../../../spec/Call_Content_Codec_Offer.xml"/> -<xi:include href="../../../../../spec/Call_Content_Interface_Media.xml"/> -<xi:include href="../../../../../spec/Call_Stream_Endpoint.xml"/> -<xi:include href="../../../../../spec/Call_Stream_Interface_Media.xml"/> -<xi:include href="../../../../../spec/Call_Stream.xml"/> +<xi:include href="../../../../../../spec/spec/Call_Content.xml"/> +<xi:include href="../../../../../../spec/spec/Call_Content_Interface_Media.xml"/> +<xi:include href="../../../../../../spec/spec/Call_Stream_Endpoint.xml"/> +<xi:include href="../../../../../../spec/spec/Call_Stream_Interface_Media.xml"/> +<xi:include href="../../../../../../spec/spec/Call_Stream.xml"/> </tp:spec> |