diff options
author | Olli Salli <olli.salli@collabora.co.uk> | 2008-07-11 01:29:49 +0300 |
---|---|---|
committer | Olli Salli <olli.salli@collabora.co.uk> | 2008-07-11 01:29:49 +0300 |
commit | 01c664197ea60be00a257311e89ba14f91f7b1c6 (patch) | |
tree | a903175aab3cfff852f0e93bae2a0570c2b8fbd3 /qt4/spec |
Initial commit with types and constants generated.
Diffstat (limited to 'qt4/spec')
41 files changed, 9220 insertions, 0 deletions
diff --git a/qt4/spec/Account.xml b/qt4/spec/Account.xml new file mode 100644 index 000000000..5521f5ccc --- /dev/null +++ b/qt4/spec/Account.xml @@ -0,0 +1,475 @@ +<?xml version="1.0" ?> +<node name="/Account" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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 + ConnectionManager.ListProtocols, but with "-" replaced with "_" + (i.e. the same as in the object-path of a Connection)</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" type="as" access="read"> + <tp:docstring> + A list of the extra interfaces provided by this account. + </tp:docstring> + </property> + + <method name="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:docstring> + This account has been removed. + + <tp:rationale> + This is redundant with AccountRemoved, 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: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. Nickname) 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: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:rationale> + This approximately corresponds to "display name" in NMC 4.x and + Decibel. + </tp:rationale> + </tp:docstring> + </property> + + <property name="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:rationale> + This approximately corresponds to mc_profile_get_icon_name + (or possibly mc_profile_get_branding_icon_name) in NMC 4.x. + It's accessed via the account rather than the profile because + we no longer have profiles as a core concept. + </tp:rationale> + </tp:docstring> + </property> + + <property name="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" 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> + + <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:rationale> + </tp:docstring> + </property> + + <property name="Nickname" type="as" 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 SetAliases + 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. + This corresponds to NMC 4.x mc_account_get_alias. + </tp:rationale> + </tp:docstring> + </property> + + <property name="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 + ConnectionManager 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 Set() - use + UpdateParameters instead.</p> + + <tp:rationale> + This avoids NMC being tied to gconf as a matter of API. + </tp:rationale> + </tp:docstring> + </property> + + <method name="UpdateParameters"> + <tp:docstring> + Change the value of the Parameters property. Any changes will not + take effect until the next time the account is disconnected and + reconnected. + + <tp:rationale> + Migration tools that twiddle the settings of all accounts shouldn't + cause an automatic disconnect and reconnect, probably. I could be + persuaded otherwise, though. Or we could add a Reconnect() method. + </tp:rationale> + </tp:docstring> + + <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> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + + <tp:struct name="Account_Presence"> + <tp:docstring> + A simplified form of the presence statuses seen in the Presence + interface. + </tp:docstring> + + <tp:member name="Type" type="u" tp:type="Connection_Presence_Type"> + <tp:docstring> + The presence type, e.g. Connection_Presence_Type_Away. + </tp:docstring> + </tp:member> + + <tp:member name="Status" type="s"> + <tp:docstring> + The connection-manager-specific string identifier of the presence + status, e.g. "brb". + </tp:docstring> + </tp:member> + + <tp:member name="Message" type="s"> + <tp:docstring> + The user-defined status message, e.g. "Back soon!". This will be + used as the value for the 'message' keyword in the Presence + interface's dictionary, if possible. + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="AutomaticPresence" type="(uss)" access="readwrite" + tp:type="Account_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> + + <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 <tp:type>Connection_Presence_Type</tp:type> in the structure + SHOULD NOT be Offline or Unset.</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> + </tp:docstring> + </property> + + <property name="ConnectAutomatically" type="b" access="readwrite"> + <tp:docstring> + If true, the account manager SHOULD attempt to put this account + online with the AutomaticPresence 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 AutomaticPresence if requested by the user (for + instance, if the user tries to start a conversation using this + account). + + <tp:rationale> + This approximately corresponds to NMC 4.x "enabled" and Decibel + "autoreconnect". + </tp:rationale> + </tp:docstring> + </property> + + <property name="Connection" type="s" access="read"> + <tp:docstring> + Either the well-known bus name of the connection to this account, + or the empty string if there is no connection. + </tp:docstring> + </property> + + <property name="ConnectionStatus" type="u" access="read"> + <tp:docstring> + If the Connection 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. This vaguely corresponds to + GetCurrentStatus in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionStatusReason" type="u" access="read"> + <tp:docstring> + The reason for the last change to ConnectionStatus. + 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. This is part + of GetCurrentStatus in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="CurrentPresence" type="(uss)" access="read" + tp:type="Account_Presence"> + <tp:docstring> + The actual presence. If the connection is not online, this should be + (Connection_Presence_Type_Offline, "", ""). + If the connection is online but does not support the Presence + interface, this should be (Connection_Presence_Type_Unset, "", ""). + The account manager is expected to set this by observing signals + from the Connection. + + <tp:rationale> + This corresponds to GetPresenceActual in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RequestedPresence" type="(uss)" access="readwrite" + tp:type="Account_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 CurrentPresence match RequestedPresence 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 AutomaticPresence.</p> + + <tp:rationale> + This corresponds to e.g. GetPresence and GetPresenceMessage + in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="NormalizedName" type="s" access="read"> + <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 InspectHandle method is called on the + result of GetSelfHandle() 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> + + </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 new file mode 100644 index 000000000..cb58256e2 --- /dev/null +++ b/qt4/spec/Account_Interface_Avatar.xml @@ -0,0 +1,65 @@ +<?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: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"/> + + <property name="Avatar" type="(ays)" 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:rationale> + This corresponds to NMC 4.x mc_account_get_avatar. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="AvatarChanged"> + <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_Manager.xml b/qt4/spec/Account_Manager.xml new file mode 100644 index 000000000..a068da37c --- /dev/null +++ b/qt4/spec/Account_Manager.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" ?> +<node name="/Account_Manager" + 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.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> + </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" type="as" 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:docstring> + A list of the valid (complete, usable) accounts. Change notification + is via AccountValidityChanged. + + <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:docstring> + A list of incomplete or otherwise unusable accounts. Change + notification is via AccountValidityChanged. + </tp:docstring> + </property> + + <signal name="AccountRemoved"> + <tp:docstring> + The given account has been removed. + + <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 Account, which must not be used any more. + </tp:docstring> + </arg> + </signal> + + <signal name="AccountValidityChanged"> + <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 Account. + </tp:docstring> + </arg> + + <arg name="Valid" type="b"> + <tp:docstring> + True if the account is now valid. + </tp:docstring> + </arg> + </signal> + + <method name="CreateAccount"> + <tp:docstring> + Request the creation of a new account. The account manager SHOULD NOT + allow invalid accounts to be created. Accounts created through this + API SHOULD have an empty PresetParameters property. + </tp:docstring> + + <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 DisplayName + property. The account manager MAY modify this to make it unique, + for instance by appending a number or the 'account' + parameter.</tp:docstring> + </arg> + + <arg name="Parameters" direction="in" type="a{sv}"> + <tp:docstring>Initial parameter values, as would be passed to + RequestConnection.</tp:docstring> + </arg> + + <arg name="Account" direction="out" type="o"> + <tp:docstring>The new account.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring>The connection manager is not installed or does not + implement that protocol.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring>The parameters provided omit a required argument + or provide unsupported arguments. + </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.xml b/qt4/spec/Channel.xml new file mode 100644 index 000000000..61da13412 --- /dev/null +++ b/qt4/spec/Channel.xml @@ -0,0 +1,238 @@ +<?xml version="1.0" ?> +<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <tp: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: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 GetChannelType.</p> + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip, which is desirable. + </tp:rationale> + </tp:docstring> + </property> + + <property name="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 + ChannelType is an empty string, clients MUST use the result of + calling GetInterfaces 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> + </tp:docstring> + </property> + + <property name="TargetHandle" type="u" access="read" tp:type="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 TargetHandleType property.</p> + + <p>This is fixed for the lifetime of the channel, so channels which + could potentially be used to communicate with multiple contacts + (such as streamed media calls defined by their members, or ad-hoc + chatrooms like MSN switchboards) 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> + </tp:docstring> + </property> + + <property name="TargetHandleType" type="u" access="read" + tp:type="Handle_Type"> + <tp:added version="0.17.7"/> + <tp:docstring> + The type of TargetHandle. + </tp:docstring> + </property> + + <method name="Close"> + <tp:docstring> + Request that the channel be closed. This is not the case until + the Closed 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: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:deprecated version="0.17.7">Use the ChannelType + property if possible.</tp:deprecated> + <arg direction="out" type="s" tp:type="DBus_Interface"> + <tp:docstring>The interface name</tp:docstring> + </arg> + <tp:docstring> + Returns the interface name for the type of this channel. + Clients SHOULD use the ChannelType 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:deprecated version="0.17.7">Use the TargetHandleType + and TargetHandle properties if possible.</tp:deprecated> + <arg direction="out" type="u" tp:type="Handle_Type"> + <tp:docstring> + The same as TargetHandleType. + </tp:docstring> + </arg> + <arg direction="out" type="u" tp:type="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 TargetHandle and TargetHandleType 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:deprecated version="0.17.7">Use the Interfaces + property if possible.</tp:deprecated> + <arg direction="out" type="as" tp:type="DBus_Interface[]"> + <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 Interfaces 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> + + <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 Channel.Type.ContactList which represents a list of people (such + as a buddy list) or a Channel.Type.Text which represents a channel over + which textual messages are sent and received.</p> + + <p>Each channel may have an immutable handle associated with it, which + may be any handle type, such as a contact, room or list handle, + indicating that the channel is for communicating with that handle.</p> + + <p>If a channel does not have a handle (an "anonymous channel" with + Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it + means that the channel is defined by some other terms, such as it + may be a transient group defined only by its members as visible + through the Channel.Interface.Group interface.</p> + + <p>Other optional interfaces can be implemented to indicate other available + functionality, such as Channel.Interface.Group if the channel contains + a number of contacts, Channel.Interface.Password to indicate + that a channel may have a password set to require entry, and + Properties for extra data about channels which represent chat + rooms or voice calls. The interfaces implemented may not vary after the + channel's creation has been signalled to the bus (with the connection's + NewChannel signal).</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> + </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 new file mode 100644 index 000000000..09d116ff6 --- /dev/null +++ b/qt4/spec/Channel_Future.xml @@ -0,0 +1,122 @@ +<?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 Channel 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="TargetID" type="s" access="read"> + <tp:added version="0.17.7">(in Channel.FUTURE + pseudo-interface)</tp:added> + <tp:docstring> + The string that would result from inspecting the TargetHandle + property (i.e. the identifier in the IM protocol of the contact, + room, etc. with which this channel communicates). + + <tp:rationale> + See InitiatorID; the rationale is the same. + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitiatorHandle" type="u" tp:type="Contact_Handle" + access="read"> + <tp:added version="0.17.7">(in Channel.FUTURE + pseudo-interface)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact who initiated the channel. For channels requested by the + local user, this MUST be the same thing as would be returned + by Connection.GetSelfHandle() at the time the channel was + created.</p> + + <tp:rationale> + <p>The careful wording about the self-handle is because the Renaming + interface can cause the return from Connection.GetSelfHandle to + change. It's something of a specification bug that we don't signal + this in the Connection interface yet.</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 Group 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 passed to the + RequestChannels method on Channel.Interface.Requests.</p> + </tp:docstring> + </property> + + <property name="InitiatorID" type="s" access="read"> + <tp:added version="0.17.7">(in Channel.FUTURE + pseudo-interface)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string that would result from inspecting the InitiatorHandle + 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 InspectHandles(CONTACT, [I])</li> + <li>Channel C closes, removing the last reference to handle I</li> + <li>InspectHandles(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 passed to the + RequestChannels method on Channel.Interface.Requests.</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 new file mode 100644 index 000000000..06b14e80e --- /dev/null +++ b/qt4/spec/Channel_Handler.xml @@ -0,0 +1,73 @@ +<?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:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface exported by client applications which are able to + handle incoming channels.</p> + </tp:docstring> + <tp:added version="0.17.0"/> + + <method name="HandleChannel"> + <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_Call_Merging.xml b/qt4/spec/Channel_Interface_Call_Merging.xml new file mode 100644 index 000000000..23f955859 --- /dev/null +++ b/qt4/spec/Channel_Interface_Call_Merging.xml @@ -0,0 +1,80 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Call_Merging" 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 +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.CallMerging" + tp:causes-havoc='not yet API-stable'> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:added version="0.17.1"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for streamed media channels that can be merged and split + in the same sort of way as in GSM or PBX telephony.</p> + </tp:docstring> + + <method name="Merge"> + <arg direction="in" type="o" name="Other"> + <tp:docstring> + The other channel to merge into this one + </tp:docstring> + </arg> + <tp:docstring> + Request that the given channel be merged into this one. This means + that the other channel is closed, and all its participants are added + to the channel on which this method was called. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <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:possible-errors> + </method> + + <method name="Split"> + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the contact to split off a conversation with, who + must be a member in the channel's Group interface + </tp:docstring> + </arg> + <arg direction="out" name="Channel" type="o"> + <tp:docstring> + The new channel + </tp:docstring> + </arg> + <tp:docstring> + Request that the given contact is removed from this channel, and + a new channel is created to communicate with them privately instead. + This is the inverse of Merge. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <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:possible-errors> + </method> + + </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 new file mode 100644 index 000000000..aead16bb1 --- /dev/null +++ b/qt4/spec/Channel_Interface_Call_State.xml @@ -0,0 +1,108 @@ +<?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> + An interface for streamed media channels that can indicate call + progress or call states. The presence of this interface is no guarantee + that call states will actually be signalled (for instance, SIP + implementations are not guaranteed to generate status 180 Ringing, + so a call can be accepted without the Ringing flag ever having been set). + </tp:docstring> + <tp:added version="0.17.2"/> + + <method name="GetCallStates"> + <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: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: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 new file mode 100644 index 000000000..9cc6883d3 --- /dev/null +++ b/qt4/spec/Channel_Interface_Chat_State.xml @@ -0,0 +1,100 @@ +<?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"/> + <method name="SetChatState"> + <arg direction="in" name="state" type="u" tp:type="Channel_Chat_State"> + <tp:docstring> + The new state: one of the values of ChannelChatState. + </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"> + <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: one of the values of ChannelChatState. + </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> + <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_DTMF.xml b/qt4/spec/Channel_Interface_DTMF.xml new file mode 100644 index 000000000..c24ec1100 --- /dev/null +++ b/qt4/spec/Channel_Interface_DTMF.xml @@ -0,0 +1,137 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_DTMF" 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.DTMF"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <method name="StartTone"> + <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID"> + <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</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> + Start sending a DTMF tone on this stream. Where possible, the tone + will continue until StopTone 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. + </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. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested event is not available on this stream. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StopTone"> + <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID"> + <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> + </arg> + <tp:docstring> + Stop sending any DTMF tone which has been started using the StartTone + method. If there is no current tone, this method will do nothing. + </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. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Continuous tones are not supported by this stream. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <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> + + <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 DTMF_Event enumeration. + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Delivery_Reporting.xml b/qt4/spec/Channel_Interface_Delivery_Reporting.xml new file mode 100644 index 000000000..29b0f769b --- /dev/null +++ b/qt4/spec/Channel_Interface_Delivery_Reporting.xml @@ -0,0 +1,442 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Delivery_Reporting" + 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.DeliveryReporting.DRAFT" + tp:causes-havoc="experimental"> + <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 Text and Messages interfaces with improved + sent-message status reporting.</p> + + <p>This interface replaces Text.SendError, adding support for protocols + where the message content is not echoed back to the sender on + failure. It also adds support for receiving positive + acknowledgements, and uses the Messages queue for state-recovery + (ensuring that incoming delivery reports are not lost if there is not + currently a process handling them).</p> + + <p>If this interface and the Messages interface are both present, + clients that support it SHOULD listen for the MessageReceived signal + to get delivery reports, and ignore the SendError signal on the Text + interface.</p> + + <p>Delivery reports appear as messages of type + Channel_Text_Message_Type_Delivery_Report in the Text and Messages + interfaces. The message in the Text interface SHOULD have the + Non_Text_Content flag.</p> + + <p>Whenever a message of type Channel_Text_Message_Type_Delivery_Report + is signalled for a delivery error report, Channel.Type.Text.SendError + SHOULD also be emitted; whenever Channel.Type.Text.SendError is + emitted by a channel which supports this interface, a message of type + Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p> + + <p>The corresponding message in the Messages interface MUST contain + "headers" for the delivery report, as specified below, in its + first Message_Part.</p> + + <dl> + <dt>interface (s - DBus_Interface, as defined in the Messages + interface)</dt> + <dd>MUST be the name of this interface.</dd> + + <dt>message-sender (u - Contact_Handle, as defined in the Messages + interface)</dt> + <dd>MUST be the intended recipient of the original message, if + available (zero or omitted otherwise), even if the delivery report + actually came from an intermediate server.</dd> + + <dt>message-type (u - Channel_Text_Message_Type, as defined in the + Messages interface)</dt> + <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd> + + <dt>delivery-status (u - Delivery_Status)</dt> + <dd>The status of the message. All delivery reports MUST contain + this key in the first Message_Part.</dd> + + <dt>delivery-token (s - Sent_Message_Token)</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 on the Messages + interface. 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 - Channel_Text_Send_Error)</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-echo (aa{sv} - Message_Part[])</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> + + <p>Unlike in the Messages interface, content not visible + in the value for this key cannot be retrieved by another + means, so the connection manager SHOULD be more + aggressive about including (possibly truncated) message + content in the 'content' key.</p> + + <tp:rationale> + The Messages interface needs to allow all content to be + retrieved, but in this interface, the content we provide is + merely a hint; so some is better than none, and it doesn't + seem worth providing an API as complex as Messages' + GetPendingMessageContent for the echoed message. + </tp:rationale> + </dd> + + </dl> + + <p>The second and subsequent Message_Part dictionaries, if present, + are a human-readable report from the IM service.</p> + + <p>It is an error for this interface to appear on channels of type + other than Text, or on Text channels without the Messages interface. + Clients MUST recover from this error by ignoring the presence + of the DeliveryReporting interface.</p> + + <p>Some example delivery reports in a Python-like syntax (in which + arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) + follow.</p> + + <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 +'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting', +'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 +'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting', +'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 + '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 +'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting', +'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 + 'type': 'text/plain', + 'content': 'Hello, world!', + }] + ], +}, +{ # message from server (alternative in English) +'alternative': '404', +'type': 'text/plain', +'lang': 'en', +'content': 'I have no contact with that name', +}, +{ # message from server (alternative in German) +'alternative': '404'. +'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 +'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting', +'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> + </tp:docstring> + + <tp:enum name="Delivery_Status" value-prefix="Delivery_Status"> + <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 keys in the Message_Part.</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:enum> + + <tp:flags name="Delivery_Reporting_Support_Flags" + value-prefix="Delivery_Reporting_Support_Flag"> + <tp:docstring> + Flags indicating the level of support for delivery reporting on this + channel. 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. + </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: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> + + <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:rationale> + Same rationale as Receive_Failures. + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Send_Failures" value="4"> + <tp:docstring> + Clients MAY expect that sending a negative delivery report will + succeed, and will actually get a message to the sender. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Send_Successes" value="8"> + <tp:docstring> + Clients MAY expect that sending a positive delivery report will + succeed, and will actually get a message to the sender. + </tp:docstring> + </tp:flag> + + </tp:flags> + + <property name="DeliveryReportingSupport" access="read" + tp:type="Delivery_Reporting_Support_Flags" type="u"> + <tp:docstring> + A bitfield indicating features supported by this channel. + </tp:docstring> + </property> + + <method name="SendDeliveryReport"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that a delivery report is sent for the specified pending + incoming message. Delivery reports cannot currently be sent for + messages that have already been acknowledged.</p> + + <tp:rationale> + <p>The only use-case I can see for delivery reports on non-pending + messages is a "read receipt" like in email's RFC 3798. Delivery + reports on non-pending messages will also need a more complex + API.</p> + + <p>If they turn out to be needed, we can add a method like + SendDeliveryReportByContent(aa{sv}: message) and add a flag to + Delivery_Reporting_Support_Flags indicating that this method is + implemented.</p> + </tp:rationale> + + <p>Clients SHOULD NOT attempt to send delivery reports that are + not indicated to be supported using the DeliveryReportingSupport + property.</p> + + <p>Clients MUST NOT attempt to send delivery reports using the + SendMessage method in the Messages API, and connection managers + MUST NOT allow this to be done.</p> + </tp:docstring> + + <arg name="Messages" type="au" tp:type="Message_ID[]" direction="in"> + <tp:docstring> + The IDs of one or more unacknowledged messages. + </tp:docstring> + </arg> + + <arg name="Status" direction="in" type="u" tp:type="Delivery_Status"> + <tp:docstring> + The status to be reported. + </tp:docstring> + </arg> + + <arg name="Reason" direction="in" type="u" + tp:type="Channel_Text_Send_Error"> + <tp:docstring> + If the status to be reported is a failure, the reason for that + failure. If the status to be reported is not an error, this MUST be + Channel_Text_Send_Error_Unknown. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + One of the specified message IDs was invalid. No delivery reports + were sent. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested message status could not be reported to the sender + (for instance, this will be raised if a positive delivery report + is requested on a protocol that only supports negative delivery + reports). Clients MUST treat this error as non-fatal. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + This channel cannot report message status back to the sender + at all. Do not call this method on this channel again. + </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_Group.xml b/qt4/spec/Channel_Interface_Group.xml new file mode 100644 index 000000000..cab68c5cd --- /dev/null +++ b/qt4/spec/Channel_Interface_Group.xml @@ -0,0 +1,777 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Group" 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.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 + AddMembers.</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"> + <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 flags 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.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: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 GetLocalPendingMembers if necessary.</tp:deprecated> + + <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + array of handles of current members + </tp:docstring> + </arg> + <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + array of handles of local pending members + </tp:docstring> + </arg> + <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <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 AddMembers 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 RemoveMembers 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 RemoveMembers 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 AddMembers 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 RemoveMembers 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 AddMembers 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 RemoveMembers 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 RemoveMembers 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 + call GetHandleOwners to find the owners of these handles, which + should be done if you wish to eg 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 SelfHandle. + + <tp:rationale> + This used to be an important optimization to avoid repeated + GetHandleOwners calls, before we introduced the HandleOwner + property and HandleOwnerChanged 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:flags> + + <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags" + access="read"> + <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 GroupFlagsChanged 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"> + <arg direction="out" type="u" tp:type="Channel_Group_Flags"> + <tp:docstring> + The value of the GroupFlags property + </tp:docstring> + </arg> + <tp:docstring> + Returns the value of the GroupFlags 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: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 HandleOwnersChanged signal. + </tp:docstring> + <tp:added version="0.17.6"/> + </property> + + <signal name="HandleOwnersChanged"> + <tp:docstring> + Emitted whenever the HandleOwners 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 MembersChanged signal + </tp:docstring> + </arg> + </signal> + + <method name="GetHandleOwners"> + <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[]"> + <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"> + <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <tp:docstring> + Returns the To_Be_Added handle (only) for each structure in the + LocalPendingMembers 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:added version="0.15.0" /> + <tp:docstring> + Returns the LocalPendingMembers 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[]"> + <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 + ChannelGroupChangeReason + </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:docstring> + An array of structs containing handles representing contacts + requesting channel membership and awaiting local approval with + AddMembers. + </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" 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"> + <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <tp:docstring> + Returns the Members 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: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"> + <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <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 RemotePendingMembers + 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:docstring> + Emitted whenever the SelfHandle 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: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 ContactList + channels). Note that this is different from the connection + GetSelfHandle 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"> + <arg direction="out" type="u" tp:type="Contact_Handle"/> + <tp:docstring> + Returns the value of the SelfHandle 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"> + <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 GetGroupFlags are changed. + The user interface should be updated as appropriate. + </tp:docstring> + </signal> + + <tp:enum name="Channel_Group_Change_Reason" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + No reason was provided for this change. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring> + The change is due to a user going offline. Also used when + user is already offline, but this wasn't known previously. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Kicked" value="2"> + <tp:docstring> + The change is due to a kick operation. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Busy" value="3"> + <tp:docstring> + The change is due to a busy indication. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invited" value="4"> + <tp:docstring> + The change is due to an invitation. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Banned" value="5"> + <tp:docstring> + The change is due to a kick+ban operation. + </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> + The change is because the requested contact does not exist. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="No_Answer" value="8"> + <tp:docstring> + The change is because the requested contact did not respond. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Renamed" value="9"> + <tp:docstring> + 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 Renamed signal on the + Renaming interface will have been emitted for the same handles, + shortly before this MembersChanged signal is emitted. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Permission_Denied" value="10"> + <tp:docstring> + The change is because there was no permission to contact the + requested handle. + </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. Text or Tubes 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> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="MembersChanged"> + <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: one of the values of + ChannelGroupChangeReason + </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 HandleOwners property. + In practice, this will mean that HandleOwnersChanged 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> + </tp:docstring> + </signal> + + <method name="RemoveMembers"> + <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> + Requests the removal of contacts from a channel, reject their request + for channel membership on the pending local list, or rescind their + invitation on the pending remote list. A message may be provided along + with the request, which will be sent to the server if supported. See + the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE, + CHANNEL_GROUP_FLAG_MESSAGE_REJECT and + CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this + message should be provided. + </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"> + <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: one of the values of + ChannelGroupChangeReason + </tp:docstring> + </arg> + <tp:docstring> + As RemoveMembers, 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, and two + lists of local pending and remote pending members. 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 MembersChanged signal should be emitted when information + is retrieved from the server, or changes occur.</p> + + <p>Addition of members to the channel may be requested by using AddMembers. 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 + RemoveMembers. 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 new file mode 100644 index 000000000..ad86867ca --- /dev/null +++ b/qt4/spec/Channel_Interface_HTML.xml @@ -0,0 +1,86 @@ +<?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 new file mode 100644 index 000000000..6e64e3a63 --- /dev/null +++ b/qt4/spec/Channel_Interface_Hold.xml @@ -0,0 +1,217 @@ +<?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:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <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.</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: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: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 + RequestHold, or the state changing as a result of a request from + another process. + </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 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"> + <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 HoldStateChanged 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 new file mode 100644 index 000000000..cc7a7a956 --- /dev/null +++ b/qt4/spec/Channel_Interface_Media_Signalling.xml @@ -0,0 +1,117 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp: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: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"> + <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"/> + <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"> + <arg name="Session_Handler" type="o"> + <tp:docstring> + Object path of the new MediaSessionHandler 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:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string indicating the NAT traversal techniques employed by the + streams within this channel. Can be protocol-specific values, but the + following values should be used if appropriate:</p> + + <dl> + <dt>none</dt> + <dd>No attempt should be made at NAT traversal.</dd> + + <dt>stun</dt> + <dd>If appropriate, a STUN request should be made to the given server + to open a UDP port mapping and determine the external IP.</dd> + + <dt>gtalk-p2p</dt> + <dd>Google Talk peer-to-peer connectivity establishment should be used, + as implemented in libjingle 0.3.</dd> + </dl> + </tp:docstring> + </tp:property> + <tp:property name="stun-server" type="s"> + <tp:docstring> + The IP address or hostname of the STUN server to use for NAT traversal. + </tp:docstring> + </tp:property> + <tp:property name="stun-port" type="q"> + <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:docstring> + The authentication token for use with the Google Talk peer-to-peer relay + server. + </tp:docstring> + </tp:property> + + <tp:docstring> + An interface for signalling a channel containing synchronised media + sessions which can contain an arbitrary number of streams. The negotiation + interface is based closely around the API of the Farsight library + (http://farsight.sourceforge.net/). 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. + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Messages.xml b/qt4/spec/Channel_Interface_Messages.xml new file mode 100644 index 000000000..677ca09fe --- /dev/null +++ b/qt4/spec/Channel_Interface_Messages.xml @@ -0,0 +1,634 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Messages" + 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.Messages.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + <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 Text 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</li> + <li>any extra types of message we need in future</li> + </ul> + + <p>It also provides a hook for improved sent + message status notification, to be used by the DeliveryReporting + 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> + + <p>If this interface is present, clients that support it SHOULD + listen for the MessageSent and MessageReceived signals, and + ignore the Sent and Received signal on the Text interface + (which are guaranteed to duplicate signals from this interface).</p> + </tp:docstring> + + <property name="SupportedContentTypes" type="as" access="read"> + <tp:docstring> + 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. + If the list is empty, this indicates that messages may only include + a single "text/plain" part. + </tp:docstring> + </property> + + <property name="MessagePartSupportFlags" type="u" + tp:type="Message_Part_Support_Flags" + access="read"> + <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"> + <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>It is assumed that messages containing a textual message body + (only), like the messages the Text interface was designed for, are + always supported.</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 1, 2, 4 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> + </tp:docstring> + + <tp:flag suffix="Data_Only" value="1"> + <tp:docstring> + SendMessage will accept messages containing a single part of any + type listed in the SupportedContentTypes property, with no + accompanying text. + </tp:docstring> + </tp:flag> + <tp:flag suffix="One_Attachment" value="2"> + <tp:docstring> + SendMessage 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="4"> + <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"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Part of a message's content. In practice, this mapping never + appears in isolation - messages are represented by a list of + <tp:type>Message_Part</tp:type> mappings.</p> + + <p>An example of how a message might + look, in a Python-like syntax:</p> + + <pre> +[ + { + 'message-sender': 42, + 'message-sent': 1210067943, + 'message-received': 1210067947, + 'message-type': 0, + 'pending-message-id': 437, + }, + { 'alternative': 'main', + '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', + 'type': 'text/plain', + 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?', + }, + { 'identifier': 'catphoto', + 'type': 'image/jpeg', + 'size': 101000, + 'needs-retrieval': True, + }, +] + </pre> + + <div> + <p>The first part of the message contains "headers" which refer + to the entire message.</p> + + <p>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, but clients MUST recover from this error by ignoring + these keys in the second and subsequent parts.</p> + + <p>Well-known keys for the message as a whole, and the corresponding + value types, include:</p> + + <dl> + <!-- FIXME: if needed we could add: + <dt>message-identifier (s)</dt> + <dd>An opaque, globally-unique identifier for the entire message. + This MAY be treated as if it were a MIME Message-ID, e.g. for + the mid: and cid: URI schemes. If omitted, there is no suitable + identifier.</dd> + --> + + <dt>message-sent (u - <tp:type>Unix_Timestamp</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</dd> + + <dt>message-received (u - <tp:type>Unix_Timestamp</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-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. SHOULD + be omitted for normal chat messages.</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> + </dl> + </div> + + <div> + <p>The second and subsequent parts contain the message's + content, including plain text, formatted text and/or attached + files.</p> + + <p>In any group of parts with the same non-empty value for the + "alternative" 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 "multipart/alternative" parts). Clients SHOULD + display the first alternative that they understand.</p> + + <tp:rationale> + 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. + </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>Well-known keys for the second and subsequent parts, and the + corresponding value types, include:</p> + + <dl> + <dt>identifier (s)</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>type (s)</dt> + <dd> + <p>The MIME type of this part. See the documentation + for ReceivedMessage for notes on the special status of + "text/plain" parts.</p> + + <p>Connection managers MUST NOT signal parts without a '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 'type' key, which are + reserved for future expansion.</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>needs-retrieval (b)</dt> + <dd>If false or omitted, the connection + manager already holds this part in memory. If present and true, + this part will be retrieved on demand (like MIME's + message/external-body), so clients should expect retrieval to + take time; if this specification is later extended to provide a + streaming version of GetPendingMessageContent, clients should + use it for parts with this flag.</dd> + + <dt>truncated (b)</dt> + <dd>The content available via the 'content' key or + GetPendingMessageContent 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> + + <p>It is an error for a connection manager to put these keys + in the first <tp:type>Message_Part</tp:type>, but clients MUST be + able to recover from this error by ignoring these keys in the + first part.</p> + + </div> + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring> + A key, which SHOULD be one of the well-known keys specified, if + possible. + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring> + The value corresponding to the given key, which must be of one of + the types indicated. + </tp:docstring> + </tp:member> + </tp:mapping> + + + <tp:simple-type type="s" name="Sent_Message_Token"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An opaque token used to identify sent messages. 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, if possible.</p> + + <p>Some protocols can only track a limited number of sent messages + in a small message-ID space. As a result, clients MUST NOT assume + that message tokens will not be re-used, and SHOULD use some + reasonable 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:rationale> + <p>This is a hook for the DeliveryReporting interface, + to avoid having to introduce a + SendMultiPartMessageAndReturnToken method in that interface.</p> + </tp:rationale> + </tp:docstring> + </tp:simple-type> + + <method name="SendMessage"> + <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 MessageSent signal is emitted. A corresponding + Sent signal on the Text interface MUST also be emitted.</p> + + <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> + </tp:docstring> + + <arg direction="in" type="aa{sv}" tp:type="Message_Part[]" + name="Message"> + <tp:docstring> + The message content, including any attachments or alternatives + </tp:docstring> + </arg> + <arg direction="in" name="Flags" type="u" + tp:type="Message_Sending_Flags"> + <tp:docstring> + Flags affecting how the message is sent. + </tp:docstring> + </arg> + + <arg direction="out" type="s" tp:type="Sent_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> + + <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"> + <tp:docstring> + Flags altering the way a message is sent. The "most usual" action + should always be to have these flags unset. + </tp:docstring> + + <tp:flag suffix="Report_Delivery" value="1"> + <tp:docstring> + Provide a delivery report via the DeliveryReporting interface, if + possible, even if this is not the default for this protocol. + Ignored if delivery reports are not possible on this protocol. + + <tp:rationale> + In some protocols, like XMPP, it is not conventional to request + or send delivery notifications. + </tp:rationale> + </tp:docstring> + </tp:flag> + </tp:flags> + + <signal name="MessageSent"> + <tp:docstring> + Signals that a message has been submitted for sending. This + MUST be emitted exactly once per emission of the Sent signal on the + Text interface. + + <tp:rationale> + This signal allows a process that is not the caller of + SendMessage to log sent messages. The double signal-emission + means that clients can safely follow the following rule: + if the channel has the Messages interface, listen for + Messages.MessageSent only; otherwise, listen for Text.Sent only. + </tp:rationale> + </tp:docstring> + + <arg type="aa{sv}" tp:type="Message_Part[]" name="Content"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The message content (see <tp:type>Message_Part</tp:type> for full + details). If the message that was passed to SendMessage has a + formatted text part that the connection manager recognises, but no + text/plain alternative, the CM MUST use the formatted text part to + generate a text/plain alternative which is also included in this + signal argument. + </tp:docstring> + </arg> + + <arg name="Message_Token" type="s" tp:type="Sent_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:docstring> + A list of incoming messages that have neither been acknowledged nor + rejected. This list is a superset of the one returned by + ListPendingMessages on the Text interface; its items can be removed + using AcknowledgePendingMessages on that interface. + </tp:docstring> + </property> + + <signal name="PendingMessagesRemoved"> + <tp:docstring> + The messages with the given IDs have been removed from the + PendingMessages 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: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: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: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 '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: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 + Received signal on the Text interface. + + <tp:rationale> + The double signal-emission means that clients can safely follow + the following rule: if the channel has the Messages interface, + listen for Messages.MessageReceived only; otherwise, listen for + Text.Received only. + </tp:rationale> + </tp:docstring> + + <arg type="aa{sv}" tp:type="Message_Part[]" name="Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The message content, including any attachments or alternatives + </tp:docstring> + </arg> + </signal> + + </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 new file mode 100644 index 000000000..41a92ab0b --- /dev/null +++ b/qt4/spec/Channel_Interface_Password.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> +Copyright (C) 2005, 2006 Collabora Limited +Copyright (C) 2005, 2006 Nokia Corporation +Copyright (C) 2006 INdT + </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 ProvidePassword method must be called now for the user to join + the channel + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="GetPasswordFlags"> + <arg direction="out" type="u" tp:type="Channel_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"> + <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 GetPasswordFlags are changed. + The user interface should be updated as appropriate. + </tp:docstring> + </signal> + <method name="ProvidePassword"> + <arg direction="in" name="password" type="s"> + <tp:docstring> + The password + </tp:docstring> + </arg> + <arg direction="out" type="b"> + A boolean indicating whether or not the password was correct + </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 GetPasswordFlags method and the associated PasswordFlagsChanged + 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_Transfer.xml b/qt4/spec/Channel_Interface_Transfer.xml new file mode 100644 index 000000000..5165c9ad1 --- /dev/null +++ b/qt4/spec/Channel_Interface_Transfer.xml @@ -0,0 +1,53 @@ +<?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_Type_Contact_List.xml b/qt4/spec/Channel_Type_Contact_List.xml new file mode 100644 index 000000000..577f250c2 --- /dev/null +++ b/qt4/spec/Channel_Type_Contact_List.xml @@ -0,0 +1,71 @@ +<?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 + Channel.Interface.Group 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 + RequestHandles with a handle type of HANDLE_TYPE_LIST and + one of the following identifiers:</p> + + <ul> + <li>subscribe - the group of contacts for whom you wish to 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> + </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 + RequestHandles with a handle 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 closing 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 new file mode 100644 index 000000000..0213ca70d --- /dev/null +++ b/qt4/spec/Channel_Type_Contact_Search.xml @@ -0,0 +1,150 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp: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:causes-havoc='not well-tested'> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Search_Key_Info"> + <tp:docstring>A struct representing details on search strings.</tp:docstring> + <tp:member type="b" name="Is_Mandatory"> + <tp:docstring>Booleans indicating if the search key is mandatory. + </tp:docstring> + </tp:member> + <tp:member type="g" name="Type_Signature"> + <tp:docstring>The type signature of the value for this search key. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Search_Key_Info_Map"> + <tp:docstring>A dictionary mapping string search key names to its search details. + </tp:docstring> + <tp:member type="s" name="Term"/> + <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/> + </tp:mapping> + + <method name="GetSearchKeys"> + <arg direction="out" type="s"> + <tp:docstring> + A string with any instructions from the server + </tp:docstring> + </arg> + <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A dictionary mapping string search key names to its search details. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Returns any instructions from the server along with a dictionary of + search key names to their types, and a boolean indicating if the key is + mandatory. The following well-known search key names should be used + where appropriate:</p> + <dl> + <dt>s:first</dt><dd>The desired contact's given name</dd> + <dt>s:last</dt><dd>The desired contact's family name</dd> + <dt>s:nick</dt><dd>The desired contact's nickname</dd> + <dt>s:email</dt><dd>The e-mail address of the desired contact</dd> + </dl> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + <tp:enum name="Channel_Contact_Search_State" type="u"> + <tp:enumvalue suffix="Before" value="0"> + <tp:docstring>The search has not started</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="During" value="1"> + <tp:docstring>The search is in progress</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="After" value="2"> + <tp:docstring>The search has been completed</tp:docstring> + </tp:enumvalue> + </tp:enum> + <method name="GetSearchState"> + <arg direction="out" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring>The search state represented as one of the values of + ChannelContactSearchState</tp:docstring> + </arg> + <tp:docstring> + Returns the current state of this search channel object. + </tp:docstring> + </method> + <method name="Search"> + <arg direction="in" name="terms" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + A dictionary mapping search key names to the desired values + </tp:docstring> + </arg> + <tp:docstring> + Send a request to start a search for contacts on this connection. A + valid search request will cause the SearchStateChanged signal to be + emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING. + </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> + <signal name="SearchResultReceived"> + <arg name="contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>An integer handle for the contact</tp:docstring> + </arg> + <arg name="values" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring> + </arg> + <tp:docstring> + Emitted when a search result is received from the server. + </tp:docstring> + </signal> + <signal name="SearchStateChanged"> + <arg name="state" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring>An integer representing the new search state</tp:docstring> + </arg> + <tp:docstring> + Emitted when the search state (as returned by the GetSearchState + method) changes. + </tp:docstring> + </signal> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for searching server-stored user directories. A new channel + should be requested by a client for each search attempt, and it should be + closed when the search is completed or the required result has been found + in order to free unused handles. The search can be cancelled at any time + by calling the channel Close method, although depending upon the protocol + the connection manager may not be able to prevent the server from sending + further results.</p> + + <p>Before searching, the GetSearchKeys method should be used to discover any + instructions sent by the server, and the valid search keys which can be + provided to the Search method. A search request is then started by + providing some of these terms to the Search method, and the search status + will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are + returned by the server, the SearchResultReceived signal is emitted for each + contact found, and when the search is complete, the search status will be + set to CHANNEL_SEARCH_STATE_AFTER.</p> + </tp:docstring> + </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 new file mode 100644 index 000000000..10261c97f --- /dev/null +++ b/qt4/spec/Channel_Type_Room_List.xml @@ -0,0 +1,127 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp: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" 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"> + <arg direction="out" type="b"> + <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"> + <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 + RequestChannel 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>s:handle-name</dt><dd>The string name of the room handle (as would be returned by InspectHandles)</dd> + <dt>s:name</dt><dd>The human-readable name of the room if different from the handle</dd> + <dt>s:description</dt><dd>A description of the room's overall purpose</dd> + <dt>s:subject</dt><dd>The current subject of conversation in the room</dd> + <dt>u:members</dt><dd>The number of members of the room</dd> + <dt>b:password</dt><dd>True if the room requires a password to enter</dd> + <dt>b:invite-only</dt><dd>True if you cannot join the room, but must be invited</dd> + </dl> + </tp:docstring> + </signal> + <method name="ListRooms"> + <tp:docstring> + Request the list of rooms from the server. The ListingRooms signal + should be emitted when this request is being processed, GotRooms when + any room information is received, and ListingRooms 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:docstring> + Stop the room listing if it's in progress, but don't close the channel. + The ListingRooms signal should be emitted when the listing stops. + </tp:docstring> + </method> + <signal name="ListingRooms"> + <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 + ListRooms method is called, it emits signals for rooms present on the + server, until you Close 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 ListingRooms + signal, or GetListingRooms 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_Streamed_Media.xml b/qt4/spec/Channel_Type_Streamed_Media.xml new file mode 100644 index 000000000..0c2eced3d --- /dev/null +++ b/qt4/spec/Channel_Type_Streamed_Media.xml @@ -0,0 +1,377 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp: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"> + <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 RequestStreamDirection 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 StreamDirectionChanged 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"/> + + <method name="ListStreams"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> + <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"> + <arg direction="in" name="streams" type="au" tp:type="Stream_ID[]"> + <tp:docstring> + An array of stream identifiers (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring> + Request that the given streams are removed. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + A stream identifier is unknown + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreamDirection"> + <arg direction="in" name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </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 StreamRemoved 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 StreamDirectionChanged 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"> + A stream identifier is unknown + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The requested direction is not available on this stream + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreams"> + <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[]"> + <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 StreamDirectionChanged 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> + </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 Group 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 CallState 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"> + A stream type given is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + That contact is not able to do this stream type + </tp:error> + </tp:possible-errors> + </method> + + <signal name="StreamAdded"> + <arg name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </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> + Emitted when a new stream has been added to this channel. + </tp:docstring> + </signal> + + <signal name="StreamDirectionChanged"> + <arg name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </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> + Emitted when the direction or pending flags of a stream are changed. If + the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has + requested that we begin sending on this stream. RequestStreamDirection + should be called to indicate whether or not this change is acceptable. + </tp:docstring> + </signal> + + <signal name="StreamError"> + <arg name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </tp:docstring> + </arg> + <arg name="errno" type="u"> + <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"> + <arg name="stream_id" type="u"> + <tp:docstring> + stream_id - the stream identifier (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a stream has been removed from this channel. + </tp:docstring> + </signal> + + <signal name="StreamStateChanged"> + <arg name="stream_id" type="u"> + <tp:docstring> + The stream identifier (as defined in ListStreams) + </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> + + <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.</p> + + <p>Channels of this type are expected to provide the Group interface + and be "anonymous" (have no associated handle). To make a media call + to a contact, clients should request a new, empty streamed media + channel, then call AddMembers to add the contact to the channel. + The local user should be in the group's members, while the contact + should be absent from the channel until a call is made, appear in + "remote pending" from when the call is attempted until the call is + accepted, then move to the group's members.</p> + + <p>Similarly, incoming calls should be signalled as having handle type 0 + and handle 0. The remote contact should be in the group's members, + with the local user in the "local pending" members; to accept the + call, AddMembers can be used to move the local user to the + group's members.</p> + + <p>In general this should be used in conjunction with the MediaSignalling + 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> + </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 Connection.Interface.Capabilities + interface. + </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: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 new file mode 100644 index 000000000..b3265ec50 --- /dev/null +++ b/qt4/spec/Channel_Type_Text.xml @@ -0,0 +1,467 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp: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:simple-type name="Message_ID" type="u"> + <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: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 ListPendingMessages + on the Text channel type. The arguments of the Received 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"> + <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"> + <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]"> + <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"> + <arg direction="in" name="clear" type="b"> + <tp:docstring> + If true, behave as if AcknowledgePendingMessages had also been + called. + </tp:docstring> + <tp:deprecated since="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[]"> + <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: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"> + <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 + AcknowledgePendingMessage method. + </tp:docstring> + </signal> + + <method name="Send"> + <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> + Request that a message be sent on this channel. When the message has + been submitted for delivery, this method will return and the Sent + signal will be emitted. If the message cannot be submitted for + delivery, the method returns an error and no signal is 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.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"> + <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 + Sent has already been emitted and Send 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"> + <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 + </tp:docstring> + </arg> + <tp:docstring> + Signals that a message has been submitted for sending. + </tp:docstring> + </signal> + + <tp:enum name="Channel_Text_Message_Type" type="u"> + <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> + This message type MUST NOT appear unless the channel supports the + DeliveryReporting interface. The message MUST be as defined by + the DeliveryReporting interface. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u"> + <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 Messages 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: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 string + version of the channel's handle. + </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. + </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. + </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. + </tp:docstring> + </tp:property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for sending and receiving messages in plain text, + with no formatting. In future specifications, channels for sending + and receiving messages that can be reduced to plain text (i.e. + formatted text) should also have this type.</p> + + <p>When a message is received, an identifier is assigned and a + Received signal emitted, and the message placed in a pending queue + which can be inspected with ListPendingMessages. A client which has + handled the message by showing it to the user (or equivalent) should + acknowledge the receipt using the AcknowledgePendingMessage 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>Each message has an associated 'type' value, which should be one + of the values allowed by ChannelTextMessageType.</p> + + <p>Each message also has a flags value, which is a bitwise OR of the + flags given in ChannelTextMessageFlags.</p> + + <p>Sending messages can be requested using the Send method, which will + return successfully and emit the Sent signal when the message has + been delivered to the server, or return an error with no signal + emission if there is a failure. If a message is sent but delivery + of the message later fails, this is indicated with the SendError + signal.</p> + + <p>On protocols where additional contacts cannot be invited into + a one-to-one chat, or where a one-to-one chat is just a series of + individual personal messages rather than being represented by some + object on the server (i.e. most protocols), one-to-one chats should be + represented by a Text channel with handle type CONTACT.</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 handle type ROOM and the Group interface; they should + usually also have the Properties interface.</p> + + <p>Unnamed, transient chat rooms defined only by their members (e.g. on + MSN) are expected to be represented by Text channels with handle type + 0, handle 0, the Group interface, and optionally the Properties + interface.</p> + + <p>On protocols 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, calling RequestChannel with type Text + and handle type CONTACT should continue to succeed, but may return + a channel with handle type 0, handle 0, the group interface, + and the local and remote contacts in its members.</p> + </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 new file mode 100644 index 000000000..b187c03e1 --- /dev/null +++ b/qt4/spec/Channel_Type_Tubes.xml @@ -0,0 +1,743 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright (C) 2007-2008 Collabora Limited + </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: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>A struct (handle, unique name) representing a participant + in a D-Bus tube, as returned by GetDBusNames on the Tubes channel + type, and as seen in the DBusNamesChanged signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"/> + </tp:struct> + + <tp:struct name="Socket_Address_IPv4"> + <tp:docstring>An IPv4 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv6"> + <tp:docstring>An IPv6 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv4"> + <tp:docstring>An IPv4 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv6"> + <tp:docstring>An IPv6 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum name="Tube_Type" type="u"> + <tp:enumvalue suffix="DBus" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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> + </tp:enumvalue> + + <tp:enumvalue suffix="Stream" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A transport for ordered, reliable data transfer, similar to + SOCK_STREAM sockets.</p> + + <p>When accepting a Stream Unix tube, a new listening local socket is + created. Each time the client connects to this socket, the + connection manager of the initiator of the tube opens a new + connection to its local socket. Both sides can then use this pair + of sockets to communicate together.</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:enum name="Socket_Address_Type" type="u"> + <tp:enumvalue suffix="Unix" value="0"> + <tp:docstring> + A Unix socket. The 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 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 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 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"> + <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: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>The connecting process must send a single zero (NUL) 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> + + <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: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"> + <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"> + <arg direction="out" type="au" tp:type="Tube_Type[]"> + <tp:docstring> + An array of the available tube types, as defined by the Tube_Type + enum. + </tp:docstring> + </arg> + </method> + + <method name="ListTubes"> + <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"> + <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> + + <method name="OfferDBusTube"> + <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"> + <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: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"> + <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: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> + + <method name="AcceptDBusTube"> + <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: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: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: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: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> + + <method name="GetDBusTubeAddress"> + <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"> + <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> + + <method name="GetDBusNames"> + <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[]"> + <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> + + <signal name="DBusNamesChanged"> + <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: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: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/Connection.xml b/qt4/spec/Connection.xml new file mode 100644 index 000000000..792499671 --- /dev/null +++ b/qt4/spec/Connection.xml @@ -0,0 +1,650 @@ +<?xml version="1.0" ?> +<node name="/Connection" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright (C) 2005, 2006, 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.Connection"> + + <tp:struct name="Channel_Info" array-name="Channel_Info_List"> + <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:docstring> + Request that the connection be established. This will be done + asynchronously and errors will be returned by emitting StatusChanged + signals. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The connection is already connecting or connected + </tp:error> + </tp:possible-errors> + </method> + + <method name="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> + + <method name="GetInterfaces"> + <arg direction="out" type="as" tp:type="DBus_Interface[]"> + <tp:docstring> + An array of D-Bus interface names + </tp:docstring> + </arg> + + <tp:docstring> + Get the optional interfaces supported by this connection. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <method name="GetProtocol"> + <arg direction="out" type="s" tp:type="Protocol"> + <tp:docstring> + A string identifier for the protocol + </tp:docstring> + </arg> + + <tp:docstring> + Get the protocol this connection is using. + </tp:docstring> + </method> + + <method name="GetSelfHandle"> + <arg direction="out" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle representing the user + </tp:docstring> + </arg> + + <tp:docstring> + Get 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 Renamed signal on the + Renaming interface (if present). + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <method name="GetStatus"> + <arg direction="out" type="u" tp:type="Connection_Status"> + <tp:docstring> + An integer representing the current status + </tp:docstring> + </arg> + + <tp:docstring> + Get the current status as defined in the StatusChanged signal. + </tp:docstring> + </method> + + <method name="HoldHandles"> + <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>Notify 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 RequestHandles 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 ReleaseHandle + 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"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + </tp:possible-errors> + </method> + + <method name="InspectHandles"> + <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"> + <tp:docstring> + An array of handle names in the same order as the given numbers + </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"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + </tp:possible-errors> + </method> + + <method name="ListChannels"> + <arg direction="out" type="a(osuu)" tp:type="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"> + <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 RequestChannel method), so no other handler should be + launched.</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 + (a typical use-case is an address-book viewer that does not itself + implement chat or VoIP functionality, starting a channel that + will be handled by the same user interface that would handle + incoming channels).</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"> + <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> + Explicitly notify 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 HoldHandles for notes. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + One of the given handles is not held by this client + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestChannel"> + <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> + If true, the requesting client intends to take responsibility for + displaying the channel to the user, so no other handler needs to + be launched + </tp:docstring> + </arg> + + <arg direction="out" type="o"> + <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 GetHandle() returns 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.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"> + <tp:docstring>An unsigned 32-bit integer representing a + handle</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Contact_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Contact</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Room_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Room</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="List_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_List</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Group_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Group</tp:docstring> + </tp:simple-type> + + <method name="RequestHandles"> + <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="names" type="as"> + <tp:docstring> + An array of names of entities to request handles for + </tp:docstring> + </arg> + + <arg direction="out" type="au" tp:type="Handle[]"> + <tp:docstring> + An array of integer handle numbers in the same order as the given strings + </tp:docstring> + </arg> + + <tp:docstring> + Request several handles from the connection manager which represent a + number of contacts, rooms or server-stored lists on the service. 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 ReleaseHandle + method. Where the name 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. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The given name is not a valid entity of the given type + </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 alive and all methods are available. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connecting" value="1"> + <tp:docstring> + The connection has not yet been established, or has been + severed and reconnection is being attempted. Some methods may fail + until the connection has been established. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Disconnected" value="2"> + <tp:docstring> + The connection has been severed and no method calls are + valid. The object may be removed from the bus at any time. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <tp:enum name="Connection_Status_Reason" type="u"> + <tp:enumvalue suffix="None_Specified" value="0"> + <tp:docstring> + There is no reason set for this state change. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Requested" value="1"> + <tp:docstring> + The change is in response to a user request. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Network_Error" value="2"> + <tp:docstring> + There was an error sending or receiving on the network socket. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Authentication_Failed" value="3"> + <tp:docstring> + The username or password was invalid. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Encryption_Error" value="4"> + <tp:docstring> + There was an error negotiating SSL on this connection, or + encryption was unavailable and require-encryption was set when the + connection was created. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Name_In_Use" value="5"> + <tp:docstring> + Someone is already connected to the server using the name + you are trying to connect with. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Not_Provided" value="6"> + <tp:docstring> + The server did not provide a SSL certificate. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Untrusted" value="7"> + <tp:docstring> + The server's SSL certificate could not be trusted. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Expired" value="8"> + <tp:docstring> + The server's SSL certificate has expired. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Not_Activated" value="9"> + <tp:docstring> + The server's SSL certificate is not yet valid. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10"> + <tp:docstring> + The server's SSL certificate did not match its hostname. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11"> + <tp:docstring> + The server's SSL certificate does not have the expected + fingerprint. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Self_Signed" value="12"> + <tp:docstring> + The server's SSL certificate is self-signed. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cert_Other_Error" value="13"> + <tp:docstring> + There was some other error validating the server's SSL certificate. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="StatusChanged"> + <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: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>As well as the methods and signatures below, arbitrary interfaces may be + provided by the Connection object to represent extra connection-wide + functionality, such as the Connection.Interface.Presence for receiving and + 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 GetInterfaces after the + connection, has been established and must not change subsequently at + runtime.</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 name with the RequestHandles + method, inspect the entity name of handles with the InspectHandles method, + keep handles from being released with HoldHandles, and notify that they are + no longer storing handles with ReleaseHandles.</p> + </tp:docstring> + </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 new file mode 100644 index 000000000..c975adfff --- /dev/null +++ b/qt4/spec/Connection_Interface_Aliasing.xml @@ -0,0 +1,144 @@ +<?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 AliasesChanged + signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:struct> + + <signal name="AliasesChanged"> + <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"> + <arg direction="out" type="u" tp:type="Connection_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"> + <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"> + <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="SetAliases"> + <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 AliasesChanged 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 + GetSelfHandle on the Connection interface). + </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 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 GetAliasFlags method will have the + CONNECTION_ALIAS_FLAG_USER_SET flag set, and the SetAliases 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_Avatars.xml b/qt4/spec/Connection_Interface_Avatars.xml new file mode 100644 index 000000000..9395a6efd --- /dev/null +++ b/qt4/spec/Connection_Interface_Avatars.xml @@ -0,0 +1,294 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Avatars" 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.Connection.Interface.Avatars"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <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" name="Token"/> + </tp:mapping> + + <signal name="AvatarUpdated"> + <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" 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 RequestAvatars. + </tp:docstring> + </signal> + <signal name="AvatarRetrieved"> + <arg name="contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose avatar has been retrieved + </tp:docstring> + </arg> + <arg name="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> + <method name="GetAvatarRequirements"> + <arg direction="out" type="as"> + <tp:docstring> + An array of supported MIME types (eg image/jpeg) + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The minimum image width in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The minimum image height in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The maximum image width in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="q"> + <tp:docstring> + The maximum image height in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="u"> + <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"> + <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"> + <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:docstring> + Get the unique tokens for all of the given contacts' avatars. + + Using this method in new Telepathy clients is deprecated; use + GetKnownAvatarTokens 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"> + <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="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. A CM must always have + the tokens for the self handle if one is set (even if it is set to no + avatar). Otherwise, only tokens that are already known are returned. An + empty token means the given contact has no avatar. + </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"> + <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"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg direction="out" type="s"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> + <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"> + <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 AvatarRetrieved 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"> + <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"> + <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 GetAvatarRequirements. + </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: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: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 unique (per contact) token which represents a + hash or timestamp (depending on the protocol) of the contacts' avatar data. + 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 GetKnownAvatarTokens 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 RequestAvatars for the contacts. + Clients should bind to the AvatarChanged 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 SetAvatar to provide an image + which meets the requirements returned by the GetAvatarRequirements + 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, and set the avatar if it is an empty string (and may + optionally replace it if the token corresponds to a different avatar).</p> + + <p>To remove the published avatar on protocols which have persistent avatars, + a client should use the ClearAvatar 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_Capabilities.xml b/qt4/spec/Connection_Interface_Capabilities.xml new file mode 100644 index 000000000..e4b739d23 --- /dev/null +++ b/qt4/spec/Connection_Interface_Capabilities.xml @@ -0,0 +1,206 @@ +<?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:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections where it is possible to know what channel + types may be requested before the request is made to the connection + object. Each capability represents a commitment by the connection + manager that it will ordinarily be able to create a channel when given + a request with the given type and handle.</p> + + <p>Capabilities can pertain to a certain contact handle, representing + activities such as having a text chat or a voice call with the user, or + can be on the connection itself (where the handle will be zero), where + they represent the ability to create channels for chat rooms or + activities such as searching and room listing. The activities are + represented by the D-Bus interface name of the channel type for that + activity.</p> + + <p>The generic capability flags are defined by + Connection_Capability_Flags.</p> + + <p>In addition, channel types may have type specific capability flags of + their own, which are described in the documentation for each channel + type.</p> + + <p>This interface also provides for user interfaces notifying the + connection manager of what capabilities to advertise for the user. This + is done by using the AdvertiseCapabilities method, and deals with the + interface names of channel types and the type specific flags pertaining + to them which are implemented by available client processes.</p> + </tp:docstring> + + <tp:flags name="Connection_Capability_Flags" + value-prefix="Connection_Capability_Flag" type="u"> + <tp:flag suffix="Create" value="1"> + <tp:docstring> + The given channel type and handle can be given to RequestChannel to + create a new channel of this type. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Invite" value="2"> + <tp:docstring> + The given contact can be invited to an existing channel of this type. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:struct name="Capability_Pair" array-name="Capability_Pair_List"> + <tp:docstring>A pair (channel type, type-specific flags) as passed to + AdvertiseCapabilities 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 GetCapabilities 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 + CapabilitiesChanged 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"> + <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[]"> + <tp:docstring> + An array of structures describing the current capabilities containing: + <ul> + <li>a string channel type</li> + <li>a bitwise OR of type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used by user interfaces to indicate which channel types they are able + to handle on this connection. Because these may be provided by + different client processes, this method accepts channel types to add + and remove from the set already advertised on this connection. The type + of advertised capabilities (create versus invite) is protocol-dependent + and hence cannot be set by the this method. In the case of a client + adding an already advertised channel type but with new channel type + specific flags, the connection manager should simply add the new flags + to the set of advertised capabilities.</p> + + <p>Upon a successful invocation of this method, the CapabilitiesChanged + signal will be emitted for the user's own handle (as returned by + GetSelfHandle) the by the connection manager to indicate the changes + that have been made. This signal should also be monitored to ensure + that the set is kept accurate - for example, a client may remove + capabilities or type specific capability flags when it exits + which are still provided by another client.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <signal name="CapabilitiesChanged"> + <arg name="caps" type="a(usuuuu)" tp: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> + Announce that there has been a change of capabilities on the + given handle, or on the connection itself if the handle is zero. + </tp:docstring> + </signal> + + <method name="GetCapabilities"> + <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of contact handles for this connection, or zero to query capabilities available on the connection itself + </tp:docstring> + </arg> + <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]"> + <tp:docstring> + An array of structures containing: + <ul> + <li>an integer handle representing the contact</li> + <li>a string channel type</li> + <li>a bitwise OR of generic capability flags for the type</li> + <li>a bitwise OR of type specific capability flags for the type</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of capabilities for the given contact handles, or + the connection itself (where handle is zero). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The handle does not represent a contact + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + </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 new file mode 100644 index 000000000..22cd507ca --- /dev/null +++ b/qt4/spec/Connection_Interface_Contact_Info.xml @@ -0,0 +1,83 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Info" 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.ContactInfo" + tp:causes-havoc='obsolete'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <signal name="GotContactInfo"> + <arg name="contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle of the contact ID on the server + </tp:docstring> + </arg> + <arg name="vcard" type="s"> + <tp:docstring> + The XML string containing their vcard information + </tp:docstring> + </arg> + <tp:docstring> + Emitted when information has been received from the server with + the details of a particular contact. + </tp:docstring> + </signal> + <method name="RequestContactInfo"> + <arg direction="in" name="contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact to request info for + </tp:docstring> + </arg> + <tp:docstring> + Request information for a given contact. The function will return + after a GotContactInfo signal has been emitted for the contact, or + an error returned. + </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:possible-errors> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. A new version + will be proposed in the 0.13 specification branch.</p> + + <p>An interface for requesting information about a contact on a given + connection. Information is returned as a vCard represented as an XML + string, in the format defined by JEP-0054: vcard-temp specifiation + from the Jabber Software Foundation (this is derived from the + aborted IETF draft draft-dawson-vcard-xml-dtd-01).</p> + + <p>Implementations using PHOTO or SOUND elements should use the URI encoding + where possible, and not provide base64 encoded data to avoid unnecessary + bus traffic. Clients should not implement support for these encoded forms. + A separate interface will be provided for transferring user avatars.</p> + + <p>The following extended element names are also added to represent + information from other systems which are not based around vCards:</p> + <dl> + <dt>USERNAME</dt><dd>the username of the contact on their local system (used on IRC for example)</dd> + <dt>HOSTNAME</dt><dd>the fully qualified hostname, or IPv4 or IPv6 address of the contact in dotted quad or colon-separated form</dd> + </dl> + </tp:docstring> + </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 new file mode 100644 index 000000000..6322fbc75 --- /dev/null +++ b/qt4/spec/Connection_Interface_Forwarding.xml @@ -0,0 +1,76 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Forwarding" 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.Forwarding" + tp:causes-havoc='not well-tested'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <signal name="ForwardingChanged"> + <arg name="forward_to" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer contact handle to forward communication to + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the forwarding contact handle for this connection has been + changed. An zero handle indicates forwarding is disabled. + </tp:docstring> + </signal> + <method name="GetForwardingHandle"> + <arg direction="out" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer contact handle to whom incoming communication is forwarded + </tp:docstring> + </arg> + <tp:docstring> + Returns the current forwarding contact handle, or zero if none 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.NotAvailable"/> + </tp:possible-errors> + </method> + <method name="SetForwardingHandle"> + <arg direction="in" name="forward_to" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer contact handle to forward incoming communications to + </tp:docstring> + </arg> + <tp:docstring> + Set a contact handle to forward incoming communications to. A zero + handle disables forwarding. + </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> + <tp:docstring> + A connection interface for services which can signal to contacts + that they should instead contact a different user ID, effectively + forwarding all incoming communication channels to another contact on + the service. + </tp:docstring> + </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 new file mode 100644 index 000000000..98cf87391 --- /dev/null +++ b/qt4/spec/Connection_Interface_Presence.xml @@ -0,0 +1,357 @@ +<?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"/> + + <!-- We hope to simplify these eventually --> + <tp:mapping name="Multiple_Status_Map"> + <tp:docstring>Mapping used in Last_Activity_And_Statuses and passed to + SetStatus, 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 GetPresence and signalled by + PresenceUpdate, 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"> + <arg direction="in" name="status" type="s"> + <tp:docstring> + The string identifier of the desired status + </tp:docstring> + </arg> + <arg direction="in" name="parms" 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 PresenceUpdate + 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: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 PresenceUpdate + 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"> + <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 PresenceUpdate + signal + </tp:docstring> + </arg> + <tp:docstring> + Get presence previously emitted by PresenceUpdate for the given + contacts. Data is returned in the same structure as the PresenceUpdate + signal. Using this method in favour of RequestPresence 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"> + <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map"> + <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"> + <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 RequestPresence is available. + + </tp:docstring> + </signal> + <method name="RemoveStatus"> + <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 PresenceUpdate signals being + emitted. As with ClearStatus, 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"> + <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 PresenceUpdate + 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' Channel.Type.ContactList, 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"> + <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"> + <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> + Request that the user's presence be changed to the given statuses and + desired parameters. Changes will be reflected by PresenceUpdate + signals being emitted. On certain protocols, this method may be + called on a newly-created connection which is still in the + DISCONNECTED state, and will sign on with the requested status. + If the requested status is not available after signing on, + NotAvailable will be returned and the connection will remain + offline, or if the protocol does not support signing on with + a certain status, Disconnected will be returned. + </tp:docstring> + <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 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 the Galago project + (see http://www.galago-project.org/).</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 GetStatuses + method.</p> + + <p>Each status has an arbitrary string identifier which should have an agreed + meaning between the connection manager and any client which is expected to + make use of it. The following well-known values (in common with those in + Galago) should be used where possible to allow clients to identify common + choices:</p> + + <ul> + <li>available</li> + <li>away</li> + <li>brb (Be Right Back)</li> + <li>busy</li> + <li>dnd (Do Not Disturb),</li> + <li>xa (Extended Away)</li> + <li>hidden (aka Invisible)</li> + <li>offline</li> + </ul> + + <p>As well as these well-known status identifiers, every status also has a + numerical type value chosen from ConnectionPresenceType 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, PresenceUpdate 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, RequestPresence 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> + <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 + </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:enum> + </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 new file mode 100644 index 000000000..865473632 --- /dev/null +++ b/qt4/spec/Connection_Interface_Privacy.xml @@ -0,0 +1,93 @@ +<?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"> + <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"> + <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"> + <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"> + <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 new file mode 100644 index 000000000..2c4e27253 --- /dev/null +++ b/qt4/spec/Connection_Interface_Renaming.xml @@ -0,0 +1,94 @@ +<?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"> + <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 + MembersChanged signal must be emitted <em>after</em> the Renamed + 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"> + <arg direction="in" name="name" 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 Renamed signal will be emitted for the current + "self handle" as returned by GetSelfHandle.</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_Manager.xml b/qt4/spec/Connection_Manager.xml new file mode 100644 index 000000000..d16960727 --- /dev/null +++ b/qt4/spec/Connection_Manager.xml @@ -0,0 +1,412 @@ +<?xml version="1.0" ?> +<node name="/Connection_Manager" 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.ConnectionManager"> + + <tp:simple-type name="Connection_Manager_Name" type="s"> + <tp:docstring> + 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. + </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"> + <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>napster - Napster</li> + <li>qq - Tencent QQ</li> + <li>sametime - IBM Lotus Sametime</li> + <li>silc - SILC</li> + <li>sip - Session Initiation Protocol (SIP)</li> + <li>trepia - Trepia</li> + <li>yahoo - YMSG (Yahoo! Messenger)</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:flags> + + <method name="GetParameters"> + <arg direction="in" name="proto" type="s" tp:type="Protocol"> + <tp:docstring> + The required protocol name + </tp:docstring> + </arg> + <arg direction="out" type="a(susv)" tp:type="Param_Spec[]"> + <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 + RequestConnection 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"> + The requested protocol is not supported by this manager + </tp:error> + </tp:possible-errors> + </method> + + <method name="ListProtocols"> + <arg direction="out" type="as" tp:type="Protocol[]"> + <tp:docstring> + A array of string protocol identifiers supported by this manager + </tp:docstring> + </arg> + <tp:docstring> + Get a list of protocol identifiers that are implemented by this + connection manager. + </tp:docstring> + </method> + + <signal name="NewConnection"> + <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="proto" type="s" tp:type="Protocol"> + <tp:docstring> + The identifier for the protocol this connection uses + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a new Connection object is created. + </tp:docstring> + </signal> + + <method name="RequestConnection"> + <arg direction="in" name="proto" 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 name to the variant boxed value + </tp:docstring> + </arg> + <arg direction="out" type="s" tp:type="DBus_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"> + <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 Connection 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 + Connect method.</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 connection manager name that appears + in the connection manager's object path and well-known bus name</li> + <li><em>proto</em> is the protocol name as seen in + ListProtocols, but with "-" replaced with "_" to get a valid + object path/bus name</li> + <li><em>account</em> SHOULD be a series of elements 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), or on protocols where connecting multiple times + is permissable, a per-connection identifier might be necessary to + ensure uniqueness</li> + </ul> + + <p>Clients MUST NOT attempt to parse the <em>account</em> part of the + bus name. Connection managers MAY use any unique string for this + part.</p> + + <p>The parameters which must and may be provided in the parameters + dictionary can be discovered with the GetParameters 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 + following well-known names and types should be used where appropriate:</p> + + <dl> + <dt>s:account</dt> + <dd>The identifier for the user's account on the server</dd> + + <dt>s:server</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>q:port</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>s:password</dt><dd>A password associated with the account.</dd> + + <dt>b:require-encryption</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>b:register</dt><dd>This account should be created on the server if it + does not already exist.</dd> + + <dt>s:ident</dt><dd>The local username to report to the server if + necessary, such as in IRC.</dd> + + <dt>s:fullname</dt><dd>The user's full name if the service requires this + when authenticating or registering.</dd> + + <dt>s:stun-server</dt><dd>The IP address or FQDN of a STUN server to use + for NAT traversal, without any ":port" suffix.</dd> + <dt>q:stun-port</dt><dd>The UDP port number on the stun-server to use for + STUN. Only significant if the stun-server is also supplied.</dd> + </dl> + + <p>Every successful RequestConnection call will cause the emission of a + NewConnection 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"> + The requested protocol is not supported by this manager + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + The requested connection already appears to exist + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + Unrecognised connection parameters + </tp:error> + </tp:possible-errors> + </method> + + <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 ListProtocols method, then for each protocol of interest, + calling GetParameters 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>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> + </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</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</dd> + <dt>q, u, t (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> + </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> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Makefile.am b/qt4/spec/Makefile.am new file mode 100644 index 000000000..871cbc5ad --- /dev/null +++ b/qt4/spec/Makefile.am @@ -0,0 +1,41 @@ +EXTRA_DIST = \ + Account_Interface_Avatar.xml \ + Account_Manager.xml \ + Account.xml \ + all.xml \ + Channel_Future.xml \ + Channel_Handler.xml \ + Channel_Interface_Call_Merging.xml \ + Channel_Interface_Call_State.xml \ + Channel_Interface_Chat_State.xml \ + Channel_Interface_Delivery_Reporting.xml \ + Channel_Interface_DTMF.xml \ + Channel_Interface_Group.xml \ + Channel_Interface_Hold.xml \ + Channel_Interface_HTML.xml \ + Channel_Interface_Media_Signalling.xml \ + Channel_Interface_Messages.xml \ + Channel_Interface_Password.xml \ + Channel_Interface_Transfer.xml \ + Channel_Type_Contact_List.xml \ + Channel_Type_Contact_Search.xml \ + Channel_Type_Room_List.xml \ + Channel_Type_Streamed_Media.xml \ + Channel_Type_Text.xml \ + Channel_Type_Tubes.xml \ + Channel.xml \ + Connection_Interface_Aliasing.xml \ + Connection_Interface_Avatars.xml \ + Connection_Interface_Capabilities.xml \ + Connection_Interface_Contact_Info.xml \ + Connection_Interface_Forwarding.xml \ + Connection_Interface_Presence.xml \ + Connection_Interface_Privacy.xml \ + Connection_Interface_Renaming.xml \ + Connection_Manager.xml \ + Connection.xml \ + errors.xml \ + generic-types.xml \ + Media_Session_Handler.xml \ + Media_Stream_Handler.xml \ + Properties_Interface.xml diff --git a/qt4/spec/Media_Session_Handler.xml b/qt4/spec/Media_Session_Handler.xml new file mode 100644 index 000000000..b4e9ffbe0 --- /dev/null +++ b/qt4/spec/Media_Session_Handler.xml @@ -0,0 +1,75 @@ +<?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"> + <arg direction="in" name="errno" type="u"/> + <arg direction="in" name="message" type="s"/> + <tp:docstring> + THIS METHOD IS DEPRECATED AND SHOULD NOT BE USED. Instead the Error + function should be used on the relevant MediaStreamHandler objects. + Informs the connection manager that an error occured in this session. + If used, the connection manager must terminate the session and all of + the streams within it, and may also emit a StreamError signal on the + channel for each stream within the session. + </tp:docstring> + </method> + <signal name="NewStreamHandler"> + <arg name="stream_handler" type="o"> + <tp:docstring> + An object path to a new MediaStreamHandler + </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> + Enum for type of media that this stream should handle + (a value from MediaStreamType) + </tp:docstring> + </arg> + <arg name="direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + Enum for direction of this stream (a value from + MediaStreamDirection) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a new stream handler has been created for this + session. + </tp:docstring> + </signal> + <method name="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 + NewStreamHandler 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 new file mode 100644 index 000000000..7d6946327 --- /dev/null +++ b/qt4/spec/Media_Stream_Handler.xml @@ -0,0 +1,379 @@ +<?xml version="1.0" ?> +<node name="/Media_Stream_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.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:member type="u" name="Codec_ID"/> + <tp:member type="s" name="Name"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type"/> + <tp:member type="u" name="Clock_Rate"/> + <tp:member type="u" name="Number_Of_Channels"/> + <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map"/> + </tp:struct> + + <signal name="AddRemoteCandidate"> + <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:docstring> + Signal emitted when the connection manager wishes the stream to be + closed. + </tp:docstring> + </signal> + <method name="CodecChoice"> + <arg direction="in" name="codec_id" type="u"/> + <tp:docstring> + Inform the connection manager of the current codec choice. + </tp:docstring> + </method> + <method name="Error"> + <arg direction="in" name="errno" 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:enumvalue> + </tp:enum> + <method name="NativeCandidatesPrepared"> + <tp:docstring> + Informs the connection manager that all possible native candisates + have been discovered for the moment. + </tp:docstring> + </method> + <method name="NewActiveCandidatePair"> + <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> + <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"> + <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"> + <arg direction="in" name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + As for SupportedCodecs. + </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"> + <arg name="codecs" type="a(usuuua{ss})" direction="in" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring>Codecs in the same format as for + SupportedCodecs, which have the same semantics as the + local codecs passed to Ready</tp:docstring> + </arg> + <tp:docstring> + 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. + </tp:docstring> + </method> + <signal name="RemoveRemoteCandidate"> + <arg name="candidate_id" type="s"> + <tp:docstring> + String identifier for remote candidate to drop + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client that the remote end has removed a previously usable + candidate. + </tp:docstring> + </signal> + <signal name="SetActiveCandidatePair"> + <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"> + <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"> + <arg name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring>As for SupportedCodecs</tp:docstring> + </arg> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client of the codecs supported by the remote end. + </tp:docstring> + </signal> + <signal name="SetStreamPlaying"> + <arg name="playing" type="b"/> + <tp:docstring> + Signal emitted when the connection manager wishes to set the + stream playing or stopped. + </tp:docstring> + </signal> + <signal name="SetStreamSending"> + <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"> + <arg name="event" type="y"> + <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. + </tp:docstring> + </signal> + <signal name="StopTelephonyEvent"> + <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"> + <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"> + <arg direction="in" name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + List of codec info structures, each containing: + <ul> + <li>ID of codec</li> + <li>Codec name</li> + <li>Media type</li> + <li>Clock rate of codec</li> + <li>Number of supported channels</li> + <li>String key-value pairs for supported optional parameters</li> + </ul> + </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> + + <signal name="SetStreamHeld"> + <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: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: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 new file mode 100644 index 000000000..fa78f20a0 --- /dev/null +++ b/qt4/spec/Properties_Interface.xml @@ -0,0 +1,191 @@ +<?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"> + <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: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[]"> + <!-- 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:docstring> + Returns a dictionary of the properties available on this channel. + </tp:docstring> + <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]"> + <!-- 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: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: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: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> + A dictionary mapping integer 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/all.xml b/qt4/spec/all.xml new file mode 100644 index 000000000..b5a1b60cc --- /dev/null +++ b/qt4/spec/all.xml @@ -0,0 +1,79 @@ +<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.17.7</tp:version> + +<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> +<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> +<tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + +<tp: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> + +<xi:include href="Connection_Manager.xml"/> +<xi:include href="Connection.xml"/> +<xi:include href="Connection_Interface_Aliasing.xml"/> +<xi:include href="Connection_Interface_Avatars.xml"/> +<xi:include href="Connection_Interface_Capabilities.xml"/> +<!-- Never implemented, is a terrible API +<xi:include href="Connection_Interface_Contact_Info.xml"/> --> +<!-- Never implemented, insufficient (needs conditions) +<xi:include href="Connection_Interface_Forwarding.xml"/> --> +<xi:include href="Connection_Interface_Presence.xml"/> +<!-- Never implemented, vague +<xi:include href="Connection_Interface_Privacy.xml"/> --> +<xi:include href="Connection_Interface_Renaming.xml"/> + +<xi:include href="Channel.xml"/> +<xi:include href="Channel_Future.xml"/> +<xi:include href="Channel_Type_Contact_List.xml"/> +<!-- Never implemented, can't be implemented with current dbus-glib, vague +<xi:include href="Channel_Type_Contact_Search.xml"/> --> +<xi:include href="Channel_Type_Streamed_Media.xml"/> +<xi:include href="Channel_Type_Room_List.xml"/> +<xi:include href="Channel_Type_Text.xml"/> +<xi:include href="Channel_Type_Tubes.xml"/> + +<xi:include href="Channel_Interface_Call_Merging.xml"/> +<xi:include href="Channel_Interface_Call_State.xml"/> +<xi:include href="Channel_Interface_Chat_State.xml"/> +<xi:include href="Channel_Interface_Delivery_Reporting.xml"/> +<xi:include href="Channel_Interface_DTMF.xml"/> +<xi:include href="Channel_Interface_Group.xml"/> +<xi:include href="Channel_Interface_Hold.xml"/> +<xi:include href="Channel_Interface_HTML.xml"/> +<xi:include href="Channel_Interface_Password.xml"/> +<!-- Causes havoc, never implemented, unclear requirements +<xi:include href="Channel_Interface_Transfer.xml"/> --> +<xi:include href="Channel_Interface_Media_Signalling.xml"/> +<xi:include href="Channel_Interface_Messages.xml"/> + +<xi:include href="Media_Session_Handler.xml"/> +<xi:include href="Media_Stream_Handler.xml"/> + +<xi:include href="Properties_Interface.xml"/> + +<xi:include href="Account_Manager.xml"/> +<xi:include href="Account.xml"/> + +<xi:include href="Channel_Handler.xml"/> + +<xi:include href="errors.xml"/> +<xi:include href="generic-types.xml"/> + +</tp:spec> diff --git a/qt4/spec/errors.xml b/qt4/spec/errors.xml new file mode 100644 index 000000000..81ab440e7 --- /dev/null +++ b/qt4/spec/errors.xml @@ -0,0 +1,80 @@ +<?xml version="1.0" ?> +<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> + <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. + </tp:docstring> + </tp:error> + + <tp:error name="Invalid Handle"> + <tp:docstring> + The contact name 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:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005, 2006, 2007 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 new file mode 100644 index 000000000..a96237df0 --- /dev/null +++ b/qt4/spec/generic-types.xml @@ -0,0 +1,43 @@ +<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 since 1970</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Bus_Name" type="s"> + <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_Unique_Name" type="s"> + <tp:docstring>A string representing a D-Bus unique name, such as + ":1.123"</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Interface" type="s"> + <tp:docstring>A string representing a D-Bus interface</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:mapping name="String_Variant_Map"> + <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"> + <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:generic-types> |