diff options
author | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2011-01-07 01:08:02 -0200 |
---|---|---|
committer | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2011-01-07 18:27:15 -0200 |
commit | cf6fee0bf643c65956e2ab20ea50666833a0e3af (patch) | |
tree | c13fd20a1da3e1d8b4170aa754fb12a3b2e36c08 /spec |
Start developement.
Diffstat (limited to 'spec')
102 files changed, 32880 insertions, 0 deletions
diff --git a/spec/Account.xml b/spec/Account.xml new file mode 100644 index 0000000..acd8c30 --- /dev/null +++ b/spec/Account.xml @@ -0,0 +1,733 @@ +<?xml version="1.0" ?> +<node name="/Account" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Account"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An Account object encapsulates the necessary details to make a + Telepathy connection.</p> + + <p>Accounts are uniquely identified by object path. The object path + of an Account MUST take the form + <code>/org/freedesktop/Telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p> + + <ul> + <li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type> + that appears in the connection manager's well-known bus name and + object path</li> + <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>, + but with "-" replaced with "_" + (i.e. the same as in the object-path of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li> + <li><em>acct</em> is an arbitrary string of ASCII letters, digits + and underscores, starting with a letter or underscore, which + uniquely identifies this account</li> + <li>Clients SHOULD parse the object path to discover the + connection manager and protocol</li> + <li>Clients MUST NOT attempt to parse <em>acct</em></li> + <li>Clients MUST NOT assume that <em>acct</em> matches + the connection-specific part of a Connection's object-path and + bus name</li> + <li>The account manager SHOULD choose <em>acct</em> such that if + an account is deleted, its object path will be re-used if and only + if the new account is in some sense "the same" + (incorporating the 'account' parameter in some way is + recommended)</li> + </ul> + + <tp:rationale> + <p>This API avoids specifying the "profiles" used in Mission Control + 4.x or the "presets" that have been proposed to replace them. An + optional interface will be provided for AM implementations + that want to provide presets.</p> + + <p>There is deliberately no functionality here for opening channels; + we intend to provide that in the channel dispatcher.</p> + + <p>Other missing features which would be better in their own + interfaces:</p> + + <ul> + <li>dynamic parameter-providing (aka provisioning)</li> + <li>saved server capabilities</li> + <li>account conditions</li> + <li>account grouping</li> + </ul> + </tp:rationale> + + </tp:docstring> + <tp:added version="0.17.2"/> + <tp:changed version="0.17.6">moved the Avatar property to a separate + interface</tp:changed> + + <!-- Missing functionality compared with NMC 4.x account + profile, + apart from as listed above: + + * vCard field, + default profile for each vCard field + (vCard field is per protocol and should be chosen by the + Telepathy <-> address-book bridge?; default profile is now + meaningless) + + * "normalized name" (normalized handle?) + + * branding icon (what's this and how does it differ from the icon?) + + * configuration UI (not our problem - perhaps the UI could special-case + by cm,protocol,preset tuples?) + + * default account domain (somewhat meaningless in general; specialized + account config UI can hard-code this) + + * SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol, + not the profile, and in any case only the account config UI cares) + + Missing functionality compared with Decibel accounts: + + * we don't really know, they take arbitrary key/value pairs... + but display name, protocol, presence/message, current, autoreconnect + are the ones given special status by the source, and we have all of them + --> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:docstring> + A list of the extra interfaces provided by this account. + </tp:docstring> + </property> + + <method name="Remove" tp:name-for-bindings="Remove"> + <tp:docstring>Delete the account.</tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <signal name="Removed" tp:name-for-bindings="Removed"> + <tp:docstring> + This account has been removed. + + <tp:rationale> + This is redundant with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>, + but it's still worth having, + to avoid having to bind to AccountManager.AccountRemoved to tell + you whether your Account is valid — ideally, an account-editing UI + should only care about a single Account. + </tp:rationale> + </tp:docstring> + </signal> + + <signal name="AccountPropertyChanged" + tp:name-for-bindings="Account_Property_Changed"> + <tp:docstring> + The values of one or more properties on this interface (that do not + specify that this signal does not apply to them) may have changed. + This does not cover properties of other interfaces, which must + provide their own change notification if appropriate. + </tp:docstring> + + <arg name="Properties" type="a{sv}"> + <tp:docstring> + A map from property names in this namespace (e.g. + <tp:member-ref>Nickname</tp:member-ref>) to + values. Properties whose values have not changed SHOULD be + omitted, but this need not be done. + </tp:docstring> + </arg> + </signal> + + <property name="DisplayName" type="s" access="readwrite" + tp:name-for-bindings="Display_Name"> + <tp:docstring> + The user-visible name of this account. This SHOULD be chosen by the + user at account creation time. The account creation user interface + is responsible for setting a reasonable default value in the user's + locale; something like "Jabber (bob@example.com)" would be sensible. + + <tp:rationale> + This approximately corresponds to "display name" in NMC 4.x and + Decibel. + </tp:rationale> + </tp:docstring> + </property> + + <property name="Icon" tp:name-for-bindings="Icon" + type="s" access="readwrite"> + <tp:docstring> + The name of an icon in the system's icon theme, such as "im-msn", + or the empty string to not specify an icon. If the icon is set to + an empty string, the account manager or any client MAY derive a + default icon, for instance from the protocol. + + <tp: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" tp:name-for-bindings="Valid" + type="b" access="read"> + <tp:docstring> + If true, this account is considered by the account manager to be + complete and usable. If false, user action is required to make it + usable, and it will never attempt to connect (for instance, this + might be caused by the absence of a required parameter). + + <tp:rationale> + For connection managers with a plugin architecture, like + telepathy-haze, we have little or no control over the parameters + offered; for platforms with package management, we have little or + no control over the CMs offered. NMC 4.x would just pretend the + account didn't exist in these circumstances, but silent data loss + is bad, and UIs with CM-specific knowledge (or a user filling in + newly-required parameters) might be able to rescue a broken account. + </tp:rationale> + </tp:docstring> + </property> + + <property name="Enabled" tp:name-for-bindings="Enabled" + type="b" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This property gives the users the possibility to prevent an account + from being used. This flag does not change the validity of the + account.</p> + + <p>A disabled account can never be put online.</p> + + <tp:rationale> + <p>Use cases:</p> + + <ul> + <li>user has two or more accounts capable of calling contact X, but + he doesn't want the UI to prompt him everytime about which one he + wants to use for the call. He can then disable all the equivalent + accounts but one.</li> + + <li>There is some temporary server error and the user doesn't want + to be be bother by error messages, or change the account + configuration: temporarily disabling the account is quicker.</li> + </ul> + </tp:rationale> + + <p>The AccountManager SHOULD allow this property to be set on invalid + accounts, but MUST NOT attempt to put invalid accounts online + even if they become Enabled.</p> + + <tp:rationale> + <p>There doesn't seem to be any good reason not to allow this.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="Nickname" tp:name-for-bindings="Nickname" + type="s" access="readwrite"> + <tp:docstring> + The nickname to set on this account for display to other contacts, + as set by the user. When the account becomes connected, the + account manager SHOULD set this as the user's alias using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> + if appropriate. + + <tp:rationale> + In a later specification revision, we plan to separate the concepts + of a contact's nickname as set by themselves, and the local + name for them in our contact list (a "handle" or "pet name" as + described in XEP-0165 and its references). The terminology change + from alias to nickname here is a step in that direction. + This corresponds to NMC 4.x mc_account_get_alias. + </tp:rationale> + </tp:docstring> + </property> + + <property name="Service" tp:name-for-bindings="Service" type="s" + access="readwrite"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some protocols, like XMPP and SIP, are used by various different + user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by + Nokia</i>. On accounts for such services, this property SHOULD be + set to a string describing the service, which MUST consist only of + ASCII letters, numbers and hyphen/minus signs, and start with a + letter (matching the requirements for <tp:type>Protocol</tp:type>). + For the <tt>jabber</tt> protocol, one of the following service names + should be used if possible:</p> + + <ul> + <li><tt>google-talk</tt> (for <a + href="http://www.google.com/talk/">Google's IM service</a>)</li> + <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM + service)</li> + <li><tt>facebook</tt> (for <a + href="http://www.facebook.com/sitetour/chat.php">Facebook's IM + service</a>)</li> + <li><tt>lj-talk</tt> (for <a + href="http://www.livejournal.com/chat/">LiveJournal's IM + service</a>)</li> + + </ul> + + <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a + corresponding brand-specific icon name, if possible. In the future, + this property may be used as an index into additional + service-specific customizations. If this property is the empty string + (or missing), the service is determined by the protocol name (either + because this is a single-service protocol like <tt>msn</tt>, or + because this is just a generic <tt>jabber</tt> or <tt>sip</tt> + account without specific branding).</p> + + <p>This property MAY be set, if appropriate, when calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.AccountManager" + >CreateAccount</tp:dbus-ref>. Updating this property will fail on + externally-stored accounts whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Storage" + >StorageRestrictions</tp:dbus-ref> include + <code>Cannot_Set_Service</code>.</p> + </tp:docstring> + </property> + + <property name="Parameters" tp:name-for-bindings="Parameters" + type="a{sv}" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from connection manager parameter names (as in the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref> + interface) to their values. This property includes + only those parameters that are stored for this account, and SHOULD + only include those parameters that the user has explicitly set. + </p> + <p>This property cannot be altered using Set() - use + <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p> + </tp:docstring> + </property> + + <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref> + property.</p> + + <p>If any of the changed parameters' + <tp:type>Conn_Mgr_Param_Flags</tp:type> include + <code>DBus_Property</code>, the change will be applied immediately to + the + corresponding D-Bus Property on the active + <tp:member-ref>Connection</tp:member-ref>, if there is one. Changes to + other parameters will not take effect until the next time the account + is disconnected and reconnected.</p> + + <tp:rationale> + <p>In general, reconnecting is a destructive operation that shouldn't + happen as a side-effect. In particular, migration tools that + twiddle the settings of all accounts shouldn't cause an automatic + disconnect and reconnect.</p> + </tp:rationale> + </tp:docstring> + + <tp:changed version="0.17.16"> + parameters which are also D-Bus properties can and should be updated on + existing Connections + </tp:changed> + + <tp:changed version="0.17.24"> + return an array of the parameters that won't change until the account + is reconnected + </tp:changed> + + <arg name="Set" type="a{sv}" direction="in"> + <tp:docstring> + A mapping from parameter names to their values. These parameters + should be stored for future use. + </tp:docstring> + </arg> + + <arg name="Unset" type="as" direction="in"> + <tp:docstring> + A list of the names of parameters to be removed from the set of + stored values, allowing the default values to be used. + If the given parameters were not, in fact, stored, or even if they + do not exist at all, the account manager MUST accept this without + error. + </tp:docstring> + </arg> + + <arg name="Reconnect_Required" type="as" direction="out"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If all of the parameters had the <code>DBus_Property</code> flag, + the empty list, signifying that no reconnection is required for the + new parameters to take effect. For example, if the only parameter + updated is <tt>...Cellular.<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>, + the new value can be applied immediately to the connection.</p> + + <p>Otherwise, a list of the names of parameters with changes that + will not take effect until the account is reconnected. User + interfaces that require "instant apply" semantics MAY call + <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a + non-empty list. For example, if the caller updates both + <tt>...Anonymity.<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt> + and <tt>require-encryption</tt>, the former can be applied to the + current connection, but the latter needs a reconnect to take + effect, so this method should return + <code>["require-encryption"]</code>.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + + <property name="AutomaticPresence" type="(uss)" access="readwrite" + tp:type="Simple_Presence" tp:name-for-bindings="Automatic_Presence"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The presence status that this account should have if it is brought + online.</p> + + <tp:rationale> + In ITOS2007 and ITOS2008 this is a global preference, not visible + on D-Bus (the "default presence"). "Automatic presence" better + describes when it is used. + </tp:rationale> + + <p>Setting this property MUST NOT actually change the account's + status until the next time it is (re)connected for some reason.</p> + + <p>The value of this property MUST be one that would be acceptable + for <tp:member-ref>RequestedPresence</tp:member-ref>, + with the additional restriction that the + <tp:type>Connection_Presence_Type</tp:type> MUST NOT be Offline.</p> + + <tp:rationale> + <p>Otherwise, it would not be possible to use this presence to bring + the account online for a channel request.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectAutomatically" type="b" access="readwrite" + tp:name-for-bindings="Connect_Automatically"> + <tp:docstring> + If true, the account manager SHOULD attempt to put this account + online with the <tp:member-ref>AutomaticPresence</tp:member-ref> + whenever possible (in the base + Account interface this is deliberately left vague). If false, + it MUST NOT put the account online automatically in response to, + for instance, connectivity changes, but SHOULD still put the account + online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if + requested by the user (for + instance, if the user tries to start a conversation using this + account). + + <tp:rationale> + This approximately corresponds to NMC 4.x "enabled" and Decibel + "autoreconnect". + </tp:rationale> + </tp:docstring> + </property> + + <property name="Connection" tp:name-for-bindings="Connection" + type="o" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the object path of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to + this account, or the special value <code>'/'</code> if there is no + connection.</p> + + <p>If this object path is not '/', the Connection's well-known bus + name can be derived from this object path by removing the first '/' + and replacing subsequent '/' characters with '.'.</p> + + <tp:rationale> + Object paths aren't nullable, so we can't use an empty string. + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionStatus" type="u" tp:type="Connection_Status" + access="read" tp:name-for-bindings="Connection_Status"> + <tp:docstring> + If the <tp:member-ref>Connection</tp:member-ref> property is non-empty, + the status of that connection. + If the Connection property is the empty string, this property may + either be Disconnected (indicating that the account manager is not + attempting to bring it online), or Connecting (indicating that the + account manager is attempting to connect). + The account manager is expected to set this by observing signals + from the Connection. + + <tp:rationale> + If the AM is doing some sort of backoff/delay on reconnection + attempts, the account's status is conceptually "Connecting" even + though there is no Connection. This vaguely corresponds to + GetCurrentStatus in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionStatusReason" type="u" + tp:type="Connection_Status_Reason" access="read" + tp:name-for-bindings="Connection_Status_Reason"> + <tp:docstring> + The reason for the last change to + <tp:member-ref>ConnectionStatus</tp:member-ref>. + The account manager is expected to set this by observing signals + from the Connection. + + <tp:rationale> + If you weren't watching the Connection at the time it failed, + you can't tell why - unless the AM can tell you. This is part + of GetCurrentStatus in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionError" tp:name-for-bindings="Connection_Error" + access="read" type="s" tp:type="DBus_Error_Name"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the last connection to this account failed with an error, + the D-Bus error name of that error; otherwise, the empty string. + The account manager is expected to set this by observing the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.ConnectionError</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.StatusChanged</tp:dbus-ref> + signals.</p> + + <p>If ConnectionError is received before the connection disconnects, + its first argument should be used to set this property; + otherwise, the Reason argument of StatusChanged should be converted + to a suitable D-Bus error name.</p> + + <p>Whenever the Connection connects successfully, this property should + be reset to the empty string.</p> + + <tp:rationale> + <p>This combines the state-recoverability of + <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the + extensibility of Connection.ConnectionError.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionErrorDetails" + tp:name-for-bindings="Connection_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the last connection to this account failed with an error, + a mapping representing any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>Whenever the Connection connects successfully, this property should + be reset to the empty map.</p> + + <tp:rationale> + <p>This combines the state-recoverability of + <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the + extensibility of Connection.ConnectionError.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="CurrentPresence" type="(uss)" access="read" + tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence"> + <tp:docstring> + The actual presence. If the connection is not online, the + <tp:type>Connection_Presence_Type</tp:type> SHOULD be + Connection_Presence_Type_Offline. + If the connection is online but does not support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + interface, the type SHOULD be Connection_Presence_Type_Unset. + The account manager is expected to set this by observing signals + from the Connection. + + <tp:rationale> + This corresponds to GetPresenceActual in NMC 4.x. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RequestedPresence" type="(uss)" access="readwrite" + tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requested presence for this account. When this is changed, the + account manager should attempt to manipulate the connection manager to + make <tp:member-ref>CurrentPresence</tp:member-ref> match + <tp:member-ref>RequestedPresence</tp:member-ref> as closely as + possible. It should not be saved to any sort of persistent + storage.</p> + + <p>When the account manager automatically connects an account, + it must signal this by setting the RequestedPresence to the same + thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p> + + <tp:rationale> + This corresponds to e.g. GetPresence and GetPresenceMessage + in NMC 4.x. + </tp:rationale> + + <p>The <tp:type>Connection_Presence_Type</tp:type> in this property + MUST NOT be Unset, Unknown or Error.</p> + + <tp:rationale> + <p>Requesting those presence types doesn't make sense.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, a change to the presence of this account is + in progress.</p> + + <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on + an account that could go online, or whenever an account with a + non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes + able to go online (for instance because + <tp:member-ref>Enabled</tp:member-ref> or + <tp:member-ref>Valid</tp:member-ref> changes to True), + ChangingPresence MUST change to True, and the two property changes MUST + be emitted in the same + <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the + Set method returns.</p> + + <p>When the account manager succeeds or fails in changing the presence, + or the connection disconnects due to an error, ChangingPresence MUST + change to False as part of the same + <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p> + + <tp:rationale> + <p>This allows UIs to indicate that a presence change is in progress + or has finished, even if the change was initiated by a different + UI.</p> + + <p>For instance, Maemo 5 and Empathy indicate a presence change by + having the presence indicator alternate between the + <tp:member-ref>RequestedPresence</tp:member-ref> + and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should + start blinking when ChangingPresence becomes true, and stop when it + becomes false.</p> + </tp:rationale> + + </tp:docstring> + </property> + + <method name="Reconnect" tp:name-for-bindings="Reconnect"> + <tp:added version="0.17.24"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Re-connect this account. If the account is currently disconnected + and the requested presence is offline, or if the account + is not <tp:member-ref>Enabled</tp:member-ref> or not + <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p> + + <p>If the account is disconnected and the requested presence is not + offline, this forces an attempt to connect with the requested + presence immediately.</p> + + <p>If the account is connecting or connected, this is equivalent to + remembering the current value of + <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value + to (OFFLINE, "offline", ""), waiting for the change to take effect, + then setting its value to the value that was previously + remembered.</p> + + <tp:rationale> + <p>Clients desiring "instant apply" semantics for CM parameters MAY + call this method to achieve that.</p> + </tp:rationale> + + <p>In particular, if the account's + <tp:member-ref>Connection</tp:member-ref> is in the Connecting + state, calling this method causes the attempt to connect to be + aborted and re-tried.</p> + + <tp:rationale> + <p>This is necessary to ensure that the new parameters are + picked up.</p> + </tp:rationale> + </tp:docstring> + </method> + + <property name="NormalizedName" type="s" access="read" + tp:name-for-bindings="Normalized_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The normalized user ID of the local user on this account (i.e. the + string returned when the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> + method is called on the + result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref> + for an active connection).</p> + + <p>It is unspecified whether this user ID is globally unique.</p> + + <tp:rationale> + <p>As currently implemented, IRC user IDs are only unique within + the same IRCnet. On some saner protocols, the user ID includes a + DNS name which provides global uniqueness.</p> + </tp:rationale> + + <p>If this value is not known yet (which will always be the case for + accounts that have never been online), it will be an empty + string.</p> + + <p>It is possible that this value will change if the connection + manager's normalization algorithm changes, although this SHOULD + be avoided.</p> + + <tp:rationale> + <p>It's not always completely clear what normalization algorithm + should be used; for instance, in Gabble, we currently use JIDs, + but it would also have been reasonable to use xmpp URIs.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="HasBeenOnline" tp:name-for-bindings="Has_Been_Online" + type="b" access="read"> + <tp:docstring> + If true, this account has successfully been put online at some point + in the past. + + <tp:rationale> + UIs could apply a policy that the 'account' parameter can only be + edited in accounts that have never been online, or that + ConnectAutomatically cannot be set on such accounts. The account + manager should not enforce such policies, but it can expose enough + information to UIs that the UI can decide what to do. + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml new file mode 100644 index 0000000..4b2846b --- /dev/null +++ b/spec/Account_Interface_Addressing.xml @@ -0,0 +1,76 @@ +<?xml version="1.0" ?> +<node name="/Account_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Ltd</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Account.Interface.Addressing"> + <tp:requires interface="org.freedesktop.Telepathy.Account"/> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some accounts can be used for multiple protocols; for instance, SIP + and Skype accounts can often be used to contact the PSTN, MSN and + Yahoo accounts can contact each other, and XMPP accounts can + potentially contact many protocols via a transport.</p> + <p>However, if the user does not intend to make use of this functionality, + user interfaces can improve clarity by not displaying it: for instance, + if a user prefers to call phone numbers via a particular SIP account, + when an address book displays a contact with a phone number, it is + desirable to display a "call with SIP" button for that account, but + avoid displaying similar buttons for any other configured SIP or + Skype accounts.</p> + <p>The purpose of this interface is to allow this "for use with" information + to be recorded and retrieved.</p> + </tp:docstring> + + <property name="URISchemes" type="as" access="read" + tp:name-for-bindings="URI_Schemes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of fields indicating the type of URI addressing scheme + the the account should be used for (eg 'tel') indicating the + account is intended for use by applications offering a telephony + UI, or 'sip' or 'xmpp' for those protocols</p> + <p>Note that these fields signify intent, not ability: It is + entirely possible that an account which can be used for a + given URI scheme is not wanted for it by the user, and + therefore not flagged as such in this field.</p> + </tp:docstring> + </property> + + <method name="SetURISchemeAssociation" + tp:name-for-bindings="Set_URI_Scheme_Association"> + <tp:docstring> + <p>Associate (or disassociate) an account with a particular + URI addressing scheme, (such as 'tel' for telephony)</p> + </tp:docstring> + + <arg name="URI_Scheme" direction="in" type="s"> + <tp:docstring> + <p>URI scheme to associate/disassociate the account with/from</p> + </tp:docstring> + </arg> + + <arg name="Association" direction="in" type="b"> + <tp:docstring> + <p>True to associate this account with a given addressing scheme</p> + <p>False if the account should not be associated with said scheme</p> + </tp:docstring> + </arg> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml new file mode 100644 index 0000000..6c85b8e --- /dev/null +++ b/spec/Account_Interface_Avatar.xml @@ -0,0 +1,76 @@ +<?xml version="1.0" ?> +<node name="/Account_Interface_Avatar" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Account.Interface.Avatar"> + <tp:requires interface="org.freedesktop.Telepathy.Account"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface extends the core Account interface to provide a + user-settable avatar image.</p> + + <tp:rationale> + <p>The avatar could have been a property on the core Account interface, + but was moved to a separate interface because it is likely to be + large. This means that clients can safely use GetAll to get + properties on the core Account interface without flooding the + session bus with large images.</p> + </tp:rationale> + + </tp:docstring> + <tp:added version="0.17.6"/> + + <tp:struct name="Avatar"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A struct containing avatar data marked with its MIME type.</p> + </tp:docstring> + <tp:member type="ay" name="Avatar_Data"/> + <tp:member type="s" name="MIME_Type"/> + </tp:struct> + + <property name="Avatar" tp:name-for-bindings="Avatar" + type="(ays)" tp:type="Avatar" access="readwrite"> + <tp:docstring> + The avatar to set on this account for display to other contacts, + represented as a structure containing the bytes of the avatar, + and the MIME type as a string; may be set to an empty byte-array and + an empty string to indicate no avatar. When the account becomes + connected, the account manager SHOULD set this avatar using SetAvatar + if appropriate. + + <tp:rationale> + This corresponds to NMC 4.x mc_account_get_avatar. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="AvatarChanged" tp:name-for-bindings="Avatar_Changed"> + <tp:docstring> + Emitted when the Avatar property changes. + + <tp:rationale>The avatar itself is deliberately not included in this + signal, to reduce bus traffic in the (likely common) case where no + running application cares about the user's own avatar.</tp:rationale> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Interface_Storage.xml b/spec/Account_Interface_Storage.xml new file mode 100644 index 0000000..4e3ba5d --- /dev/null +++ b/spec/Account_Interface_Storage.xml @@ -0,0 +1,169 @@ +<?xml version="1.0" ?> +<node name="/Account_Interface_Storage" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Account.Interface.Storage"> + <tp:requires interface="org.freedesktop.Telepathy.Account"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + This interface extends the core Account interface to specify details + regarding the storage of this account. + </p> + + <tp:rationale> + <p> + Single-sign-on systems do not generally have directly user-editable + properties for Accounts, and require the user to visit a specific UI + to alter their account properties. User interfaces should know not to + expose these account properties as user-editable, and instead + redirect the user to the appropriate interface. + </p> + </tp:rationale> + + </tp:docstring> + <tp:added version="0.19.8"/> + + <property name="StorageProvider" tp:name-for-bindings="Storage_Provider" + type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The name of the account storage implementation, which SHOULD start + with a reversed domain name in the same way as D-Bus interface names. + When this is the empty string the account is internally stored. + </p> + <p> + This property cannot change once an Account has been created. + </p> + </tp:docstring> + </property> + + <property name="StorageIdentifier" + tp:name-for-bindings="Storage_Identifier" type="v" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Unique identification of the account within the storage backend. + The contents of the variant are defined by the + <tp:member-ref>StorageProvider</tp:member-ref>. + </p> + <p> + This property cannot change once an Account has been created. + </p> + <tp:rationale> + <p> + Different storage systems will have their own way of uniquely + identifying an account, typically an integer or a string. + Given that all users of this property should have direct knowledge + of the backend they should know what types to expect and how to + handle it. + </p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="StorageSpecificInformation" + tp:name-for-bindings="Storage_Specific_Information" type="a{sv}" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Map containing information specific to the storage backend. The keys + and the types of their values are defined by the + <tp:member-ref>StorageProvider</tp:member-ref>, and are not + interpreted by the AccountManager implementation. + </p> + <p> + As the values in this map may change at any time (due to an external + application manipulating the storage provider directly), this + property should not be cached; it should instead be retrieved each + time it is needed. + </p> + + <tp:rationale> + <p> + This can be used to provide additional hints to user interfaces + aware of a specific storage provider, without requiring those user + interfaces to use the + <tp:member-ref>StorageIdentifier</tp:member-ref> to query the + storage provider directly. + </p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="StorageRestrictions" + tp:name-for-bindings="Storage_Restrictions" type="u" + tp:type="Storage_Restriction_Flags" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Bitfield which defines what restrictions this Storage method has. + </p> + <p> + This property cannot change once an Account has been created. + </p> + </tp:docstring> + </property> + + <tp:flags name="Storage_Restriction_Flags" + value-prefix="Storage_Restriction_Flag" type="u"> + <tp:docstring> + Flags indicating restrictions imposed on an Account by its storage + method. + </tp:docstring> + + <tp:flag suffix="Cannot_Set_Parameters" value="1"> + <tp:docstring> + The account's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >Parameters</tp:dbus-ref> property can't be changed by calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Enabled" value="2"> + <tp:docstring> + The account can't be enabled/disabled by setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >Enabled</tp:dbus-ref> property. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Presence" value="4"> + <tp:docstring> + The account's presence can't be changed by setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >AutomaticPresence</tp:dbus-ref> properties. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Service" value="8"> + <tp:docstring> + The account's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref> + property cannot be changed. + </tp:docstring> + </tp:flag> + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml new file mode 100644 index 0000000..cd82e7f --- /dev/null +++ b/spec/Account_Manager.xml @@ -0,0 +1,296 @@ +<?xml version="1.0" ?> +<node name="/Account_Manager" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.AccountManager"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The account manager is a central service used to store account + details.</p> + + <p>The current account manager is defined to be the process that owns + the well-known bus name org.freedesktop.Telepathy.AccountManager on + the session bus. This process must export an + /org/freedesktop/Telepathy/AccountManager object with the + AccountManager interface.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of AccountManager implementation, implementations SHOULD NOT + register as an activatable service for the AccountManager's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs can + detect whether Telepathy is in use by checking whether the + AccountManager's well-known name is in use at runtime.</p> + </tp:docstring> + <tp:added version="0.17.2"/> + + <!-- Missing functionality compared with NMC 4.x: + * look up accounts by conditions (can be done client-side, less + efficiently, so not a blocker) + * global presence/... changes (can be done client-side, less efficiently - + we should add this) + * count used channels (what's this for?) + * get "average" status (not well-defined, UIs can do this) + * request channels (out of scope: Channel Dispatcher will do this) + * register filters (completely out of scope: Channel Dispatcher again) + --> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:docstring> + A list of the interfaces provided by the account manager object. + </tp:docstring> + </property> + + <property name="ValidAccounts" type="ao" access="read" + tp:name-for-bindings="Valid_Accounts"> + <tp:docstring> + A list of the valid (complete, usable) <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change + notification is via + <tp:member-ref>AccountValidityChanged</tp:member-ref>. + + <tp:rationale> + This split between valid and invalid accounts makes it easy to + ignore the invalid ones. The only things that should be manipulating + invalid accounts are account-editing UIs, which might be able to + rescue them. + </tp:rationale> + </tp:docstring> + </property> + + <property name="InvalidAccounts" type="ao" access="read" + tp:name-for-bindings="Invalid_Accounts"> + <tp:docstring> + A list of incomplete or otherwise unusable <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change + notification is via + <tp:member-ref>AccountValidityChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="AccountRemoved" tp:name-for-bindings="Account_Removed"> + <tp:docstring> + The given account has been removed. + + <tp:rationale> + This is effectively change notification for the valid and invalid + accounts lists. On emission of this signal, the Account indicated + will no longer be present in either of the lists. + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o"> + <tp:docstring> + An Account, which must not be used any more. + </tp:docstring> + </arg> + </signal> + + <signal name="AccountValidityChanged" + tp:name-for-bindings="Account_Validity_Changed"> + <tp:docstring> + The validity of the given account has changed. New accounts are + also indicated by this signal, as an account validity change + (usually to True) on an account that did not previously exist. + + <tp:rationale> + This is effectively change notification for the valid and invalid + accounts lists. + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o"> + <tp:docstring> + An <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Valid" type="b"> + <tp:docstring> + True if the account is now valid. + </tp:docstring> + </arg> + </signal> + + <property name="SupportedAccountProperties" + tp:name-for-bindings="Supported_Account_Properties" + type="as" tp:type="DBus_Qualified_Member[]" access="read"> + <tp:added version="0.17.24"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the fully qualified names of properties that can be set + via the Properties argument to + <tp:member-ref>CreateAccount</tp:member-ref> when an account is + created.</p> + + <tp:rationale> + <p>Examples of good properties to support here include + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>. + </p> + + <p>Examples of properties that would make no sense here include + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>. + </p> + </tp:rationale> + + <p>This property MUST NOT include include the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> + properties, which are set using separate arguments.</p> + + <p>This property MAY include the names of properties that, after + account creation, will be read-only: this indicates that the property + can be set at account creation but not changed later.</p> + + <tp:rationale> + <p>For example, an account manager might support migration tools that + use this to preserve the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref> + property, even though that property is usually read-only.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="CreateAccount" tp:name-for-bindings="Create_Account"> + <tp:docstring> + Request the creation of a new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The + account manager SHOULD NOT allow invalid accounts to be created. + </tp:docstring> + <tp:changed version="0.17.24">added the Properties argument</tp:changed> + + <arg name="Connection_Manager" direction="in" type="s" + tp:type="Connection_Manager_Name"> + <tp:docstring> + The name of the connection manager, e.g. "salut". + </tp:docstring> + </arg> + + <arg name="Protocol" direction="in" type="s" + tp:type="Protocol"> + <tp:docstring>The protocol, e.g. "local-xmpp".</tp:docstring> + </arg> + + <arg name="Display_Name" direction="in" type="s"> + <tp:docstring>The initial value of the new account's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> + property. The account manager SHOULD modify this to make it unique if + an Account already exists with the same display name, for instance by + appending a number or the 'account' parameter. Account manager + implementations SHOULD accept an empty string, but account editing + user interfaces should avoid passing an empty string for this + parameter. + + <tp:rationale> + <p>The account creation UI may ask the user for a name for the new + account. If the author of the UI chooses not to do this, the + account creation UI is better able to suggest a default display + name because it has protocol-specific knowledge which the account + manager does not.</p> + + <p>The account manager always knows the complete list of accounts so + it can easily tell whether it should append something to the + display name to avoid presenting two identically-named accounts to + the user.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Parameters" direction="in" type="a{sv}"> + <tp:docstring>Initial parameter values, as would be passed to + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring> + </arg> + + <arg name="Properties" direction="in" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The values of any other properties to be set immediately on the + new Account.</p> + + <p>Only the properties mentioned in + <tp:member-ref>SupportedAccountProperties</tp:member-ref> are + acceptable here. In particular, the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> + properties are never allowed here, since they are set using the other + arguments to this method.</p> + + <p>Account manager implementations SHOULD support creating accounts + with an empty value for this argument.</p> + </tp:docstring> + </arg> + + <arg name="Account" direction="out" type="o"> + <tp:docstring>The new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Connection_Manager is not installed or does not + implement the given Protocol, or one of the properties in the + Properties argument is unsupported.</p> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Parameters provided omit a required parameter + or provide unsupported parameter, or the type of one + of the Parameters or Properties is inappropriate.</p> + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> + diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 0000000..db1d76f --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,305 @@ +<?xml version="1.0" ?> +<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate"> + <tp:added version="0.19.13">(as stable API)</tp:added> + + <tp:docstring> + This object represents a TLS certificate. + </tp:docstring> + + <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List" + type="ay"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The raw data contained in a TLS certificate.</p> + + <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref> + = "x509"), this MUST be in DER format, as defined by the + <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a> + ITU standard.</p> + + <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref> + = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 + of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p> + </tp:docstring> + </tp:simple-type> + + <tp:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Struct representing one reason why a TLS certificate was rejected.</p> + <p>Since there can be multiple things wrong with a TLS certificate, + arrays of this type are used to represent lists of reasons for + rejection. In that case, the most important reason SHOULD be placed + first in the list.</p> + </tp:docstring> + + <tp:member name="Reason" type="u" + tp:type="TLS_Certificate_Reject_Reason"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The value of the TLS_Certificate_Reject_Reason enumeration for + this certificate rejection. + <tp:rationale> + Clients that do not understand the <code>Error</code> member, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + </tp:rationale> + </p> + </tp:docstring> + </tp:member> + + <tp:member name="Error" type="s" + tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The DBus error name for this certificate rejection.</p> + <p>This MAY correspond to the value of the <code>Reason</code> member, + or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p> + </tp:docstring> + </tp:member> + + <tp:member name="Details" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about why the certificate was rejected. + This MAY also include one or more of the following well-known keys:</p> + <p> + <dl> + <dt>user-requested (b)</dt> + <dd>True if the error was due to an user-requested rejection of + the certificate; False if there was an unrecoverable error in the + verification process.</dd> + <dt>expected-hostname (s)</dt> + <dd>If the rejection reason is Hostname_Mismatch, the hostname that + the server certificate was expected to have.</dd> + <dt>certificate-hostname (s)</dt> + <dd>If the rejection reason is Hostname_Mismatch, the hostname of + the certificate that was presented. + <tp:rationale> + <p>For instance, if you try to connect to gmail.com but are presented + with a TLS certificate issued to evil.example.org, the error details + for Hostname_Mismatch MAY include:</p> + <pre> + { + 'expected-hostname': 'gmail.com', + 'certificate-hostname': 'evil.example.org', + } + </pre> + </tp:rationale> + </dd> + <dt>debug-message (s)</dt> + <dd>Debugging information on the error, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + </dl> + </p> + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum type="u" name="TLS_Certificate_State"> + <tp:docstring> + The possible states for a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref> + object. + </tp:docstring> + + <tp:enumvalue suffix="Pending" value="0"> + <tp:docstring> + The certificate is currently waiting to be accepted or rejected. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Accepted" value="1"> + <tp:docstring> + The certificate has been verified. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Rejected" value="2"> + <tp:docstring> + The certificate has been rejected. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum type="u" name="TLS_Certificate_Reject_Reason"> + <tp:docstring> + Possible reasons to reject a TLS certificate. + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The certificate has been rejected for another reason + not listed in this enumeration. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Untrusted" value="1"> + <tp:docstring> + The certificate is not trusted. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Expired" value="2"> + <tp:docstring> + The certificate is expired. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Not_Activated" value="3"> + <tp:docstring> + The certificate is not active yet. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Fingerprint_Mismatch" value="4"> + <tp:docstring> + The certificate provided does not have the expected + fingerprint. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Hostname_Mismatch" value="5"> + <tp:docstring> + The hostname certified does not match the provided one. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Self_Signed" value="6"> + <tp:docstring> + The certificate is self-signed. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Revoked" value="7"> + <tp:docstring> + The certificate has been revoked. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Insecure" value="8"> + <tp:docstring> + The certificate uses an insecure cipher algorithm, or is + cryptographically weak. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Limit_Exceeded" value="9"> + <tp:docstring> + The length in bytes of the certificate, or the depth of the + certificate chain exceed the limits imposed by the crypto + library. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="State" type="u" access="read" + tp:type="TLS_Certificate_State" + tp:name-for-bindings="State"> + <tp:docstring> + The current state of this certificate. + State change notifications happen by means of the + <tp:member-ref>Accepted</tp:member-ref> and + <tp:member-ref>Rejected</tp:member-ref> signals. + </tp:docstring> + </property> + + <property name="Rejections" type="a(usa{sv})" access="read" + tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the <tp:member-ref>State</tp:member-ref> is Rejected, + an array of <tp:type>TLS_Certificate_Rejection</tp:type> + structures containing the reason why the certificate is rejected.</p> + <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected, + this property is not meaningful, and SHOULD be set to an empty + array.</p> + <p>The first rejection in the list MAY be assumed to be + the most important; if the array contains more than one + element, the CM MAY either use the values after the first, + or ignore them.</p> + </tp:docstring> + </property> + + <property name="CertificateType" type="s" access="read" + tp:name-for-bindings="Certificate_Type"> + <tp:docstring> + The type of this TLS certificate (e.g. 'x509' or 'pgp'). + <p>This property is immutable</p> + </tp:docstring> + </property> + + <property name="CertificateChainData" type="aay" access="read" + tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more TLS certificates forming a trust chain, each encoded as + specified by <tp:type>Certificate_Data</tp:type>.</p> + <p>The first certificate in the chain MUST be the server certificate, + followed by the issuer's certificate, followed by the issuer's issuer + and so on.</p> + </tp:docstring> + </property> + + <signal name="Accepted" + tp:name-for-bindings="Accepted"> + <tp:docstring> + The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted. + </tp:docstring> + </signal> + + <signal name="Rejected" + tp:name-for-bindings="Rejected"> + <tp:docstring> + The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected. + </tp:docstring> + <arg name="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]"> + <tp:docstring> + The new value of the <tp:member-ref>Rejections</tp:member-ref> property. + </tp:docstring> + </arg> + </signal> + + <method name="Accept" tp:name-for-bindings="Accept"> + <tp:docstring> + Accepts this certificate, i.e. marks it as verified. + </tp:docstring> + </method> + + <method name="Reject" tp:name-for-bindings="Reject"> + <tp:docstring> + Rejects this certificate. + </tp:docstring> + <arg direction="in" type="a(usa{sv})" name="Rejections" + tp:type="TLS_Certificate_Rejection[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p> + <p>This MUST NOT be an empty array.</p> + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref> + is not <code>Pending</code>, or when the provided rejection list is empty. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml new file mode 100644 index 0000000..17ed710 --- /dev/null +++ b/spec/Call_Content.xml @@ -0,0 +1,291 @@ +<?xml version="1.0" ?> +<node name="/Call_Content" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Content.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents one Content inside a <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For + example, in an audio/video call there would be one audio content + and one video content. Each content has one or more <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which + represent the actual transport to one or more remote contacts. + </tp:docstring> + + <tp:enum name="Content_Removal_Reason" type="u"> + <tp:added version="0.21.2"/> + <tp:docstring> + A representation of the reason for a content to be removed, + which may be used by simple clients, or used as a fallback + when the DBus_Reason is not understood. This enum will be + extended with future reasons as and when appropriate, so + clients SHOULD keep up to date with its values, but also be + happy to fallback to the Unknown value when an unknown value + is encountered. + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="User_Requested" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The local user requests that this content is removed + from the call.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Error" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There is an error with the content which means that it + has to be removed from the call.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Unsupported" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some aspect of the content is unsupported so has to be + removed from the call.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="Remove" tp:name-for-bindings="Remove"> + <tp:changed version="0.21.2">previously there were no + arguments</tp:changed> + <tp:docstring> + Remove the content from the call. + </tp:docstring> + + <arg direction="in" name="Reason" type="u" + tp:type="Content_Removal_Reason"> + <tp:docstring> + A generic hangup reason. + </tp:docstring> + </arg> + + <arg direction="in" name="Detailed_Removal_Reason" type="s" + tp:type="DBus_Error_Name"> + <tp:docstring> + A more specific reason for the content removal, if one is + available, or an empty string. + </tp:docstring> + </arg> + + <arg direction="in" name="Message" type="s"> + <tp:docstring> + A human-readable message for the reason of removing the + content, such as "Fatal streaming failure" or "no codec + intersection". This property can be left empty if no reason + is to be given. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised when a Call doesn't support removing contents + (e.g. a Google Talk video call). + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="Removed" tp:name-for-bindings="Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the content is removed from the call. This + is the same as the <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT.ContentRemoved</tp:dbus-ref> + signal.</p> + </tp:docstring> + </signal> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> + <tp:added version="0.19.11"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this content, such as <tp:dbus-ref + namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or + <tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>. + This SHOULD NOT include the Content interface itself, and cannot + change once the content has been created.</p> + </tp:docstring> + </property> + + <property name="Name" tp:name-for-bindings="Name" type="s" access="read" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the content.</p> + + <tp:rationale> + The content name property should be meaningful, so should be + given a name which is significant to the user. The name + could be the "audio" or "video" string localized, or perhaps + include some string identifying the source, such as a webcam + identifier. + </tp:rationale> + </tp:docstring> + </property> + + <property name="Type" tp:name-for-bindings="Type" + type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The media type of this content.</p> + </tp:docstring> + </property> + + <tp:enum name="Call_Content_Disposition" type="u"> + <tp:docstring> + The disposition of this content, which defines whether to + automatically start sending data on the streams when + <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is + called on the channel. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The content has no specific disposition + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Initial" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The content was initially part of the call. When + <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + is called on the channel, all streams of this content with + <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> + set to <tp:type>Sending_State</tp:type>_Pending_Send will be + moved to <tp:type>Sending_State</tp:type>_Sending as if + <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> + (True) had been called.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Disposition" tp:name-for-bindings="Disposition" + type="u" tp:type="Call_Content_Disposition" access="read" + tp:immutable="yes"> + <tp:docstring> + The disposition of this content. + </tp:docstring> + </property> + + <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added"> + <tp:changed version="0.21.2">plural version, renamed from + StreamAdded</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when streams are added to a call.</p> + </tp:docstring> + <arg name="Streams" type="ao"> + <tp:docstring> + The <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were + added. + </tp:docstring> + </arg> + </signal> + + <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed"> + <tp:changed version="0.21.2">plural version, renamed from + StreamRemoved</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when streams are removed from a call</p> + </tp:docstring> + <arg name="Streams" type="ao"> + <tp:docstring> + The <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were + removed. + </tp:docstring> + </arg> + </signal> + + <property name="Streams" tp:name-for-bindings="Streams" + type="ao" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of <tp:dbus-ref namespace="ofdT.Call" + >Stream.DRAFT</tp:dbus-ref> objects that exist in this + content.</p> + + <tp:rationale> + In a conference call multiple parties can share one media + content (say, audio), but the streaming of that media can + either be shared or separate. For example, in a multicast + conference all contacts would share one stream, while in a + Muji conference there would be a stream for each + participant. + </tp:rationale> + + <p>Change notification is through the + <tp:member-ref>StreamsAdded</tp:member-ref> and + <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p> + </tp:docstring> + </property> + + <tp:enum name="Call_Content_Packetization_Type" type="u"> + <tp:added version="0.21.2"/> + <tp:docstring> + A packetization method that can be used for a content. + </tp:docstring> + + <tp:enumvalue suffix="RTP" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Real-time Transport Protocol, as documented by RFC 3550. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Raw" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Raw media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="MSN_Webcam" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Packetization" tp:name-for-bindings="Packetization" + type="u" tp:type="Call_Content_Packetization_Type" access="read" + tp:immutable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The packetization method in use for this content.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml new file mode 100644 index 0000000..f88143f --- /dev/null +++ b/spec/Call_Content_Codec_Offer.xml @@ -0,0 +1,87 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Codec_Offer" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents an offer of a Codec payload mapping. + </tp:docstring> + + <method name="Accept" tp:name-for-bindings="Accept"> + <arg name="Codecs" direction="in" + type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The local codec mapping to send to the remote contacts and + to use in the <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. + </tp:docstring> + </arg> + <tp:docstring> + Accept the updated Codec mapping and update the local mapping. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The codecs given as the argument are invalid in some way. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Reject" tp:name-for-bindings="Reject"> + <tp:docstring> + Reject the proposed update to the codecs + FIXME add error codes and strings here + </tp:docstring> + </method> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this codec offer. This SHOULD + NOT include the CodecOffer interface itself, and cannot change + once the content has been created.</p> + </tp:docstring> + </property> + + <property name="RemoteContactCodecs" + tp:name-for-bindings="Remote_Contact_Codecs" + type="a(usuua{ss})" tp:type="Codec[]" access="read" + tp:immutable="yes"> + <tp:docstring> + A list of codecs the remote contact supports. + </tp:docstring> + </property> + + <property name="RemoteContact" tp:name-for-bindings="Remote_Contact" + type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes"> + <tp:docstring> + The contact handle that this codec offer applies to. + </tp:docstring> + </property> + + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml new file mode 100644 index 0000000..274d8b2 --- /dev/null +++ b/spec/Call_Content_Interface_Media.xml @@ -0,0 +1,331 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface to use by a software implementation of media + streaming. The reason behind splitting the members of this + interface out from the main <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is + that the software is not necessarily what controls the + media. An example of this is in GSM phones, where the CM just + tells the phone to dial a number and it does the audio routing + in a device specific hardware way and the CM does not need + to concern itself with codecs.</p> + + <h4>Codec negotiation</h4> + + <p>When a new <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel + appears, whether it was requested or not, a <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + will either be waiting in the + <tp:member-ref>CodecOffer</tp:member-ref> property, or will + appear at some point via the + <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p> + + <p>The <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + property on the codec offer lists the codecs which are + supported by the remote contact, and so will determine the + codecs that should be proposed by the local user's streaming + implementation. An empty list means all codecs can be proposed.</p> + + <p>For incoming calls on protocols where codecs are proposed when + starting the call (for example, <a + href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>), + the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + will contain information on the codecs that have already been + proposed by the remote contact, otherwise the codec map will + be the empty list.</p> + + <p>The streaming implementation should look at the remote codec + map and the codecs known by the local user and call + <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> + on the intersection of these two codec lists.</p> + + <p>This means that in practice, outgoing calls will have a codec + offer pop up with no information in the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + so the local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the list of all codecs supported. If this codec offer is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will fire with the details of the codecs passed into + <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If + the call is incoming, then the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + will contain details of the remote contact's codecs and the + local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the codecs that both sides understand. After the codec + set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref> + will fire to signal this change.</p> + + <h4>Protocols without codec negotiation</h4> + + <p>For protocols where the codecs are not negotiable, instead of + popping up the initial content's <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object with an empty <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + the CM should set the supported codec values to known codec + values in the said object's codec map.</p> + + <h4>Changing codecs mid-call</h4> + + <p>To update the codec list used mid-call, the + <tp:member-ref>UpdateCodecs</tp:member-ref> method should be + called with details of the new codec list. If this is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will be emitted with the new codec set.</p> + + <p>If the other side decides to update his or her codec list + during a call, a new <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object will appear through + <tp:member-ref>NewCodecOffer</tp:member-ref> which should be + acted on as documented above.</p> + + </tp:docstring> + + <tp:struct name="Codec" array-name="Codec_List"> + <tp:docstring> + A description of a codec. + </tp:docstring> + <tp:member name="Identifier" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Numeric identifier for the codec. This will be used as the PT in the + SDP or content description. + </tp:docstring> + </tp:member> + <tp:member name="Name" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The name of the codec. + </tp:docstring> + </tp:member> + <tp:member name="Clockrate" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The clockrate of the codec. + </tp:docstring> + </tp:member> + <tp:member name="Channels" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Number of channels of the codec if applicable, otherwise 0. + </tp:docstring> + </tp:member> + <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Extra parameters for this codec. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Codec_Map"> + <tp:docstring> + A map from contact to the list of codecs he or she supports. + </tp:docstring> + <tp:member name="Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle. + </tp:docstring> + </tp:member> + <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs that the contact supports. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Codec_Offering"> + <tp:docstring> + A codec offer and its corresponding remote contact codec map. + </tp:docstring> + <tp:member name="Codec_Offer" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> + </tp:docstring> + </tp:member> + <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The contact handle that this codec offer applies to. + </tp:docstring> + </tp:member> + <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})" + tp:type="Codec[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property + of the codec offer. + </tp:docstring> + </tp:member> + </tp:struct> + + <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the codecs in use change.</p> + + <p>As well as acting as change notification for the + <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this + signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> + property has changed to <code>('/', {})</code>.</p> + </tp:docstring> + <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" + tp:type="Contact_Codec_Map"> + <tp:docstring> + A map from contact to his or her codecs. Each pair in this + map is added to the + <tp:member-ref>ContactCodecMap</tp:member-ref> property, + replacing any previous pair with that key. + </tp:docstring> + </arg> + <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of keys which were removed from the + <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because + those contacts left the call. + </tp:docstring> + </arg> + </signal> + + <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> + <tp:docstring> + Update the local codec mapping. This method should only be + used during an existing call to update the codec mapping. + </tp:docstring> + <arg name="Codecs" direction="in" + type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs now supported by the local user. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Raised when a <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object exists and is referred to in the + <tp:member-ref>CodecOffer</tp:member-ref> property which + should be used instead of calling this method, or before + the content's initial <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object has appeared. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + <tp:docstring> + <p>A map from contact handles (including the local user's own handle) + to the codecs supported by that contact.</p> + + <p>Change notification is via the + <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming + implementation MUST respond by calling the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >Accept</tp:dbus-ref> or <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >Reject</tp:dbus-ref> method on the codec offer object.</p> + + <p>Emission of this signal indicates that the + <tp:member-ref>CodecOffer</tp:member-ref> property has changed to + <code>(Contact, Offer, Codecs)</code>.</p> + </tp:docstring> + <arg name="Contact" type="u"> + <tp:docstring> + The contact the codec offer belongs to. + </tp:docstring> + </arg> + <arg name="Offer" type="o"> + <tp:docstring> + The object path of the new codec offer. This replaces any previous + codec offer. + </tp:docstring> + </arg> + <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property + of the codec offer.</p> + + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. + </tp:rationale> + </tp:docstring> + </arg> + </signal> + + <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" + type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The object path to the current + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> object, its + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties. + If the object path is "/" then there isn't an outstanding + codec offer, and the mapping MUST be empty.</p> + + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContact</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContactCodecs</tp:dbus-ref> + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in + practice. + </tp:rationale> + + <p>Change notification is via the + <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the + value of this property with a new codec offer), and + <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that + there is no longer any active codec offer) signals.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml new file mode 100644 index 0000000..f926e03 --- /dev/null +++ b/spec/Call_Content_Interface_Mute.xml @@ -0,0 +1,85 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for calls which may be muted. This only makes sense + for channels where audio or video is streaming between members.</p> + + <p>Muting a call content indicates that the user does not wish to send + outgoing audio or video.</p> + + <p>Although it's client's responsibility to actually mute the microphone + or turn off the camera, using this interface the client can also + inform the CM and other clients of that fact.</p> + + <tp:rationale> + For some protocols, the fact that the content is muted needs + to be transmitted to the peer; for others, the notification + to the peer is only informational (eg. XMPP), and some + protocols may have no notion of muting at all. + </tp:rationale> + </tp:docstring> + + <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> + <tp:docstring> + Emitted to indicate that the mute state has changed for this call content. + This may occur as a consequence of the client calling + <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another + client has (un)muted the content. + </tp:docstring> + <arg name="MuteState" type="b"> + <tp:docstring> + True if the content is now muted. + </tp:docstring> + </arg> + </signal> + + <property name="MuteState" type="b" + access="read" tp:name-for-bindings="Mute_State"> + <tp:docstring> + True if the content is muted. + </tp:docstring> + </property> + + <method name="SetMuted" tp:name-for-bindings="Set_Muted"> + <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed> + <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed> + <arg direction="in" name="Muted" type="b"> + <tp:docstring> + True if the client has muted the content. + </tp:docstring> + </arg> + <tp:docstring> + <p>Inform the CM that the call content has been muted or unmuted by + the client.</p> + + <p>It is the client's responsibility to actually mute or unmute the + microphone or camera used for the content. However, the client + MUST call this whenever it mutes or unmutes the content.</p> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml new file mode 100644 index 0000000..1d7b281 --- /dev/null +++ b/spec/Call_Stream.xml @@ -0,0 +1,261 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Stream.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + One stream inside a <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. + </tp:docstring> + + <method name="SetSending" tp:name-for-bindings="Set_Sending"> + <tp:docstring> + Set the stream to start or stop sending media from the local + user to other contacts. + </tp:docstring> + + <arg name="Send" type="b" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If True, the + <tp:member-ref>LocalSendingState</tp:member-ref> should + change to <tp:type>Sending_State</tp:type>_Sending, if it isn't + already.</p> + + <p>If False, the + <tp:member-ref>LocalSendingState</tp:member-ref> should + change to <tp:type>Sending_State</tp:type>_None, if it isn't + already.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" /> + </tp:possible-errors> + </method> + + <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving"> + <tp:docstring> + <p>Request that a remote contact stops or starts sending on + this stream.</p> + + <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref> + property defines whether the protocol allows the local user to + request the other side start sending on this stream.</p> + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Contact from which sending is requested</p> + </tp:docstring> + </arg> + + <arg name="Receive" type="b" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, request that the given contact starts to send media. + If false, request that the given contact stops sending media.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request contact is valid but is not involved in this + stream. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The protocol does not allow the local user to request the + other side starts sending on this stream. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="RemoteMembersChanged" + tp:name-for-bindings="Remote_Members_Changed"> + <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed> + <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes. + </tp:docstring> + + <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map"> + <tp:docstring> + A mapping from channel-specific handles to their updated sending + state, whose keys include at least the members who were added, + and the members whose states changed. + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The channel-specific handles that were removed from the keys + of the <tp:member-ref>RemoteMembers</tp:member-ref> + property, as a result of the contact leaving this stream + </tp:docstring> + </arg> + </signal> + + <signal name="LocalSendingStateChanged" + tp:name-for-bindings="Local_Sending_State_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes. + </tp:docstring> + + <arg name="State" type="u" tp:type="Sending_State"> + <tp:docstring> + The new value of + <tp:member-ref>LocalSendingState</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Sending_State" type="u"> + <tp:docstring> + Enum indicating whether a contact is sending media. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + The contact is not sending media and has not been asked to + do so. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Pending_Send" value="1"> + <tp:docstring> + The contact has been asked to start sending media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Sending" value="2"> + <tp:docstring> + The contact is sending media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Pending_Stop_Sending" value="3"> + <tp:docstring> + The contact has been asked to stop sending media. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Contact_Sending_State_Map"> + <tp:docstring> + A map from a contact to his or her sending state. + </tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact handle. + </tp:docstring> + </tp:member> + <tp:member name="Sending" type="u" tp:type="Sending_State"> + <tp:docstring> + The sending state of the contact. + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> + <tp:added version="0.19.11"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this stream, such as <tp:dbus-ref + namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>. + This SHOULD NOT include the Stream interface itself, and cannot + change once the stream has been created.</p> + </tp:docstring> + </property> + + <property name="RemoteMembers" tp:name-for-bindings="Remote_Members" + type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> + <tp:changed version="0.21.2">renamed from Senders</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from remote contacts to their sending state. The + local user's sending state is shown in + <tp:member-ref>LocalSendingState</tp:member-ref>.</p> + + <p><tp:type>Sending_State</tp:type>_Pending_Send indicates + that another contact has asked the local user to send + media.</p> + + <p>Other contacts' handles in this map indicate whether they are + sending media to the contacts in this stream. + Sending_State_Pending_Send indicates contacts who are not sending but + have been asked to do so.</p> + </tp:docstring> + </property> + + <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State" + type="u" access="read" tp:type="Sending_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The local user's sending state. Media sent on this stream + should be assumed to be received, directly or indirectly, by + every other contact in the + <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change + notification is given via the + <tp:member-ref>LocalSendingStateChanged</tp:member-ref> + signal.</p> + + <tp:rationale> + Implementations of the first Call draft had the self handle + in the <tp:member-ref>RemoteMembers</tp:member-ref> (then + called Members) map and this showed that it's annoying + having to keep track of the self handle so that it can be + special-cased. + </tp:rationale> + + <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for + this property indicates that the other side requested the + local user start sending media, which can be done by calling + <tp:member-ref>SetSending</tp:member-ref>. When a call is + accepted, all initial contents with streams that have a + local sending state of + <tp:type>Sending_State</tp:type>_Pending_Send are + automatically set to sending. For example, on an incoming + call it means you need to <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + to start the actual call, on an outgoing call it might mean + you need to call <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + before actually starting the call.</p> + </tp:docstring> + </property> + + <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving" + type="b" access="read" tp:immutable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the user can request that a remote contact starts + sending on this stream.</p> + + <tp:rationale>Not all protocols allow the user to ask the + other side to start sending media.</tp:rationale> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml new file mode 100644 index 0000000..4818168 --- /dev/null +++ b/spec/Call_Stream_Endpoint.xml @@ -0,0 +1,182 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream_Endpoint" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This object represents an endpoint for a stream. In a one-to-one + call, there will be one (bidirectional) stream per content and + one endpoint per stream (as there is only one remote + contact). In a multi-user call there is a stream for each remote + contact and each stream has one endpoint as it refers to the one + physical machine on the other end of the stream.</p> + + <p>The multiple endpoint use case appears when SIP call forking + is used. Unlike jingle call forking (which is just making + multiple jingle calls to different resources appear as one + call), SIP call forking is actually done at the server so you + have one stream to the remote contact and then and endpoint for + each SIP client to be called.</p> + </tp:docstring> + + <property name="RemoteCredentials" + tp:name-for-bindings="Remote_Credentials" + type="(ss)" tp:type="Stream_Credentials" access="read"> + <tp:docstring> + The ICE credentials used for all candidates. If each candidate + has different credentials, then this property SHOULD be ("", + ""). Per-candidate credentials are set in the + <tp:type>Candidate</tp:type>'s + <tp:type>Candidate_Info</tp:type> a{sv}. + </tp:docstring> + </property> + + <signal name="RemoteCredentialsSet" + tp:name-for-bindings="Remote_Credentials_Set"> + <arg name="Username" type="s"> + <tp:docstring> + The username set. + </tp:docstring> + </arg> + <arg name="Password" type="s"> + <tp:docstring> + The password set. + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the remote ICE credentials for the endpoint are + set. If each candidate has different credentials, then this + signal will never be fired. + </tp:docstring> + </signal> + + <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates" + type="a(usqa{sv})" tp:type="Candidate[]" access="read"> + <tp:docstring> + A list of candidates for this endpoint. + </tp:docstring> + </property> + + <signal name="RemoteCandidatesAdded" + tp:name-for-bindings="Remote_Candidates_Added"> + <tp:docstring> + Emitted when remote candidates are added to the + <tp:member-ref>RemoteCandidates</tp:member-ref> property. + </tp:docstring> + <arg name="Candidates" + type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + The candidates that were added. + </tp:docstring> + </arg> + </signal> + + <signal name="CandidateSelected" + tp:name-for-bindings="Candidate_Selected"> + <tp:docstring> + Emitted when a candidate is selected for use in the stream. + </tp:docstring> + <arg name="Candidate" + type="(usqa{sv})" tp:type="Candidate"> + <tp:docstring> + The candidate that has been selected. + </tp:docstring> + </arg> + </signal> + + <property name="SelectedCandidate" + tp:name-for-bindings="Selected_Candidate" + type="(usqa{sv})" tp:type="Candidate" access="read"> + <tp:docstring> + The candidate that has been selected for use to stream packets + to the remote contact. Change notification is given via the + the <tp:member-ref>CandidateSelected</tp:member-ref> signal. + </tp:docstring> + </property> + + <method name="SetSelectedCandidate" + tp:name-for-bindings="Set_Selected_Candidate"> + <tp:docstring> + Set the value of + <tp:member-ref>CandidateSelected</tp:member-ref>. + </tp:docstring> + <arg name="Candidate" + type="(usqa{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The candidate that has been selected. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + + <property name="StreamState" tp:name-for-bindings="Stream_State" + type="u" tp:type="Media_Stream_State" + access="read"> + <tp:docstring> + The stream state of the endpoint. + </tp:docstring> + </property> + + <signal name="StreamStateChanged" + tp:name-for-bindings="Stream_State_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>StreamState</tp:member-ref> + property changes. + </tp:docstring> + <arg name="state" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The new <tp:member-ref>StreamState</tp:member-ref> value. + </tp:docstring> + </arg> + </signal> + + <method name="SetStreamState" + tp:name-for-bindings="Set_Stream_State"> + <tp:docstring> + Change the <tp:member-ref>StreamState</tp:member-ref> of the + endpoint. + </tp:docstring> + <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The requested stream state. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <property name="Transport" tp:name-for-bindings="Transport" + type="u" tp:type="Stream_Transport_Type" access="read"> + <tp:docstring> + The transport type for the stream endpoint. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml new file mode 100644 index 0000000..9e62c87 --- /dev/null +++ b/spec/Call_Stream_Interface_Media.xml @@ -0,0 +1,447 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + [FIXME] + + <h4>ICE restarts</h4> + + <p>If the <tp:dbus-ref + namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref> + signal is fired during a call once it has been called before + whilst setting up the call for initial use, and the + credentials have changed, then there has been an ICE + restart. In such a case, the CM SHOULD also empty the remote + candidate list in the <tp:dbus-ref + namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p> + + <p>If the CM does an ICE restart, then the + <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is + emitted and the streaming implementation should then call + <tp:member-ref>SetCredentials</tp:member-ref> again.</p> + + <p>For more information on ICE restarts see + <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245 + section 9.1.1.1</a></p> + </tp:docstring> + + <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used to set the username fragment and password for streams that have + global credentials.</p> + </tp:docstring> + <arg name="Username" type="s" direction="in"> + <tp:docstring> + The username to use when authenticating on the stream. + </tp:docstring> + </arg> + <arg name="Password" type="s" direction="in"> + <tp:docstring> + The password to use when authenticating on the stream. + </tp:docstring> + </arg> + </method> + + <tp:mapping name="Candidate_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:</p> + + <dl> + <dt>Type (u)</dt> + <dd>type of candidate (host, srflx, prflx, relay)</dd> + + <dt>Foundation (s)</dt> + <dd>the foundation of this candiate</dd> + + <dt>Protocol (u) </dt> + <dd>Underlying protocol of the candidate (udp, tcp) </dd> + + <dt>Priority (u) </dt> + <dd>Priority of the candidate </dd> + + <dt>BaseIP (u) </dt> + <dd>Base IP of this candidate </dd> + + <dt>Username (s) </dt> + <dd>Username of this candidate + (only if credentials are per candidate)</dd> + + <dt>Password (s) </dt> + <dd>Password of this candidate + (only if credentials are per candidate)</dd> + + <dt>RawUDPFallback (b) </dt> + <dd>Indicate whether this candidate may be used to provide a UDP + fallback</dd> + </dl> + </tp:docstring> + <tp:member name="Key" type="s"> + <tp:docstring>One of the well-known keys documented here, or an + implementation-specific key.</tp:docstring> + </tp:member> + <tp:member name="Value" type="v"> + <tp:docstring>The value corresponding to that key.</tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Candidate" array-name="Candidate_List"> + <tp:docstring>A Stream Candidate.</tp:docstring> + <tp:member name="Component" type="u"> + <tp:docstring>The component number.</tp:docstring> + </tp:member> + <tp:member name="IP" type="s"> + <tp:docstring>The IP address to use.</tp:docstring> + </tp:member> + <tp:member name="Port" type="q"> + <tp:docstring>The port number to use.</tp:docstring> + </tp:member> + <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info"> + <tp:docstring>Additional information about the candidate.</tp:docstring> + </tp:member> + </tp:struct> + + <method name="AddCandidates" tp:name-for-bindings="Add_Candidates"> + <tp:docstring> + Add candidates to the + <tp:member-ref>LocalCandidates</tp:member-ref> property and + signal them to the remote contact(s). + </tp:docstring> + <arg name="Candidates" direction="in" + type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + The candidates to be added. + </tp:docstring> + </arg> + </method> + + <method name="CandidatesPrepared" + tp:name-for-bindings="Candidates_Prepared"> + <tp:docstring> + This indicates to the CM that the initial batch of candidates + has been added. + </tp:docstring> + </method> + + <tp:enum type="u" name="Stream_Transport_Type"> + <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A transport that can be used for streaming. + </tp:docstring> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The stream transport type is unknown or not applicable + (for streams that do not have a configurable transport). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Raw_UDP" value="1"> + <tp:docstring> + Raw UDP, with or without STUN. All streaming clients are assumed to + support this transport, so there is no handler capability token for + it in the <tp:dbus-ref namespace="ofdT.Channel.Type" + >Call.DRAFT</tp:dbus-ref> interface. + [This corresponds to "none" or "stun" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="ICE" value="2"> + <tp:docstring> + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="GTalk_P2P" value="3"> + <tp:docstring> + Google Talk peer-to-peer connectivity establishment, as implemented + by libjingle 0.3. + [This corresponds to "gtalk-p2p" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="WLM_2009" value="4"> + <tp:docstring> + The transport used by Windows Live Messenger 2009 or later, which + resembles ICE draft 19. + [This corresponds to "wlm-2009" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="SHM" value="5"> + <tp:added version="0.21.2"/> + <tp:docstring> + Shared memory transport, as implemented by the GStreamer + shmsrc and shmsink plugins. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Multicast" value="6"> + <tp:added version="0.21.5"/> + <tp:docstring> + Multicast transport. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Transport" tp:name-for-bindings="Transport" + type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes"> + <tp:docstring> + The transport for this stream. + </tp:docstring> + </property> + + <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates" + type="a(usqa{sv})" tp:type="Candidate[]" access="read"> + <tp:docstring> + [FIXME]. Change notification is via the + <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal. + </tp:docstring> + </property> + + <signal name="LocalCandidatesAdded" + tp:name-for-bindings="Local_Candidates_Added"> + <tp:docstring> + Emitted when local candidates are added to the + <tp:member-ref>LocalCandidates</tp:member-ref> property. + </tp:docstring> + <arg name="Candidates" type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + Candidates that have been added. + </tp:docstring> + </arg> + </signal> + + <tp:struct name="Stream_Credentials"> + <tp:docstring>A username and password pair.</tp:docstring> + + <tp:member name="Username" type="s"> + <tp:docstring>The username.</tp:docstring> + </tp:member> + + <tp:member name="Password" type="s"> + <tp:docstring>The password.</tp:docstring> + </tp:member> + </tp:struct> + + <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" + type="(ss)" tp:type="Stream_Credentials" access="read"> + <tp:docstring> + [FIXME]. Change notification is via the + <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal. + </tp:docstring> + </property> + + <signal name="LocalCredentialsChanged" + tp:name-for-bindings="Local_Credentials_Changed"> + <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed> + <tp:docstring> + Emitted when the value of + <tp:member-ref>LocalCredentials</tp:member-ref> changes. + </tp:docstring> + <arg name="Username" type="s" /> + <arg name="Password" type="s" /> + </signal> + + <signal name="RelayInfoChanged" + tp:name-for-bindings="Relay_Info_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>RelayInfo</tp:member-ref> changes. + </tp:docstring> + <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" /> + </signal> + + <signal name="STUNServersChanged" + tp:name-for-bindings="STUN_Servers_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>STUNServers</tp:member-ref> changes. + </tp:docstring> + <arg name="Servers" type="a(sq)" tp:type="Socket_Address_IP[]" /> + </signal> + + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" + type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The IP addresses of possible STUN servers to use for NAT + traversal, as dotted-quad IPv4 address literals or RFC2373 + IPv6 address literals. Change notification is via the + <tp:member-ref>STUNServersChanged</tp:member-ref> + signal. The IP addresses MUST NOT be given as DNS hostnames.</p> + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RelayInfo" type="aa{sv}" access="read" + tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:</p> + + <dl> + <dt><code>ip</code> - s</dt> + <dd>The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + </tp:rationale> + </dd> + + <dt><code>type</code> - s</dt> + <dd> + <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this + key is omitted), <code>tcp</code> for TCP, or + <code>tls</code>.</p> + + <p>The precise meaning of this key depends on the + <tp:member-ref>Transport</tp:member-ref> property: if + Transport is ICE, <code>tls</code> means + TLS over TCP as referenced by ICE draft 19, and if + Transport is GTalk_P2P, <code>tls</code> means + a fake SSL session over TCP as implemented by libjingle.</p> + </dd> + + <dt><code>port</code> - q</dt> + <dd>The UDP or TCP port of the relay server as an ASCII unsigned + integer</dd> + + <dt><code>username</code> - s</dt> + <dd>The username to use</dd> + + <dt><code>password</code> - s</dt> + <dd>The password to use</dd> + + <dt><code>component</code> - u</dt> + <dd>The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + <tp:rationale> + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + </tp:rationale> + </dd> + </dl> + + <tp:rationale> + <p>An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.</p> + </tp:rationale> + + <p>The type of relay server that this represents depends on + the value of the <tp:member-ref>Transport</tp:member-ref> + property. If Transport is ICE, this is a TURN server; + if Transport is GTalk_P2P, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.</p> + + <p>If relaying is not possible for this stream, the list is + empty.</p> + + <p>Change notification is given via the + <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="ServerInfoRetrieved" + tp:name-for-bindings="Server_Info_Retrieved"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that the initial information about STUN and Relay servers + has been retrieved, i.e. the + <tp:member-ref>HasServerInfo</tp:member-ref> property is + now true.</p> + </tp:docstring> + </signal> + + <property name="HasServerInfo" type="b" + tp:name-for-bindings="Has_Server_Info" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the + <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p> + + <tp:rationale> + Streaming implementations that can't cope with STUN and + relay servers being added later SHOULD wait for this + property to become true before proceeding. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="EndpointsChanged" + tp:name-for-bindings="Endpoints_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property + changes. + </tp:docstring> + <arg name="Endpoints_Added" type="ao"> + <tp:docstring> + Endpoints that were added. + </tp:docstring> + </arg> + <arg name="Endpoints_Removed" type="ao"> + <tp:docstring> + Endpoints that no longer exist. + </tp:docstring> + </arg> + </signal> + + <property name="Endpoints" tp:name-for-bindings="Endpoints" + type="ao" access="read"> + <tp:docstring> + <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream" + >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this + stream.</p> + + <p>Change notification is via the + <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="PleaseRestartICE" + tp:name-for-bindings="Please_Restart_ICE"> + <tp:docstring> + Emitted when the CM does an ICE restart to notify the + streaming implementation that it should call + <tp:member-ref>SetCredentials</tp:member-ref> again. + </tp:docstring> + </signal> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel.xml b/spec/Channel.xml new file mode 100644 index 0000000..11d3e50 --- /dev/null +++ b/spec/Channel.xml @@ -0,0 +1,557 @@ +<?xml version="1.0" ?> +<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel"> + + <property name="ChannelType" type="s" tp:type="DBus_Interface" + access="read" tp:name-for-bindings="Channel_Type"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel's type. This cannot change once the channel has + been created.</p> + + <p>For compatibility between older connection managers and newer + clients, if this is unavailable or is an empty string, + clients MUST use the result of calling + <tp:member-ref>GetChannelType</tp:member-ref>.</p> + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip, which is desirable. + </tp:rationale> + + <p>When requesting a channel, the request MUST specify a channel + type, and the request MUST fail if the specified channel type + cannot be supplied.</p> + + <tp:rationale> + Common sense. + </tp:rationale> + </tp:docstring> + </property> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this channel. This SHOULD NOT include + the channel type and the Channel interface itself, and cannot + change once the channel has been created.</p> + + <p>For compatibility between older connection managers and newer + clients, if this is unavailable, or if this is an empty list and + <tp:member-ref>ChannelType</tp:member-ref> is an empty string, + clients MUST use the result of calling + <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an + empty list but ChannelType is non-empty, clients SHOULD NOT call + GetInterfaces; this implies that connection managers that implement + the ChannelType property MUST also implement the Interfaces property + correctly.</p> + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip, which is desirable. + </tp:rationale> + + <p>When requesting a channel with a particular value for this + property, the request must fail without side-effects unless the + connection manager expects to be able to provide a channel whose + interfaces include at least the interfaces requested.</p> + </tp:docstring> + </property> + + <property name="TargetHandle" type="u" access="read" tp:type="Handle" + tp:name-for-bindings="Target_Handle"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The handle (a representation for the identifier) of the contact, + chatroom, etc. with which this handle communicates. Its type + is given by the <tp:member-ref>TargetHandleType</tp:member-ref> + property.</p> + + <p>This is fixed for the lifetime of the channel, so channels which + could potentially be used to communicate with multiple contacts, + and do not have an identity of their own (such as a Handle_Type_Room + handle), must have TargetHandleType set to Handle_Type_None and + TargetHandle set to 0.</p> + + <p>Unlike in the telepathy-spec 0.16 API, there is no particular + uniqueness guarantee - there can be many channels with the same + (channel type, handle type, handle) tuple. This is necessary + to support conversation threads in XMPP and SIP, for example.</p> + + <p>If this is present in a channel request, it must be nonzero, + <tp:member-ref>TargetHandleType</tp:member-ref> + MUST be present and not Handle_Type_None, and + <tp:member-ref>TargetID</tp:member-ref> MUST NOT be + present. Properties from + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> + MUST NOT be present.</p> + + <p>The channel that satisfies the request MUST either:</p> + + <ul> + <li>have the specified TargetHandle property; or</li> + <li>have <tp:member-ref>TargetHandleType</tp:member-ref> = + Handle_Type_None, TargetHandle = 0, and be configured such that + it could communicate with the specified handle in some other way + (e.g. have the requested contact handle in its Group + interface)</li> + </ul> + </tp:docstring> + </property> + + <property name="TargetID" tp:name-for-bindings="Target_ID" + type="s" access="read"> + <tp:added version="0.17.9"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string that would result from inspecting the + <tp:member-ref>TargetHandle</tp:member-ref> + property (i.e. the identifier in the IM protocol of the contact, + room, etc. with which this channel communicates), or the empty + string if the TargetHandle is 0.</p> + + <tp:rationale> + <p>The presence of this property avoids the following race + condition:</p> + + <ul> + <li>New channel C is signalled with target handle T</li> + <li>Client calls <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [T])</li> + <li>Channel C closes, removing the last reference to handle T</li> + <li><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [T]) returns an error</li> + </ul> + </tp:rationale> + + <p>If this is present in a channel request, + <tp:member-ref>TargetHandleType</tp:member-ref> + MUST be present and not Handle_Type_None, and + <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be + present. Properties from + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> + MUST NOT be present.The request MUST fail with error InvalidHandle, + without side-effects, if the requested TargetID would not be + accepted by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p> + + <p>The returned channel must be related to the handle corresponding + to the given identifier, in the same way as if TargetHandle + had been part of the request instead.</p> + + <tp:rationale> + <p>Requesting channels with a string identifier saves a round-trip + (the call to RequestHandles). It also allows the channel + dispatcher to accept a channel request for an account that is not + yet connected (and thus has no valid handles), bring the account + online, and pass on the same parameters to the new connection's + CreateChannel method.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="TargetHandleType" type="u" access="read" + tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p> + + <p>If this is omitted from a channel request, connection managers + SHOULD treat this as equivalent to Handle_Type_None.</p> + + <p>If this is omitted or is Handle_Type_None, + <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the + request.</p> + </tp:docstring> + </property> + + <method name="Close" tp:name-for-bindings="Close"> + <tp:docstring> + Request that the channel be closed. This is not the case until + the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and + depending on the connection + manager this may simply remove you from the channel on the server, + rather than causing it to stop existing entirely. Some channels + such as contact list channels may not be closed. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + This channel may never be closed, e.g. a contact list + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This channel is not currently in a state where it can be closed, + e.g. a non-empty user-defined contact group + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="Closed" tp:name-for-bindings="Closed"> + <tp:docstring> + Emitted when the channel has been closed. Method calls on the + channel are no longer valid after this signal has been emitted, + and the connection manager may then remove the object from the bus + at any point. + </tp:docstring> + </signal> + + <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type"> + <tp:deprecated version="0.17.7">Use the ChannelType + property if possible.</tp:deprecated> + <arg direction="out" type="s" tp:type="DBus_Interface" + name="Channel_Type"> + <tp:docstring>The interface name</tp:docstring> + </arg> + <tp:docstring> + Returns the interface name for the type of this channel. Clients + SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property + instead, falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </tp:docstring> + </method> + + <method name="GetHandle" tp:name-for-bindings="Get_Handle"> + <tp:deprecated version="0.17.7">Use the TargetHandleType + and TargetHandle properties if possible.</tp:deprecated> + <arg direction="out" type="u" tp:type="Handle_Type" + name="Target_Handle_Type"> + <tp:docstring> + The same as TargetHandleType. + </tp:docstring> + </arg> + <arg direction="out" type="u" tp:type="Handle" name="Target_Handle"> + <tp:docstring> + The same as TargetHandle. + </tp:docstring> + </arg> + <tp:docstring> + Returns the handle type and number if this channel represents a + communication with a particular contact, room or server-stored list, or + zero if it is transient and defined only by its contents. Clients + SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetHandleType</tp:member-ref> properties instead, + falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </tp:docstring> + </method> + + <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> + <tp:deprecated version="0.17.7">Use the Interfaces + property if possible.</tp:deprecated> + <arg direction="out" type="as" tp:type="DBus_Interface[]" + name="Interfaces"> + <tp:docstring> + An array of the D-Bus interface names + </tp:docstring> + </arg> + <tp:docstring> + Get the optional interfaces implemented by the channel. + Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref> + property instead, falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </tp:docstring> + </method> + + <property name="Requested" tp:name-for-bindings="Requested" + type="b" access="read"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel was created in response to a local request, + such as a call to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> + or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p> + + <tp:rationale> + <p>The idea of this property is to distinguish between "incoming" + and "outgoing" channels, in a way that doesn't break down when + considering special cases like contact lists that are automatically + created on connection to the server, or chatrooms that an + IRC proxy/bouncer like irssi-proxy or bip was already in.</p> + + <p>The reason we want to make that distinction is that UIs for + things that the user explicitly requested should start up + automatically, whereas for incoming messages and VoIP calls we + should first ask the user whether they want to open the messaging + UI or accept the call.</p> + </tp:rationale> + + <p>If the channel was not explicitly requested (even if it was + created as a side-effect of a call to one of those functions, + e.g. because joining a Tube in a MUC context on XMPP implies + joining that MUC), then this property is false.</p> + + <p>For compatibility with older connection managers, clients SHOULD + assume that this property is true if they see a channel announced + by the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal with the suppress_handler parameter set to true.</p> + + <tp:rationale> + <p>In a correct connection manager, the only way to get such a + channel is to request it.</p> + </tp:rationale> + + <p>Clients MAY additionally assume that this property is false + if they see a channel announced by the NewChannel signal with the + suppress_handler parameter set to false.</p> + + <tp:rationale> + <p>This is more controversial, since it's possible to get that + parameter set to false by requesting a channel. However, there's + no good reason to do so, and we've deprecated this practice.</p> + + <p>In the particular case of the channel dispatcher, the only + side-effect of wrongly thinking a channel is unrequested + is likely to be that the user has to confirm that they want to + use it, so it seems fairly harmless to assume in the channel + dispatcher that channels with suppress_handler false are + indeed unrequested.</p> + </tp:rationale> + + <p>It does not make sense for this property to be in channel + requests—it will always be true for channels returned by + CreateChannel, and callers of EnsureChannel cannot control whether an + existing channel was originally requested locally—so it MUST NOT + be accepted.</p> + </tp:docstring> + </property> + + <property name="InitiatorHandle" type="u" tp:type="Contact_Handle" + access="read" tp:name-for-bindings="Initiator_Handle"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact who initiated the channel; for instance, the contact + who invited the local user to a chatroom, or the contact who + initiated a call.</p> + + <p>This does <em>not</em> necessarily represent the contact who + created the underlying protocol-level construct. For instance, if + Rob creates a chatroom, Will joins that chatroom, and Will invites Simon + to join it, then Simon will see Will as the InitiatorHandle of the + channel representing the chatroom.</p> + + <tp:rationale> + <p>The room creator is generally a less useful piece of information + than the inviter, is less likely to be available at invitation + time (i.e. can't necessarily be an immutable property), and is + less likely to be available at all. The creator of a chatroom + is not currently available via Telepathy; if added in future, it + is likely to be made available as a property on the Chatroom + interface (<a + href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p> + </tp:rationale> + + <p>For channels requested by the + local user, this MUST be the value of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref> + at the time the channel was created (i.e. not a channel-specific + handle).</p> + + <tp:rationale> + <p>On some protocols, the SelfHandle may change (as signalled by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>), + but this property is immutable. Hence, locally-requested channels' + InitiatorHandle and InitiatorID may not match the current + SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to + determine whether the channel was created locally.</p> + </tp:rationale> + + <p>For channels requested by a remote user, this MUST be their handle. + If unavailable or not applicable, this MUST be 0 (for instance, + contact lists are not really initiated by anyone in particular, and + it's easy to imagine a protocol where chatroom invitations can be + anonymous).</p> + + <p>For channels with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + interface, this SHOULD be the same + contact who is signalled as the "Actor" causing the self-handle + to be placed in the local-pending set.</p> + + <p>This SHOULD NOT be a channel-specific handle, if possible.</p> + + <p>It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.</p> + </tp:docstring> + </property> + + <property name="InitiatorID" type="s" access="read" + tp:name-for-bindings="Initiator_ID"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string that would result from inspecting the + <tp:member-ref>InitiatorHandle</tp:member-ref> + property (i.e. the initiator's identifier in the IM protocol).</p> + + <tp:rationale> + <p>The presence of this property avoids the following race + condition:</p> + + <ul> + <li>New StreamedMedia channel C is signalled with initiator + handle I</li> + <li>Client calls <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [I])</li> + <li>Channel C closes, removing the last reference to handle I</li> + <li><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [I]) returns an error</li> + <li>Client can indicate that a call was missed, but not who + called!</li> + </ul> + </tp:rationale> + + <p>It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.</p> + </tp:docstring> + </property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>All communication in the Telepathy framework is carried out via channel + objects which are created and managed by connections. This interface must + be implemented by all channel objects, along with one single channel type, + such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref> + which represents a list of people (such as a buddy list) or <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which + represents a channel over which textual messages are sent and received.</p> + + <p>Each Channel's object path MUST start with the object path of + its associated <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed + by '/'. There MAY be any number of additional object-path components, + which clients MUST NOT attempt to parse.</p> + + <tp:rationale> + <p>This ensures that Channel object paths are unique, even between + Connections and CMs, because Connection object paths are + guaranteed-unique via their link to the well-known bus name.</p> + + <p>If all connection managers in use are known to comply with at least + spec version 0.17.10, then the Connection's object path can + even be determined from the Channel's without any additional + information, by taking the first 7 components.</p> + </tp:rationale> + + <p>Each channel has a number of immutable properties (which cannot vary + after the channel has been announced with <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>), + provided to clients in the + <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and + <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref> + methods to permit immediate identification of the channel. This interface + contains immutable properties common to all channels. In brief:</p> + + <ul> + <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of + communication carried out on this channel;</li> + <li><tp:member-ref>TargetHandleType</tp:member-ref>, + <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetID</tp:member-ref> specify the entity with which + this channel communicates, such as the other party in a 1-1 call, or + the name of a multi-user chat room;</li> + <li><tp:member-ref>InitiatorHandle</tp:member-ref> and + <tp:member-ref>InitiatorID</tp:member-ref> specify who created this + channel;</li> + <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local + user requested this channel, or whether it is an incoming call, a text + conversation started by a remote contact, a chatroom invitation, + etc.</li> + </ul> + + <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be + implemented to indicate other available + functionality, such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> + if the channel contains a number of contacts, <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref> + to indicate that a channel may have a password set to require entry, and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref> + for typing notifications. The interfaces implemented may not vary after + the channel has been created. These other interfaces (along with the + interface named by <tp:member-ref>ChannelType</tp:member-ref>) may + themselves specify immutable properties to be announced up-front along + with the properties on this interface.</p> + + <p>Some channels are “anonymous”, with + <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>, + which indicates that the channel is defined by some other properties. For + instance, transient ad-hoc chat rooms may be defined only by their members (as visible + through the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface), and <tp:dbus-ref + namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref> + channels represent a single search attempt for a particular <tp:dbus-ref + namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p> + + <p>Specific connection manager implementations may implement channel types and + interfaces which are not contained within this specification in order to + support further functionality. To aid interoperability between client and + connection manager implementations, the interfaces specified here should be + used wherever applicable, and new interfaces made protocol-independent + wherever possible. Because of the potential for 3rd party interfaces adding + methods or signals with conflicting names, the D-Bus interface names should + always be used to invoke methods and bind signals.</p> + </tp:docstring> + + <tp:changed version="0.17.7">Previously we guaranteed that, for + any handle type other than Handle_Type_None, and for any channel type + and any handle, there would be no more than one channel with that + combination of channel type, handle type and handle. This guarantee + has now been removed in order to accommodate features like message + threads. + </tp:changed> + + <tp:changed version="0.17.10">Previously we did not explicitly + guarantee that Channels' object paths had the Connection's object path + as a prefix. + </tp:changed> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Bundle.xml b/spec/Channel_Bundle.xml new file mode 100644 index 0000000..d211525 --- /dev/null +++ b/spec/Channel_Bundle.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" ?> +<node name="/Channel_Bundle" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.ChannelBundle.DRAFT" + tp:causes-havoc="experimental"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A group of related channels, which should all be dispatched to the + same handler if possible.</p> + + <p>Bundles currently have no functionality of their own, so clients + SHOULD NOT examine this interface, but should instead treat the + bundle object-path as an opaque identifier. If more functionality is + added to bundles in future, this interface will be used for capability + discovery.</p> + + <p>The lifetime of a bundle is defined by its component channels - + as long as one or more channels whose Bundle property is <em>B</em> + exist, the bundle <em>B</em> will also exist.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel bundle. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml new file mode 100644 index 0000000..6ec69a6 --- /dev/null +++ b/spec/Channel_Dispatch_Operation.xml @@ -0,0 +1,483 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatch_Operation" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, + MA 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel dispatch operation is an object in the ChannelDispatcher + representing a batch of unrequested channels being announced to + client + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref> + processes.</p> + + <p>These objects can result from new incoming channels or channels + which are automatically created for some reason, but cannot result + from outgoing requests for channels.</p> + + <p>More specifically, whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> + signal contains channels whose + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + property is false, or whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal contains a channel with suppress_handler false, + one or more ChannelDispatchOperation objects are created for those + channels.</p> + + <p>(If some channels in a NewChannels signal are in different bundles, + this is an error. The channel dispatcher SHOULD recover by treating + the NewChannels signal as if it had been several NewChannels signals + each containing one channel.)</p> + + <p>First, the channel dispatcher SHOULD construct a list of all the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s + that could handle all the channels (based on their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + property), ordered by + priority in some implementation-dependent way. If there are handlers + which could handle all the channels, one channel dispatch operation + SHOULD be created for all the channels. If there are not, one channel + dispatch operation SHOULD be created for each channel, each with + a list of channel handlers that could handle that channel.</p> + + <p>If no handler at all can handle a channel, the channel dispatcher + SHOULD terminate that channel instead of creating a channel dispatcher + for it. It is RECOMMENDED that the channel dispatcher closes + the channels using <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + if supported, or <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + otherwise. As a special case, the channel dispatcher SHOULD NOT close + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref> + channels, and if Close fails, the channel dispatcher SHOULD ignore + that channel.</p> + + <tp:rationale> + <p>ContactList channels are strange. We hope to replace them with + something better, such as an interface on the Connection, in a + future version of this specification.</p> + </tp:rationale> + + <p>When listing channel handlers, priority SHOULD be given to + channel handlers that are already handling channels from the same + bundle.</p> + + <p>If a handler with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">BypassApproval</tp:dbus-ref> + <code>= True</code> could handle all of the channels in the dispatch + operation, then the channel dispatcher SHOULD call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + on that handler, and (assuming the call succeeds) emit + <tp:member-ref>Finished</tp:member-ref> and stop processing those + channels without involving any approvers.</p> + + <tp:rationale> + <p>Some channel types can be picked up "quietly" by an existing + channel handler. If a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + channel is added to an existing bundle containing a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + channel, there shouldn't be + any approvers, flashing icons or notification bubbles, if the + the UI for the StreamedMedia channel can just add a text box + and display the message.</p> + </tp:rationale> + + <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch + operation to all relevant approvers (in parallel) and wait for an + approver to claim the channels or request that they are handled. + See + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> + for more details on this.</p> + + <p>Finally, if the approver requested it, the channel dispatcher SHOULD + send the channels to a handler.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatch + operation. This property cannot change. + </tp:docstring> + </property> + + <property name="Connection" tp:name-for-bindings="Connection" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the <tp:member-ref>Channels</tp:member-ref> are + associated. The well-known bus name to use can be derived from + this object path by removing the leading '/' and replacing all + subsequent '/' by '.'. This property cannot change. + </tp:docstring> + </property> + + <property name="Account" tp:name-for-bindings="Account" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the <tp:member-ref>Connection</tp:member-ref> + and <tp:member-ref>Channels</tp:member-ref> are + associated. This property cannot change. + </tp:docstring> + </property> + + <property name="Channels" tp:name-for-bindings="Channels" + type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + to be dispatched, and their properties. Change notification is via + the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels + cannot be added to this property, only removed). + </tp:docstring> + </property> + + <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel has closed before it could be claimed or handled. If + this is emitted for the last remaining channel in a channel + dispatch operation, it MUST immediately be followed by + <tp:member-ref>Finished</tp:member-ref>.</p> + + <p>This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> + method.</p> + + <tp:rationale> + <p>This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to ChannelLost and + <tp:member-ref>Finished</tp:member-ref>, + then download <tp:member-ref>Channels</tp:member-ref> (and + on error, perhaps assume that the operation has already + Finished).</p> + </tp:rationale> + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> + that closed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error indicating why the channel closed. If + no better reason can be found, + <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + A string associated with the D-Bus error. + </tp:docstring> + </arg> + </signal> + + <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" + type="as" access="read" tp:type="DBus_Well_Known_Name[]"> + <tp:docstring> + <p>The well known bus names (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the possible + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s + for these channels. The channel dispatcher MUST place the most + preferred handlers first, according to some reasonable heuristic. + As a result, approvers SHOULD use the first handler by default.</p> + + <p>The heuristic used to prioritize handlers SHOULD give a higher + priority to handlers that are already running.</p> + + <tp:rationale> + <p>If, for instance, Empathy and Kopete have similar functionality, + and Empathy is running, we should prefer to send channels to it + rather than launching Kopete via service activation.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="HandleWith" tp:name-for-bindings="Handle_With"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to accept a channel bundle and request that + the given handler be used to handle it.</p> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>.</p> + + <p>However, this method may fail because the dispatch has already been + completed and the object has already gone. If this occurs, it + indicates that another approver has asked for the bundle to be + handled by a particular handler. The approver MUST NOT attempt + to interact with the channels further in this case, unless it is + separately invoked as the handler.</p> + + <p>Approvers which are also channel handlers SHOULD use + <tp:member-ref>Claim</tp:member-ref> instead + of HandleWith to request that they can handle a channel bundle + themselves.</p> + + <p>(FIXME: list some possible errors)</p> + + <p>If the channel handler raises an error from <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>, + this method + MAY respond by raising that same error, even if it is not + specifically documented here.</p> + </tp:docstring> + + <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the channel + handler that should handle the channel, or the empty string + if the client has no preferred channel handler.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The selected handler is non-empty, but is not a syntactically + correct <tp:type>DBus_Bus_Name</tp:type> or does not start with + "<code>org.freedesktop.Telepathy.Client.</code>". + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The selected handler is temporarily unable to handle these + channels. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Claim" tp:name-for-bindings="Claim"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to claim channels for handling + internally. If this method is called successfully, the process + calling this method becomes the handler for the channel, but + <em>does not</em> have the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + method called on it.</p> + + <p>Clients that call Claim on channels but do not immediately + close them SHOULD implement the Handler interface and its + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandledChannels</tp:dbus-ref> + property.</p> + + <p>Approvers wishing to reject channels MUST call this method to + claim ownership of them, and MUST NOT call + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channels unless/until this method returns successfully.</p> + + <tp:rationale> + <p>The channel dispatcher can't know how best to close arbitrary + channel types, so it leaves it up to the approver to do so. + For instance, for Text channels it is necessary + to acknowledge any messages that have already been displayed to + the user first - ideally, the approver would display and then + acknowledge the messages - or to call <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + if the destructive behaviour of that method is desired.</p> + + <p>Similarly, an Approver for StreamedMedia channels can close the + channel with a reason (e.g. "busy") if desired. The channel + dispatcher, which is designed to have no specific knowledge + of particular channel types, can't do that.</p> + </tp:rationale> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>, in the same way as for + <tp:member-ref>HandleWith</tp:member-ref>.</p> + + <p>This method may fail because the dispatch operation has already + been completed. Again, see HandleWith for more details. The approver + MUST NOT attempt to interact with the channels further in this + case.</p> + + <p>(FIXME: list some other possible errors)</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that Claim was called, this dispatch operation was + processing a call to HandleWith which has now succeeded, so + some Handler nominated by another approver is now responsible for + the channel. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time"> + <tp:added version="0.19.6"> + At the time of writing, no released implementation of the + Channel Dispatcher implements this method; clients should fall + back to calling <tp:member-ref>HandleWith</tp:member-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the + approver to pass an user action time. This timestamp will be passed + to the Handler when <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + is called.</p> + </tp:docstring> + + <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the channel + handler that should handle the channel, or the empty string + if the client has no preferred channel handler.</p> + </tp:docstring> + </arg> + + <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The selected handler is non-empty, but is not a syntactically + correct <tp:type>DBus_Bus_Name</tp:type> or does not start with + "<code>org.freedesktop.Telepathy.Client.</code>". + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The selected handler is temporarily unable to handle these + channels. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="Finished" tp:name-for-bindings="Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when this dispatch operation finishes. The dispatch + operation is no longer present and further methods must not be + called on it.</p> + + <p>Approvers that have a user interface SHOULD stop notifying the user + about the channels in response to this signal; they MAY assume that + on errors, they would have received + <tp:member-ref>ChannelLost</tp:member-ref> first.</p> + + <p>Its object path SHOULD NOT be reused for a subsequent dispatch + operation; the ChannelDispatcher MUST choose object paths + in a way that avoids immediate re-use.</p> + + <tp:rationale> + <p>Otherwise, clients might accidentally call + <tp:member-ref>HandleWith</tp:member-ref> or + <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation + instead of the one they intended to handle.</p> + </tp:rationale> + + <p>This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref> + method.</p> + + <tp:rationale> + <p>This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to + <tp:member-ref>ChannelLost</tp:member-ref> and + Finished, then download <tp:member-ref>Channels</tp:member-ref> + (and on error, perhaps assume that the operation has already + Finished).</p> + </tp:rationale> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml new file mode 100644 index 0000000..2dd000b --- /dev/null +++ b/spec/Channel_Dispatcher.xml @@ -0,0 +1,595 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelDispatcher"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel dispatcher is responsible for responding to new + channels and launching client processes to handle them. It also + provides functionality for client processes to request that new + channels are created.</p> + + <p>If a channel dispatcher is running, it is responsible for dispatching + new channels on all + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s + created by the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + Connections not created by the AccountManager are outside the scope + of the channel dispatcher.</p> + + <tp:rationale> + <p>Connections created by standalone Telepathy clients + that do not intend to interact with the channel dispatcher + should be ignored - otherwise, the channel dispatcher would try + to launch handlers for channels that the standalone client + was already handling internally.</p> + </tp:rationale> + + <p>The current channel dispatcher is defined to be the process that + owns the well-known bus name + <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on + the session bus. This process MUST export an object with this + interface at the object path + <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of ChannelDispatcher implementation, implementations SHOULD NOT + register as an activatable service for the ChannelDispatcher's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs + can detect whether channel request/dispatch functionality is available + by checking whether the ChannelDispatcher's well-known name is in use + at runtime.</p> + + <p>There are three categories of client process defined by this + specification:</p> + + <dl> + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt> + <dd><p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p></dd> + + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt> + <dd> + <p>Approvers notify the user that new channels have been created, + and also select which channel handler will be used for the channel, + either by asking the user or by choosing the most appropriate + channel handler.</p> + </dd> + + <dt><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt> + <dd> + <p>Each new channel or set of channels is passed to exactly one + handler as its final destination. A typical channel handler is a + user interface process handling channels of a particular type.</p> + </dd> + </dl> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatcher. + </tp:docstring> + </property> + + <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Equivalent to calling + <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty + <var>Hints</var> parameter.</p> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + <tp:changed version="0.19.0"> + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + </tp:changed> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Equivalent to calling + <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty + <var>Hints</var> parameter.</p> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="CreateChannelWithHints" + tp:name-for-bindings="Create_Channel_With_Hints"> + <tp:added version="0.21.5"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start a request to create a channel. This initially just creates a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <tp:rationale> + <p>The request can take a long time - in the worst case, the + channel dispatcher has to ask the account manager to put the + account online, the account manager has to ask the operating + system to obtain an Internet connection, and the operating + system has to ask the user whether to activate an Internet + connection using an on-demand mechanism like dialup.</p> + + <p>This means that using a single D-Bus method call and response + to represent the whole request will tend to lead to that call + timing out, which is not the behaviour we want.</p> + </tp:rationale> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>This means there's only one code path for errors, apart from + InvalidArgument for "that request makes no sense".</p> + + <p>It also means that the request will proceed if the account is + enabled after calling CreateChannel, but before calling + Proceed.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> + property will be set to this value, and it will eventually be + passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler—irrespective of whether that handler's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + matches the channel—and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler.</p> + + <tp:rationale> + <p>This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.</p> + + <p>This is partly so the channel dispatcher can call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.</p> + + <p>The filter should be disregarded for ease of use of this + interface: clients will usually use this argument to request + channels be sent to themself, and this should trump the filter + not matching. This also allows a client to become the handler + for a channel produced by one of its own requests, while not + being a candidate to handle other channels of that type.</p> + </tp:rationale> + + <p>If this is a well-known bus name and the handler has the + Requests interface, the channel dispatcher SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> + on that Handler after this method has returned.</p> + + <tp:rationale> + <p>This ordering allows a Handler which calls CreateChannel with + itself as the preferred handler to associate the call to + AddRequest with that call.</p> + </tp:rationale> + + <p>This is copied to the ChannelRequest that is returned, + as the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref> + property.</p> + </tp:docstring> + + <tp:changed version="0.19.0"> + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + </tp:changed> + </arg> + + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + <p>Additional information about the channel request, which will be + used as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + property.</p> + + <tp:rationale> + <p>See the Hints property's documentation for rationale.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="EnsureChannelWithHints" + tp:name-for-bindings="Ensure_Channel_With_Hints"> + <tp:added version="0.21.5"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start a request to ensure that a channel exists, creating it if + necessary. This initially just creates a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>The rationale is as for <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except + as noted here.</p> + + <p>If any new channels are created in response to this + request, the channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler. If the requested channel already exists (that + is, <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> + returns <code>Yours=False</code>) then the channel dispatcher + SHOULD re-dispatch the channel to its existing handler, and MUST + NOT dispatch it to this client (unless it is the existing handler); + the request is still deemed to have succeeded in this case.</p> + + <tp:rationale> + <p>An address book application, for example, might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> + to ensure that a text channel with a particular contact is + displayed to the user; it does not care whether a new channel was + made. An IM client might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> + in response to the user double-clicking an entry in the contact + list, with itself as the <code>Preferred_Handler</code>; if the + user already has a conversation with that contact in another + application, they would expect the existing window to be + presented, rather than their double-click leading to an error + message. So the request should succeed, even if its + <code>Preferred_Handler</code> is not used.</p> + </tp:rationale> + + </tp:docstring> + </arg> + + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + Additional information about the channel request, which will be used + as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + property.</tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <property name="SupportsRequestHints" + tp:name-for-bindings="Supports_Request_Hints" + type="b" access="read"> + <tp:added version="0.21.5"/> + <tp:docstring> + If <code>True</code>, the channel dispatcher is new enough to support + <tp:member-ref>CreateChannelWithHints</tp:member-ref> and + <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition + to the older <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref> + and <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref> + methods, and also new enough to emit <tp:dbus-ref + namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref> + before the older <tp:dbus-ref + namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal. + If <code>False</code> or missing, only the metadata-less + variants are supported. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml new file mode 100644 index 0000000..be06f5c --- /dev/null +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -0,0 +1,140 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Interface_Operation_List" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface allows users of the ChannelDispatcher to enumerate + all the pending dispatch operations, with change notification.</p> + + <tp:rationale> + <p>The existence of the + <tp:member-ref>DispatchOperations</tp:member-ref> property allows a + newly started approver to pick up existing dispatch operations.</p> + + <p>This is on a separate interface so clients that aren't interested + in doing this aren't woken up by its signals.</p> + </tp:rationale> + </tp:docstring> + + <tp:struct name="Dispatch_Operation_Details" + array-name="Dispatch_Operation_Details_List"> + + <tp:docstring> + Details of a channel dispatch operation. + </tp:docstring> + + <tp:member name="Channel_Dispatch_Operation" type="o"> + <tp:docstring> + The object path of the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>. + </tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel dispatch operation.</p> + + <p>Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.</p> + + <tp:rationale> + <p>The rationale is the same as for + <tp:type>Channel_Details</tp:type>.</p> + </tp:rationale> + + <p>Each dictionary MUST contain at least the following keys:</p> + <ul> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Connection</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Account</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers</tp:dbus-ref></li> + </ul> + </tp:docstring> + </tp:member> + </tp:struct> + + <property + name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations" + type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of ChannelDispatchOperation objects currently being + processed. Change notification is via the + <tp:member-ref>NewDispatchOperation</tp:member-ref> and + <tp:member-ref>DispatchOperationFinished</tp:member-ref> signals.</p> + </tp:docstring> + </property> + + <signal name="NewDispatchOperation" + tp:name-for-bindings="New_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a dispatch operation is added to + <tp:member-ref>DispatchOperations</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was created. + </tp:docstring> + </arg> + + <arg name="Properties" + type="a{sv}" tp:type="Qualified_Property_Value_Map"> + <tp:docstring> + The same properties that would appear in the Properties member of + <tp:type>Dispatch_Operation_Details</tp:type>. + </tp:docstring> + </arg> + </signal> + + <signal name="DispatchOperationFinished" + tp:name-for-bindings="Dispatch_Operation_Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when a dispatch operation finishes (i.e. exactly once per + emission of <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>). + + <tp:rationale> + Strictly speaking this is redundant with + ChannelDispatchOperation.Finished, but it provides full + change-notification for the + <tp:member-ref>DispatchOperations</tp:member-ref> property. + </tp:rationale> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was closed. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml new file mode 100644 index 0000000..5bbca17 --- /dev/null +++ b/spec/Channel_Future.xml @@ -0,0 +1,68 @@ +<?xml version="1.0" ?> +<node name="/Channel_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.FUTURE" + tp:causes-havoc="a staging area for future Channel functionality"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> interface + in future. It should be considered to + be conceptually part of the core Channel interface, but without + API or ABI guarantees.</p> + + <tp:rationale> + <p>If we add new functionality to the Channel interface, libraries + that use generated code (notably telepathy-glib) will have it as + part of their ABI forever, meaning we can't make incompatible + changes. By using this interface as a staging area for future + Channel functionality, we can try out new properties, signals + and methods as application-specific extensions, then merge them + into the core Channel interface when we have enough implementation + experience to declare them to be stable.</p> + + <p>The name is by analogy to Python's <code>__future__</code> + pseudo-module.</p> + </tp:rationale> + </tp:docstring> + + <property name="Bundle" tp:name-for-bindings="Bundle" + type="o" access="read"> + <tp:added version="0.17.9">(in Channel.FUTURE + pseudo-interface)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle.DRAFT</tp:dbus-ref> + to which this channel belongs.</p> + + <p>A channel's Bundle property can never change.</p> + + <p>Older connection managers might not have this property. Clients + (particularly the channel dispatcher) SHOULD recover by considering + each channel to be in a bundle containing only that channel, + distinct from all other bundles, which has no additional + interfaces.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml new file mode 100644 index 0000000..edf975e --- /dev/null +++ b/spec/Channel_Handler.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2007-2008 Collabora Limited</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.ChannelHandler"> + <tp:deprecated version="0.17.23"> + Clients should implement <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref> + instead. + </tp:deprecated> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface exported by Mission Control 4 client applications which + are able to handle incoming channels.</p> + </tp:docstring> + <tp:added version="0.17.0"/> + + <method name="HandleChannel" tp:name-for-bindings="Handle_Channel"> + <tp:docstring> + Called when a channel handler should handle a new channel. + </tp:docstring> + <tp:added version="0.17.0"/> + + <arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name"> + <tp:docstring> + The bus name of the connection and channel + </tp:docstring> + </arg> + + <arg direction="in" type="o" name="Connection"> + <tp:docstring> + The object-path of the connection that owns the channel + </tp:docstring> + </arg> + + <arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type"> + <tp:docstring> + The channel type + </tp:docstring> + </arg> + + <arg direction="in" type="o" name="Channel"> + <tp:docstring> + The object-path of the channel + </tp:docstring> + </arg> + + <arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type"> + <tp:docstring>The type of the handle that the channel communicates + with, or 0 if there is no associated handle</tp:docstring> + </arg> + + <arg direction="in" type="u" tp:type="Handle" name="Handle"> + <tp:docstring>The handle that the channel communicates with, + or 0 if there is no associated handle</tp:docstring> + </arg> + + <!-- FIXME: possible errors? --> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> + diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml new file mode 100644 index 0000000..494fd7b --- /dev/null +++ b/spec/Channel_Interface_Addressing.xml @@ -0,0 +1,107 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Addressing.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.12">(as draft)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface provides properties that can be used for + requesting channels through different contact addressing + schemes like vCard addresses or URIs. + </p> + </tp:docstring> + + <property name="TargetVCardField" type="s" access="read" + tp:name-for-bindings="Target_VCard_Field"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard field, normalized to lower case, + <tp:member-ref>TargetVCardAddress</tp:member-ref> refers to.</p> + + <p>The <code>url</code> vCard field MUST NOT appear here; see + <tp:member-ref>TargetURI</tp:member-ref> instead.</p> + + <tp:rationale> + <p>In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.</p> + </tp:rationale> + + <p>If this is omitted from a request, + <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST be + omitted as well.</p> + </tp:docstring> + </property> + + <property name="TargetURIScheme" type="s" access="read" + tp:name-for-bindings="Target_URI_Scheme"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The URI scheme used in <tp:member-ref>TargetURI</tp:member-ref></p> + + <tp:rationale> + <p>While this seems redundant, since the scheme is included in + <tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + that support a limited set of URI schemes.</p> + </tp:rationale> + + <p>If this is omitted from a request, + <tp:member-ref>TargetURI</tp:member-ref> MUST be + omitted as well.</p> + </tp:docstring> + </property> + + <property name="TargetVCardAddress" type="s" access="read" + tp:name-for-bindings="Target_VCard_Address"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard address of the Channel's target.</p> + + <p>If this is present in a channel request, + <tp:member-ref>TargetVCardField</tp:member-ref> + MUST be present, and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>, + and <tp:member-ref>TargetURI</tp:member-ref> MUST NOT be present. + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.</p> + </tp:docstring> + </property> + + <property name="TargetURI" type="s" access="read" + tp:name-for-bindings="Target_URI"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The URI of the Channel's target. The URI's scheme (i.e. the + part before the first colon) MUST be identical to + <tp:member-ref>TargetURIScheme</tp:member-ref>.</p> + + <p>If this is present in a channel request, + <tp:member-ref>TargetVCardField</tp:member-ref> + MUST be present, and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>, + and <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST NOT be + present. + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml new file mode 100644 index 0000000..ef3a3b8 --- /dev/null +++ b/spec/Channel_Interface_Anonymity.xml @@ -0,0 +1,68 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Anonymity" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity"> + <tp:added version="0.19.7">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for requesting the anonymity modes of a channel + (as defined in <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.Interface.Anonymity</tp:dbus-ref>).</p> + </tp:docstring> + + <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" + access="read" tp:name-for-bindings="Anonymity_Modes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The list of initially requested anonymity modes on the channel. This + MUST NOT change, and is Requestable. + </tp:docstring> + </property> + + <property name="AnonymityMandatory" type="b" access="read" + tp:name-for-bindings="Anonymity_Mandatory"> + <tp:docstring> + Whether or not the anonymity settings are required for this channel. + This MUST NOT change, and is Requestable. + </tp:docstring> + </property> + + <property name="AnonymousID" type="s" access="read" + tp:name-for-bindings="Anonymous_ID"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This is the ID that the remote user of the channel MAY see + (assuming there's a single ID). For example, for SIP connections + where the From address has been scrambled by the CM, the scrambled + address would be available here for the client to see. This is + completely optional, and MAY be an empty string ("") in + cases where anonymity modes are not set, or the CM doesn't know + what the remote contact will see, or any other case where this + doesn't make sense.</p> + + <p>This MAY change over the lifetime of the channel, and SHOULD NOT + be used with the Request interface.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml new file mode 100644 index 0000000..b0aea59 --- /dev/null +++ b/spec/Channel_Interface_Call_State.xml @@ -0,0 +1,147 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Call_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2008 Nokia Corporation </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.CallState"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for streamed media channels that can indicate call + progress or call states. The presence of this interface is no guarantee + that call states will actually be signalled (for instance, SIP + implementations are not guaranteed to generate status 180 Ringing, so a + call can be accepted without the Ringing flag ever having been set; + similarly, Jingle implementations are not guaranteed to send + <code><ringing/></code>).</p> + + <p>To notify the other participant in the call that they are on hold, + see <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Hold</tp:dbus-ref>.</p> + </tp:docstring> + <tp:added version="0.17.2"/> + + <method name="GetCallStates" tp:name-for-bindings="Get_Call_States"> + <tp:docstring> + Get the current call states for all contacts involved in this call. + </tp:docstring> + + <arg tp:type="Channel_Call_State_Map" name="States" direction="out" + type="a{uu}"> + <tp:docstring> + The current call states. Participants where the call state flags + would be 0 (all unset) may be omitted from this mapping. + </tp:docstring> + </arg> + </method> + + <signal name="CallStateChanged" tp:name-for-bindings="Call_State_Changed"> + <tp:docstring> + Emitted when the state of a member of the channel has changed. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact. + </tp:docstring> + </arg> + + <arg name="State" type="u" tp:type="Channel_Call_State_Flags"> + <tp:docstring> + The new state for this contact. + </tp:docstring> + </arg> + </signal> + + <tp:mapping name="Channel_Call_State_Map"> + <tp:docstring> + A map from contacts to call states. + </tp:docstring> + + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact involved in this call.</tp:docstring> + </tp:member> + + <tp:member name="State" type="u" tp:type="Channel_Call_State_Flags"> + <tp:docstring>State flags for the given contact.</tp:docstring> + </tp:member> + </tp:mapping> + + <tp:flags name="Channel_Call_State_Flags" value-prefix="Channel_Call_State" type="u"> + <tp:docstring> + A set of flags representing call states. + </tp:docstring> + + <tp:flag suffix="Ringing" value="1"> + <tp:docstring> + The contact has been alerted about the call but has not responded + (e.g. 180 Ringing in SIP). + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Queued" value="2"> + <tp:docstring> + The contact is temporarily unavailable, and the call has been placed + in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Held" value="4"> + <tp:docstring> + The contact has placed the call on hold, and will not receive + media from the local user or any other participants until they + unhold the call again. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Forwarded" value="8"> + <tp:docstring> + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="In_Progress" value="16"> + <tp:docstring> + Progress has been made in placing the outgoing call, but the + destination contact may not have been made aware of the call yet + (so the Ringing state is not appropriate). This corresponds to SIP's + status code 183 Session Progress, and could be used when the + outgoing call has reached a gateway, for instance. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Conference_Host" value="32"> + <tp:added version='0.19.11'/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + </tp:docstring> + </tp:flag> + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml new file mode 100644 index 0000000..27515d2 --- /dev/null +++ b/spec/Channel_Interface_Chat_State.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Chat_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.ChatState"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + + <tp:mapping name="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring>A map from contacts to their chat states.</tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact</tp:docstring> + </tp:member> + <tp:member name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring>The contact's chat state</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="ChatStates" tp:name-for-bindings="Chat_States" + access="read" type="a{uu}" tp:type="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map containing the chat states of all contacts in this + channel whose chat state is not Inactive.</p> + + <p>Contacts in this channel, but who are not listed in this map, + may be assumed to be in the Inactive state.</p> + + <p>In implementations that do not have this property, its value may be + assumed to be empty until a + <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates + otherwise.</p> + + <tp:rationale> + <p>This property was not present in older versions of telepathy-spec, + because chat states in XMPP are not state-recoverable (if you + miss the change notification signal, there's no way to know the + state). However, this property still allows clients to recover + state changes that were seen by the CM before the client started + to deal with the channel.</p> + + <p>In CMs that follow older spec versions, assuming Inactive will + mean that initial chat states will always be assumed to be + Inactive, which is the best we can do. XEP 0085 specifies + Inactive as the "neutral" state to be assumed unless told + otherwise.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="SetChatState" tp:name-for-bindings="Set_Chat_State"> + <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring> + The new state. + </tp:docstring> + </arg> + <tp:docstring> + Set the local state and notify other members of the channel that it + has changed. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + <signal name="ChatStateChanged" tp:name-for-bindings="Chat_State_Changed"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring> + The new state of this contact. + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the state of a member of the channel has changed. + This includes local state. + </tp:docstring> + </signal> + <tp:enum name="Channel_Chat_State" type="u"> + <tp:enumvalue suffix="Gone" value="0"> + <tp:docstring> + The contact has effectively ceased participating in the chat. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Inactive" value="1"> + <tp:docstring> + The contact has not been active for some time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Active" value="2"> + <tp:docstring> + The contact is actively participating in the chat. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Paused" value="3"> + <tp:docstring> + The contact has paused composing a message. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Composing" value="4"> + <tp:docstring> + The contact is composing a message to be sent to the chat. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for channels for receiving notifications of remote contacts' + state, and for notifying remote contacts of the local state.</p> + + <p>Clients should assume that a contact's state is Channel_Chat_State_Inactive + unless they receive a notification otherwise.</p> + + <p>The Channel_Chat_State_Gone state is treated differently to other states:</p> + <ul> + <li>It may not be used for multi-user chats</li> + <li>It may not be explicitly sent</li> + <li>It should be automatically sent when the channel is closed</li> + <li>It must not be sent to the peer if a channel is closed without being used</li> + <li>Receiving it must not cause a new channel to be opened</li> + </ul> + + <p>The different states are defined by XEP-0085, but may be applied to any suitable protocol.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml new file mode 100644 index 0000000..abda59e --- /dev/null +++ b/spec/Channel_Interface_Conference.xml @@ -0,0 +1,628 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Conference" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Channel.Interface.Conference"> + <tp:added version="0.19.13">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for multi-user conference channels that can "continue + from" one or more individual channels. This could be used to invite + other contacts to an existing 1-1 text conversation, combine two phone + calls into one conference call, and so on, with roughly the same API in + each case.</p> + + <tp:rationale> + <p>This interface addresses freedesktop.org <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug + #24906</a> (GSM-compatible conference calls) and <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug + #24939</a> (upgrading calls and chats to multi-user). + See those bugs for more rationale and use cases.</p> + </tp:rationale> + + <p>Existing channels are upgraded by requesting a new channel of the same + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>, + listing the channels to be merged into the new conference in the + <tp:member-ref>InitialChannels</tp:member-ref> property of the request. + If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and + <tp:member-ref>InitialInviteeIDs</tp:member-ref> are + <var>Allowed_Properties</var> in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>, + ad-hoc conferences to a set of contacts may be created by requesting a + channel, specifying + <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or + <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in + question. A request may specify these alongside + <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously + upgrade a channel to a conference and invite others to join it.</p> + + <p>Channels with this interface MAY also implement <tp:dbus-ref + namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref> + to support merging more 1-1 channels into an ongoing conference. + Similarly, 1-1 channels MAY implement <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to + support being broken out of a Conference channel.</p> + + <p>The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group</tp:dbus-ref> interface on Conference channels MAY use + channel-specific handles for participants; clients SHOULD support + both Conferences that have channel-specific handles, and those that + do not.</p> + + <tp:rationale> + <p>In the GSM case, the Conference's Group interface MAY have + channel-specific handles, to represent the fact that the same + phone number may be in a conference twice (for instance, it could be + the number of a corporate switchboard).</p> + + <p>In the XMPP case, the Conference's Group interface SHOULD have + channel-specific handles, to reflect the fact that the participants + have MUC-specific identities, and the user might also be able to see + their global identities, or not.</p> + + <p>In most other cases, including MSN and link-local XMPP, the + Conference's Group interface SHOULD NOT have channel-specific + handles, since users' identities are always visible.</p> + </tp:rationale> + + <p>Connection managers implementing channels with this interface + MUST NOT allow the object paths of channels that could be merged + into a Conference to be re-used, unless the channel re-using the + object path is equivalent to the channel that previously used it.</p> + + <tp:rationale> + <p>If you upgrade some channels into a conference, and then close + the original channels, <tp:member-ref>InitialChannels</tp:member-ref> + (which is immutable) will contain paths to channels which no longer + exist. This implies that you should not re-use channel object paths, + unless future incarnations of the path are equivalent.</p> + + <p>For instance, on protocols where you can only have + zero or one 1-1 text channels with Emily at one time, it would + be OK to re-use the same object path for every 1-1 text channel + with Emily; but on protocols where this is not true, it would + be misleading.</p> + </tp:rationale> + + <h4>Examples of usage</h4> + + <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged + into a single conference call by calling:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2] + })</code> + </blockquote> + + <p>which returns a new channel <var>Cn</var> implementing the conference + interface. (As a quirk of GSM, both 1-1 will cease to function normally + until they are <tp:dbus-ref + namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref> + from the conference, or the conference ends.)</p> + + <p>An XMPP 1-1 conversation <var>C3</var> (with + <tt>chris@example.com</tt>, say) can be continued in a newly created + multi-user chatroom by calling:</p> + + <blockquote> + <code>CreateChannel({ + ...ChannelType: ...Text, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3] + })</code> + </blockquote> + + <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC + at the same time:</p> + + <blockquote> + <code>CreateChannel({ + ...ChannelType: ...Text, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3], + ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net'] + })</code> + </blockquote> + + <p>To continue <var>C3</var> in a particular multi-user + chatroom (rather than the implementation inventing a unique name for + the room), call:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({ + ...ChannelType: ...Text, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: ...Room, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com', + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3] + })</code> + </blockquote> + + <p>Note the use of EnsureChannel — if a channel for + <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be + equivalent to inviting <tt>chris@example.com</tt> to the existing + channel.</p> + + <p>In the above cases, the text channel <var>C3</var> SHOULD remain open + and fully functional (until explicitly closed by a client); new + incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in + <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed + only to <tt>chris@example.com</tt>.</p> + + <tp:rationale> + <p>If there is an open 1-1 text channel with a contact, in every + other situation new messages will appear in that channel. Given + that the old channel remains open — which is the least surprising + behaviour, and eases us towards a beautiful world where channels + never close themselves — it stands to reason that it should be + where new messages from Chris should appear. On MSN, creating a + conference from <var>C3</var> should migrate the underlying + switchboard from <var>C3</var> to the new channel; this is an + implementation detail, and should not affect the representation on + D-Bus. With a suitable change of terminology, Skype has the same + behaviour.</p> + + <p>If the current handler of that channel doesn't want this to happen + (maybe it transformed the existing tab into the group chat window, + and so there'd be no UI element still around to show new messages), + then it should just <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the + old 1-1 channel; it'll respawn if necessary.</p> + </tp:rationale> + + <p>Either of the XMPP cases could work for Call channels, to + upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases + could in principle work for link-local XMPP (XEP-0174).</p> + + <p>XMPP and MSN do not natively have a concept of merging two or more + channels C1, C2... into one channel, Cn. However, the GSM-style + merging API can be supported on XMPP and MSN, as an API short-cut + for upgrading C1 into a conference Cn (which invites the + TargetHandle of C1 into Cn), then immediately inviting the + TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p> + + <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests' + >RequestableChannelClasses</tp:dbus-ref></h4> + + <p>A GSM connection might advertise the following channel class for + conference calls:</p> + + <blockquote> + <code> +( Fixed = {<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: + ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/> + },<br/> + Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>, + <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia' + >InitialAudio</tp:dbus-ref> + ]<br/> +) + </code> + </blockquote> + + <p>This indicates support for starting audio-only conference calls by + merging two or more existing channels (since + <tp:member-ref>InitialInviteeHandles</tp:member-ref> and + <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p> + + <p>An XMPP connection might advertise the following classes for ad-hoc + multi-user text chats:</p> + + <blockquote> + <code> +( Fixed = {<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: + ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/> + },<br/> + Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>, + <tp:member-ref>InitialInviteeHandles</tp:member-ref>, + <tp:member-ref>InitialInviteeIDs</tp:member-ref>, + <tp:member-ref>InvitationMessage</tp:member-ref> + ]<br/> +),<br/> +( Fixed = {<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: + ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>: + Room<br/> + },<br/> + Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/> + <tp:member-ref>InitialChannels</tp:member-ref>, + <tp:member-ref>InitialInviteeHandles</tp:member-ref>, + <tp:member-ref>InitialInviteeIDs</tp:member-ref>, + <tp:member-ref>InvitationMessage</tp:member-ref> + ]<br/> +) + </code> + </blockquote> + + <p>The first class indicates support for starting ad-hoc (nameless) chat + rooms, upgraded from existing 1-1 channels and/or inviting new + contacts, along with a message to be sent along with the invitations. + The second indicates support for upgrading to a particular named chat + room.</p> + </tp:docstring> + + <property name="Channels" tp:name-for-bindings="Channels" + access="read" type="ao"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The individual <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that + are continued by this conference, which have the same <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> = CONTACT.</p> + + <p>This property MUST NOT be requestable; instead, the + <tp:member-ref>InitialChannels</tp:member-ref> property may be + specified when requesting a channel.</p> + + <tp:rationale> + <p>This is consistent with requesting + <tp:member-ref>InitialInviteeHandles</tp:member-ref> and + <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than + requesting <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref> + and some hypothetical ID version of that property.</p> + </tp:rationale> + + <p>Change notification is via the + <tp:member-ref>ChannelMerged</tp:member-ref> and + <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p> + </tp:docstring> + </property> + + <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new channel is added to the value of + <tp:member-ref>Channels</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring>The channel that was added to + <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> + </arg> + + <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring>A new channel-specific handle for the <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of + <var>Channel</var>, as will appear in + <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a + global handle is used for + <var>Channel</var>'s TargetHandle on the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface + of this channel.</tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring> + </arg> + </signal> + + <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a channel is removed from the value of + <tp:member-ref>Channels</tp:member-ref>, either because it closed + or because it was split using the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Splittable.DRAFT.Split</tp:dbus-ref> method.</p> + + <p>If a channel is removed because it was closed, <tp:dbus-ref + namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted + before this signal.</p> + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring>The channel that was removed from + <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> + </arg> + + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Additional information about the removal, which may include + the same well-known keys as the Details argument of + <tp:dbus-ref namespace="ofdT.Channel.Interface.Group" + >MembersChangedDetailed</tp:dbus-ref>, with the same semantics. + </tp:docstring> + </arg> + </signal> + + <property name="InitialChannels" tp:name-for-bindings="Initial_Channels" + access="read" type="ao" tp:immutable="yes" tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p> + + <p>This property SHOULD be requestable. Omitting it from a request is + equivalent to providing it with an empty list as value. Requests + where its value has at least two channel paths SHOULD be expected to + succeed on any implementation of this interface. If + <tp:member-ref>InitialInviteeHandles</tp:member-ref> and + <tp:member-ref>InitialInviteeIDs</tp:member-ref> are + <var>Allowed_Properties</var> in <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests' + >RequestableChannelClasses</tp:dbus-ref>, then requests with zero + or one channel paths SHOULD also succeed; otherwise, clients SHOULD + NOT make requests with zero or one paths for this property.</p> + + <tp:rationale> + <p>In GSM, a pair of calls can be merged into a conference, but you + can't start a conference call from zero or one existing calls. In + XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 + channel into a chatroom; however, on these protocols, it is also + possible to fake GSM-style merging by upgrading the first channel, + then inviting the targets of all the other channels into it.</p> + </tp:rationale> + + <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD + NOT be altered by merging them into a conference. However, depending on + the protocol, the Channels MAY be placed in a "frozen" state by placing + them in this property's value or by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p> + + <tp:rationale> + <p>In Jingle, nothing special will happen to merged calls. UIs MAY + automatically place calls on hold before merging them, if that is + the desired behaviour; this SHOULD always work. Not doing + an implicit hold/unhold seems to preserve least-astonishment.</p> + + <p>In GSM, the calls that are merged go into a state similar to + Hold, but they cannot be unheld, only split from the conference + call using <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p> + </tp:rationale> + + <p>Depending on the protocol, it might be signalled to remote users + that this channel is a continuation of all the requested channels, + or that it is only a continuation of the first channel in the + list.</p> + + <tp:rationale> + <p>In MSN, the conference steals the underlying switchboard (protocol + construct) from one of its component channels, so the conference + appears to remote users to be a continuation of that channel and no + other. The connection manager has to make some arbitrary choice, so + we arbitrarily mandate that it SHOULD choose the first channel in + the list as the one to continue.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialInviteeHandles" + tp:name-for-bindings="Initial_Invitee_Handles" + access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes" + tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of additional contacts invited to this conference when it + was created.</p> + + <p>If it is possible to invite new contacts when creating a conference + (as opposed to merging several channels into one new conference + channel), this property SHOULD be requestable, and appear in the allowed + properties in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property + SHOULD NOT be requestable, and its value SHOULD always be the empty + list.</p> + + <tp:rationale> + <p>On GSM you have to place a 1-1 call before you can merge it into a + conference; on the other hand, you can invite new contacts to XMPP + Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a + 1-1 channel with them first.</p> + </tp:rationale> + + <p>If included in a request, the given contacts are automatically + invited into the new channel, as if they had been added with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles, + <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after + the channel was created.</p> + + <tp:rationale> + <p>This is a simple convenience API for the common case that a UI + upgrades a 1-1 chat to a multi-user chat solely in order to invite + someone else to participate.</p> + </tp:rationale> + + <p>If the local user was not the initiator of this channel, the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this + property, together with any other contacts invited at the same time + (if that information is known).</p> + + <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be + combined in a single request.</p> + + <tp:rationale> + <p>For example, if you have a 1-1 channel C1 with Rob, and you want + to invite Sjoerd to join the discussion, you can do so by + requesting a channel with InitialChannels=[C1] and + InitialInviteeHandles=[sjoerd], + or InitialChannels=[C1] and + InitialInviteeIDs=["sjoerd@example.com"].</p> + </tp:rationale> + + <p>If a request includes some combination of InitialInviteeHandles, + InitialInviteeIDs and InitialChannels, then the value of + InitialInviteeHandles on the resulting channel SHOULD be the union of + the handles from InitialInviteeHandles, the handles corresponding + to the InitialInviteeIDs, and the target handles of the + InitialChannels, with any duplicate handles removed. Because this + property is immutable, its value SHOULD be computed before the + channel is announced via the NewChannels signal.</p> + + <tp:rationale> + <p>This simplifies identification of new channels in clients - they + only have to look at one of the properties, not both. For example, + after either of the requests mentioned above, the NewChannels + signal would announce the channel with InitialChannels=[C1], + InitialInviteeHandles=[rob, sjoerd], and + InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialInviteeIDs" + tp:name-for-bindings="Initial_Invitee_IDs" + access="read" type="as" tp:immutable="yes" tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of additional contacts invited to this conference when it + was created.</p> + + <p>This property SHOULD be requestable if and only if + <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable. + Its semantics are the same, except that it takes a list of the + string representations of contact handles; invitations are sent to + any contact present in either or both of these properties.</p> + + <p>When a channel is created, the values of InitialInviteeHandles and + InitialInviteeIDs MUST correspond to each other. In particular, this + means that the value of InitialInviteeIDs will include the TargetID + of each channel in InitialChannels, and the ID corresponding to each + handle in InitialInviteeHandles.</p> + </tp:docstring> + </property> + + <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message" + access="read" type="s" tp:immutable="yes" tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The message that was sent to the + <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were + invited.</p> + + <p>This property SHOULD be requestable, and appear in the allowed + properties in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref>, in protocols where + invitations can have an accompanying text message.</p> + + <tp:rationale> + <p>This allows invitations with a message to be sent when using + <tp:member-ref>InitialInviteeHandles</tp:member-ref> or + <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p> + </tp:rationale> + + <p>If the local user was not the initiator of this channel, the + message with which they were invited (if any) SHOULD appear in the + value of this property.</p> + </tp:docstring> + </property> + + <property name="OriginalChannels" tp:name-for-bindings="Original_Channels" + type="a{uo}" tp:type="Channel_Originator_Map" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>On GSM conference calls, it is possible to have the same phone + number in a conference twice; for instance, it could be the number of + a corporate switchboard. This is represented using channel-specific + handles; whether or not a channel uses channel-specific handles is + reported in <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref> + property specifies the mapping from opaque channel-specific handles + to actual numbers; this property specifies the original 1-1 channel + corresponding to each channel-specific handle in the conference.</p> + + <p>In protocols where this situation cannot arise, such as XMPP, + this property MAY remain empty.</p> + + <p>For example, consider this situation:</p> + + <ol> + <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact + <tt>+441234567890</tt> (which is assigned the handle <var>h</var>, + say), and ask to be put through to Simon McVittie;</li> + <li>Put that call on hold;</li> + <li>Place another call (with path <tt>/call/to/jonny</tt>) to + <tt>+441234567890</tt>, and ask to be put + through to Jonny Lamb;</li> + <li>Request a new channel with + <tp:member-ref>InitialChannels</tp:member-ref>: + <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li> + </ol> + + <p>The new channel will have the following properties, for some handles + <var>s</var> and <var>j</var>:</p> + + <blockquote> + <code>{<br/> + ...<tp:dbus-ref + namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>: + Channel_Specific_Handles | (other flags),<br/> + ...<tp:dbus-ref + namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>: + [self_handle, s, j],<br/> + ...<tp:dbus-ref + namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>: + { s: h, j: h },<br/> + ...<tp:member-ref>InitialChannels</tp:member-ref>: + ['/call/to/simon', '/call/to/jonny'],<br/> + ...<tp:member-ref>Channels</tp:member-ref>: + ['/call/to/simon', '/call/to/jonny'],<br/> + ...<tp:member-ref>OriginalChannels</tp:member-ref>: + { s: '/call/to/simon', j: '/call/to/jonny' },<br/> + # ...standard properties like ChannelType: Group elided...<br/> + }</code> + </blockquote> + + <p>Change notification is via the + <tp:member-ref>ChannelMerged</tp:member-ref> and + <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if + <var>Channel_Specific_Handle</var> in the former is non-zero, this + property SHOULD be updated to map that handle to the merged channel's + path.</p> + </tp:docstring> + </property> + + <tp:mapping name="Channel_Originator_Map"> + <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A channel-specific handle for a participant in this conference. + </tp:docstring> + </tp:member> + <tp:member name="Original_Channel" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The object path of <tp:member-ref>Channels</tp:member-ref> + representing the original 1-1 channel with + <var>Channel_Specific_Handle</var>. + </tp:docstring> + </tp:member> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A mapping from members of a conference to the original 1-1 channel with + that contact, if any. See + <tp:member-ref>OriginalChannels</tp:member-ref> for details. + </tp:docstring> + </tp:mapping> + </interface> +</node> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml new file mode 100644 index 0000000..d74ea6f --- /dev/null +++ b/spec/Channel_Interface_DTMF.xml @@ -0,0 +1,342 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF"> + <tp:xor-requires> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> + </tp:xor-requires> + <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this + interface should now be ignored by CMs. This is primarily to allow this + interface to be used with <tp:dbus-ref + namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> + channels.</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An interface that gives a Channel the ability to send DTMF events over + audio streams which have been established using the StreamedMedia channel + type. The event codes used are in common with those defined in <a + href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are + listed in the <tp:type>DTMF_Event</tp:type> enumeration. + </tp:docstring> + + <method name="StartTone" tp:name-for-bindings="Start_Tone"> + <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became + vestigial.</tp:changed> + <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> + <tp:docstring>A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the tone SHOULD be sent to all + eligible streams in the channel.</tp:docstring> + </arg> + <arg direction="in" name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring> + </arg> + + <tp:docstring> + <p>Start sending a DTMF tone to all eligible streams in the channel. + Where possible, the tone will continue until + <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols, + it may only be possible to send events with a predetermined length. In + this case, the implementation MAY emit a fixed-length tone, and the + StopTone method call SHOULD return NotAvailable.</p> + <tp:rationale> + The client may wish to control the exact duration and timing of the + tones sent as a result of user's interaction with the dialpad, thus + starting and stopping the tone sending explicitly. + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + There are no eligible audio streams. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StopTone" tp:name-for-bindings="Stop_Tone"> + <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became + vestigial.</tp:changed> + <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> + <tp:docstring>A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the sending SHOULD be stoped in + all eligible streams in the channel.</tp:docstring> + </arg> + + <tp:docstring> + Stop sending any DTMF tones which have been started using the + <tp:member-ref>StartTone</tp:member-ref> or + <tp:member-ref>MultipleTones</tp:member-ref> methods. + If there is no current tone, this method will do nothing. + If MultipleTones was used, the client should not assume the + sending has stopped immediately; instead, the client should wait + for the StoppedTones signal. + <tp:rationale> + On some protocols it might be impossible to cancel queued tones + immediately. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Continuous tones are not supported by this stream. Deprecated, + since stream IDs are ignored. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones"> + <tp:added version="0.19.6" /> + <tp:changed version="0.21.3">The characters [pPxXwW,] must + also be supported.</tp:changed> + <arg direction="in" name="Tones" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string representation of one or more DTMF + events. Implementations of this method MUST support all of the + following characters in this string:</p> + + <ul> + <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#' + correspond to the members of <tp:type>DTMF_Event</tp:type></li> + + <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an + implementation-defined pause, typically for 3 seconds</li> + + <li>'w' or 'W' waits for the user to continue, by stopping + interpretation of the string, and if there is more to be played, + emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal + with the rest of the string as its argument: see that signal + for details</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + <p>Send multiple DTMF events to all eligible streams in the channel. + Each tone will be played for an implementation-defined number of + milliseconds (typically 250ms), followed by a gap before the next tone + is played (typically 100ms). The + duration and gap are defined by the protocol or connection manager.</p> + + <tp:rationale> + <p>In cases where the client knows in advance the tone sequence it + wants to send, it's easier to use this method than manually start + and stop each tone in the sequence.</p> + + <p>The tone and gap lengths may need to vary for interoperability, + according to the protocol and other implementations' ability to + recognise tones. At the time of writing, GStreamer uses a + minimum of 250ms tones and 100ms gaps when playing in-band DTMF + in the normal audio stream, or 70ms tones and 50ms gaps when + encoding DTMF as <code>audio/telephone-event</code>.</p> + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The supplied Tones string was invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + There are no eligible audio streams. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="CurrentlySendingTones" + tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read"> + <tp:added version="0.19.6" /> + <tp:docstring> + Indicates whether there are DTMF tones currently being sent in the + channel. If so, the client should wait for + <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to + send more tones. + </tp:docstring> + </property> + + <property name="InitialTones" tp:name-for-bindings="Initial_Tones" + type="s" access="read"> + <tp:added version="0.19.6" /> + <tp:docstring> + <p>If non-empty in a channel request that will create a new channel, + the connection manager should send the tones immediately after + at least one eligible audio stream has been created in the + channel.</p> + + <p>This property is immutable (cannot change).</p> + </tp:docstring> + </property> + + <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones" + type="s" access="read"> + <tp:added version="0.21.3" /> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The tones waiting for the user to continue, if any.</p> + + <p>When this property is set to a non-empty value, + <tp:member-ref>TonesDeferred</tp:member-ref> is emitted. + When any tones are played (i.e. whenever + <tp:member-ref>SendingTones</tp:member-ref> is emitted), + this property is reset to the empty string.</p> + </tp:docstring> + </property> + + <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred"> + <tp:added version="0.21.3" /> + <arg name="Tones" type="s"> + <tp:docstring>The new non-empty value of + <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when 'w' or 'W', indicating "wait for the user to continue", + is encountered while playing a DTMF string queued by + <tp:member-ref>MultipleTones</tp:member-ref> or + <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events + after the 'w', which have not yet been played, are placed in the + <tp:member-ref>DeferredTones</tp:member-ref> property and copied + into this signal's argument.</p> + + <p>When the channel handler is ready to continue, it MAY pass the + value of <tp:member-ref>DeferredTones</tp:member-ref> to + <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending. + Alternatively, it MAY ignore the deferred tones, or even play + different tones instead. Any deferred tones are discarded the next + time a tone is played.</p> + + <p>This signal SHOULD NOT be emitted if there is nothing left to play, + i.e. if the 'w' was the last character in the DTMF string.</p> + </tp:docstring> + </signal> + + <signal name="SendingTones" tp:name-for-bindings="Sending_Tones"> + <tp:added version="0.19.6" /> + <arg name="Tones" type="s"> + <tp:docstring>DTMF string (one or more events) that is to be played. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tone(s)are being sent to all eligible streams in the channel. + The signal is provided to indicating the fact that the streams are + currently being used to send one or more DTMF tones, so any other + media input is not getting through to the audio stream. It also + serves as a cue for the + <tp:member-ref>StopTone</tp:member-ref> method.</p> + </tp:docstring> + </signal> + + <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones"> + <tp:added version="0.19.6" /> + <arg name="Cancelled" type="b"> + <tp:docstring>True if the DTMF tones were actively cancelled via + <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tones have finished playing on streams in this channel.</p> + </tp:docstring> + </signal> + + <tp:enum name="DTMF_Event" type="y"> + <tp:enumvalue suffix="Digit_0" value="0"> + <tp:docstring>0</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_1" value="1"> + <tp:docstring>1</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_2" value="2"> + <tp:docstring>2</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_3" value="3"> + <tp:docstring>3</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_4" value="4"> + <tp:docstring>4</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_5" value="5"> + <tp:docstring>5</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_6" value="6"> + <tp:docstring>6</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_7" value="7"> + <tp:docstring>7</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_8" value="8"> + <tp:docstring>8</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Digit_9" value="9"> + <tp:docstring>9</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Asterisk" value="10"> + <tp:docstring>*</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Hash" value="11"> + <tp:docstring>#</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Letter_A" value="12"> + <tp:docstring>A</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Letter_B" value="13"> + <tp:docstring>B</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Letter_C" value="14"> + <tp:docstring>C</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Letter_D" value="15"> + <tp:docstring>D</tp:docstring> + </tp:enumvalue> + </tp:enum> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml new file mode 100644 index 0000000..ce55923 --- /dev/null +++ b/spec/Channel_Interface_Destroyable.xml @@ -0,0 +1,82 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Destroyable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Channel.Interface.Destroyable"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.14">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to support channels where + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + is insufficiently destructive. At the moment this means + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref>, + but the existence of this interface means that unsupported channels + can be terminated in a non-channel-type-specific way.</p> + </tp:docstring> + + <method name="Destroy" tp:name-for-bindings="Destroy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Close the channel abruptly, possibly with loss of data. The + connection manager MUST NOT re-create the channel unless/until + more events occur.</p> + + <tp:rationale> + <p>The main motivating situation for this method is that when a Text + channel with pending messages is closed with Close, it comes back + as an incoming channel (to avoid a race between Close and an + incoming message). If Destroy is called on a Text channel, the CM + should delete all pending messages and close the channel, and + the channel shouldn't be re-created until/unless another message + arrives.</p> + </tp:rationale> + + <p>Most clients SHOULD call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + instead. However, if a client explicitly intends to destroy the + channel with possible loss of data, it SHOULD call this method + if this interface is supported (according to the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref> + property), falling back to Close if not.</p> + + <p>In particular, channel dispatchers SHOULD use this method if + available when terminating channels that cannot be handled + correctly (for instance, if no handler has been installed for + a channel type, or if the handler crashes repeatedly).</p> + + <p>Connection managers do not need to implement this interface on + channels where Close and Destroy would be equivalent.</p> + + <tp:rationale> + <p>Callers need to be able to fall back to Close in any case.</p> + </tp:rationale> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml new file mode 100644 index 0000000..92de9c5 --- /dev/null +++ b/spec/Channel_Interface_Group.xml @@ -0,0 +1,1166 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Group"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List"> + <tp:docstring>A structure representing a contact whose attempt to + join a group is to be confirmed by the local user using + <tp:member-ref>AddMembers</tp:member-ref>.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added"> + <tp:docstring> + The contact to be added to the group + </tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Contact_Handle" name="Actor"> + <tp:docstring> + The contact requesting or causing the change + </tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason"> + <tp:docstring> + The reason for the change + </tp:docstring> + </tp:member> + <tp:member type="s" name="Message"> + <tp:docstring> + A human-readable message from the Actor, or an empty string + if there is no message + </tp:docstring> + </tp:member> + </tp:struct> + + <method name="AddMembers" tp:name-for-bindings="Add_Members"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of contact handles to invite to the channel + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="s"> + <tp:docstring> + A string message, which can be blank if desired + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Invite all the given contacts into the channel, or accept requests for + channel membership for contacts on the pending local list.</p> + + <p>A message may be provided along with the request, which will be sent + to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and + CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT + <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this + message should be provided.</p> + + <p>Attempting to add contacts who are already members is allowed; + connection managers must silently accept this, without error.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + </tp:possible-errors> + </method> + + <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members"> + <tp:deprecated version="0.17.6">Use GetAll on the D-Bus + Properties D-Bus interface to get properties including Members, + RemotePendingMembers and LocalPendingMembers instead, falling back to + this method and GetLocalPendingMembersWithInfo if necessary. + </tp:deprecated> + + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Members"> + <tp:docstring> + array of handles of current members + </tp:docstring> + </arg> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Local_Pending"> + <tp:docstring> + array of handles of local pending members + </tp:docstring> + </arg> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Remote_Pending"> + <tp:docstring> + array of handles of remote pending members + </tp:docstring> + </arg> + <tp:docstring> + Returns arrays of all current, local and remote pending channel + members. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u"> + <tp:flag suffix="Can_Add" value="1"> + <tp:docstring> + The <tp:member-ref>AddMembers</tp:member-ref> method can be used to + add or invite members who are + not already in the local pending list (which is always valid). + </tp:docstring> + </tp:flag> + <tp:flag suffix="Can_Remove" value="2"> + <tp:docstring> + The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used + to remove channel members + (removing those on the pending local list is always valid). + </tp:docstring> + </tp:flag> + <tp:flag suffix="Can_Rescind" value="4"> + <tp:docstring> + The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used + on people on the remote + pending list. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Add" value="8"> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>AddMembers</tp:member-ref> on + contacts who are not currently pending members. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Remove" value="16"> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>RemoveMembers</tp:member-ref> on + contacts who are currently channel members. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Accept" value="32"> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>AddMembers</tp:member-ref> on + contacts who are locally pending. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Reject" value="64"> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>RemoveMembers</tp:member-ref> on + contacts who are locally pending. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Rescind" value="128"> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>RemoveMembers</tp:member-ref> on + contacts who are remote pending. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Channel_Specific_Handles" value="256"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The members of this group have handles which are specific to + this channel, and are not valid as general-purpose handles on + the connection. Depending on the channel, it may be possible to + check the <tp:member-ref>HandleOwners</tp:member-ref> property or + call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the + owners of these handles, which should be done if you wish to (e.g.) + subscribe to the contact's presence. + </p> + + <p> + Connection managers must ensure that any given handle is not + simultaneously a general-purpose handle and a channel-specific + handle. + </p> + </tp:docstring> + </tp:flag> + <tp:flag suffix="Only_One_Group" value="512"> + <tp:docstring> + Placing a contact in multiple groups of this type is not allowed + and will raise NotAvailable (on services where contacts may only + be in one user-defined group, user-defined groups will have + this flag). + </tp:docstring> + </tp:flag> + <tp:flag suffix="Handle_Owners_Not_Available" value="1024"> + <tp:docstring> + In rooms with channel specific handles (ie Channel_Specific_Handles + flag is set), this flag indicates that no handle owners are + available, apart from the owner of the + <tp:member-ref>SelfHandle</tp:member-ref>. + + <tp:rationale> + This used to be an important optimization to avoid repeated + GetHandleOwners calls, before we introduced the + <tp:member-ref>HandleOwners</tp:member-ref> property and + <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. + </tp:rationale> + </tp:docstring> + </tp:flag> + <tp:flag suffix="Properties" value="2048"> + <tp:docstring> + This flag indicates that all the properties introduced in + specification 0.17.6 are fully supported. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Members_Changed_Detailed" value="4096"> + <tp:docstring> + Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref> + will be emitted for changes to this group's members in addition to + <tp:member-ref>MembersChanged</tp:member-ref>. + Clients can then connect to the former and ignore emission of the + latter. This flag's state MUST NOT change over the lifetime of a + channel. + + <tp:rationale> + If it were allowed to change, client bindings would have to always + connect to MembersChanged just in case the flag ever went away (and + generally be unnecessarily complicated), which would mostly negate + the point of having this flag in the first place. + </tp:rationale> + </tp:docstring> + </tp:flag> + <tp:flag suffix="Message_Depart" value="8192"> + <tp:added version="0.17.21"/> + <tp:docstring> + A message may be sent to the server when calling + <tp:member-ref>RemoveMembers</tp:member-ref> on + the <tp:member-ref>SelfHandle</tp:member-ref>. + + <tp:rationale> + This would be set for XMPP Multi-User Chat or IRC channels, + but not for a typical implementation of streamed media calls. + </tp:rationale> + </tp:docstring> + </tp:flag> + </tp:flags> + + <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags" + access="read" tp:name-for-bindings="Group_Flags"> + <tp:docstring> + An integer representing the bitwise-OR of flags on this + channel. The user interface can use this to present information about + which operations are currently valid. Change notification is via + the <tp:member-ref>GroupFlagsChanged</tp:member-ref> signal. + </tp:docstring> + <tp:added version="0.17.6">For backwards compatibility, + clients should fall back to calling GetGroupFlags if + Channel_Group_Flag_Properties is not present.</tp:added> + </property> + + <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags"> + <arg direction="out" type="u" tp:type="Channel_Group_Flags" + name="Group_Flags"> + <tp:docstring> + The value of the GroupFlags property + </tp:docstring> + </arg> + <tp:docstring> + Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> property. + </tp:docstring> + <tp:deprecated version="0.17.6">Use GetAll on the D-Bus + Properties D-Bus interface to get properties including GroupFlags + instead, falling back to this method if necessary.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <tp:mapping name="Handle_Owner_Map"> + <tp:docstring> + A map from channel-specific handles to their owners. + </tp:docstring> + <tp:added version="0.17.6">For backwards compatibility, + clients should fall back to calling GetHandleOwners if + Channel_Group_Flag_Properties is not present.</tp:added> + + <tp:member type="u" name="Channel_Specific_Handle" + tp:type="Contact_Handle"> + <tp:docstring> + A nonzero channel-specific handle + </tp:docstring> + </tp:member> + <tp:member type="u" name="Global_Handle" tp:type="Contact_Handle"> + <tp:docstring> + The global handle that owns the corresponding channel-specific + handle, or 0 if this could not be determined + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map" + access="read" tp:name-for-bindings="Handle_Owners"> + <tp:docstring> + A map from channel-specific handles to their owners, including + at least all of the channel-specific handles in this channel's members, + local-pending or remote-pending sets as keys. Any handle not in + the keys of this mapping is not channel-specific in this channel. + Handles which are channel-specific, but for which the owner is + unknown, MUST appear in this mapping with 0 as owner. Change + notification is via the + <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. + </tp:docstring> + <tp:added version="0.17.6"/> + </property> + + <signal name="HandleOwnersChanged" + tp:name-for-bindings="Handle_Owners_Changed"> + <tp:docstring> + Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref> + property changes. + </tp:docstring> + <tp:added version="0.17.6">This signal should not be relied on + unless Channel_Group_Flag_Properties is present.</tp:added> + + <arg name="Added" type="a{uu}" tp:type="Handle_Owner_Map"> + <tp:docstring> + A map from channel-specific handles to their owners, in which the + keys include all the handles that were added to the keys of the + HandleOwners property, and all the handles in that property whose + owner has changed + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The channel-specific handles that were removed from the keys of the + HandleOwners property, as a result of the contact leaving this group + in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal + </tp:docstring> + </arg> + </signal> + + <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners"> + <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of integer handles representing members of the channel + </tp:docstring> + </arg> + <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners"> + <tp:docstring> + An array of integer handles representing the owner handles of + the given room members, in the same order, or 0 if the + owner is not available + </tp:docstring> + </arg> + <tp:docstring> + If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on + the channel, then the handles of the group members are specific + to this channel, and are not meaningful in a connection-wide + context such as contact lists. This method allows you to find + the owner of the handle if it can be discovered in this channel, + or 0 if the owner is not available. + </tp:docstring> + <tp:deprecated version="0.17.6">Clients should use the + HandleOwners property and HandleOwnersChanged signal if + Channel_Group_Flag_Properties is present.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag, + so handles in this channel are globally meaningful and calling + this method is not necessary + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + One of the given handles is not a member + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetLocalPendingMembers" + tp:name-for-bindings="Get_Local_Pending_Members"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> + <tp:docstring> + Returns the To_Be_Added handle (only) for each structure in the + <tp:member-ref>LocalPendingMembers</tp:member-ref> property. + </tp:docstring> + <tp:deprecated version="0.17.6">Use the LocalPendingMembers + property, if Channel_Group_Flag_Properties is present.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="GetLocalPendingMembersWithInfo" + tp:name-for-bindings="Get_Local_Pending_Members_With_Info"> + <tp:added version="0.15.0" /> + <tp:docstring> + Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> property. + </tp:docstring> + <tp:deprecated version="0.17.6">Use the LocalPendingMembers + property, if Channel_Group_Flag_Properties is present.</tp:deprecated> + <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]" + name="Info"> + <tp:docstring> + An array of structs containing: + <ul> + <li> + A handle representing the contact requesting channel membership + </li> + <li> + A handle representing the contact making the request, or 0 if + unknown + </li> + <li> + The reason for the request: one of the values of + <tp:type>Channel_Group_Change_Reason</tp:type> + </li> + <li> + A string message containing the reason for the request if any (or + blank if none) + </li> + </ul> + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <property name="LocalPendingMembers" access="read" + type="a(uuus)" tp:type="Local_Pending_Info[]" + tp:name-for-bindings="Local_Pending_Members"> + <tp:docstring> + An array of structs containing handles representing contacts + requesting channel membership and awaiting local approval with + <tp:member-ref>AddMembers</tp:member-ref>. + </tp:docstring> + <tp:added version="0.17.6">If Channel_Group_Flag_Properties is + not present, clients should fall back to using the + deprecated GetLocalPendingMembersWithInfo method, or fall back + from that to the deprecated GetAllMembers method.</tp:added> + </property> + + <property name="Members" tp:name-for-bindings="Members" + access="read" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The members of this channel. + </tp:docstring> + <tp:added version="0.17.6">If Channel_Group_Flag_Properties + is not set, fall back to calling GetAllMembers.</tp:added> + </property> + + <method name="GetMembers" tp:name-for-bindings="Get_Members"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> + <tp:docstring> + Returns the <tp:member-ref>Members</tp:member-ref> property. + </tp:docstring> + <tp:deprecated version="0.17.6">Use the Members + property, if Channel_Group_Flag_Properties is present.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <property name="RemotePendingMembers" access="read" type="au" + tp:type="Contact_Handle[]" tp:name-for-bindings="Remote_Pending_Members"> + <tp:docstring> + An array of handles representing contacts who have been + invited to the channel and are awaiting remote approval. + </tp:docstring> + <tp:added version="0.17.6">If Channel_Group_Flag_Properties + is not set, fall back to calling GetAllMembers.</tp:added> + </property> + + <method name="GetRemotePendingMembers" + tp:name-for-bindings="Get_Remote_Pending_Members"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> + <tp:docstring> + Returns an array of handles representing contacts who have been + invited to the channel and are awaiting remote approval. + </tp:docstring> + <tp:deprecated version="0.17.6">Use the + <tp:member-ref>RemotePendingMembers</tp:member-ref> + property, if Channel_Group_Flag_Properties is present.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed"> + <tp:docstring> + Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property + changes. + </tp:docstring> + <tp:added version="0.17.6">This signal should not be relied on + unless Channel_Group_Flag_Properties is present.</tp:added> + + <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> + <tp:docstring> + The new value of the SelfHandle property. + </tp:docstring> + </arg> + </signal> + + <property name="SelfHandle" type="u" tp:type="Contact_Handle" + access="read" tp:name-for-bindings="Self_Handle"> + <tp:docstring> + The handle for the user on this channel (which can also be a + local or remote pending member), or 0 if the user is not a member at + all (which is likely to be the case, for instance, on <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref> + channels). Note that this is different from the result of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref> + on some protocols, so the value of this handle should + always be used with the methods of this interface. + </tp:docstring> + <tp:added version="0.17.6">For backwards compatibility, + clients should fall back to calling GetSelfHandle if + Channel_Group_Flag_Properties is not present.</tp:added> + </property> + + <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> + <arg direction="out" type="u" tp:type="Contact_Handle" + name="Self_Handle"/> + <tp:docstring> + Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref> + property. + </tp:docstring> + <tp:deprecated version="0.17.6">Clients should retrieve the + SelfHandle property using GetAll instead, + if Channel_Group_Flag_Properties is present.</tp:deprecated> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <signal name="GroupFlagsChanged" tp:name-for-bindings="Group_Flags_Changed"> + <arg name="Added" type="u" tp:type="Channel_Group_Flags"> + <tp:docstring> + A bitwise OR of the flags which have been set + </tp:docstring> + </arg> + <arg name="Removed" type="u" tp:type="Channel_Group_Flags"> + <tp:docstring> + A bitwise OR of the flags which have been cleared + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the flags as returned by + <tp:member-ref>GetGroupFlags</tp:member-ref> are changed. + The user interface should be updated as appropriate. + </tp:docstring> + </signal> + + <tp:enum name="Channel_Group_Change_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for a set of handles to move to one of + <tp:member-ref>Members</tp:member-ref>, + <tp:member-ref>LocalPendingMembers</tp:member-ref> or + <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed + from the group. A client may supply a reason when attempting to + remove members from a group with + <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons + are supplied by the CM when emitting + <tp:member-ref>MembersChanged</tp:member-ref> and + <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason + codes have different meanings depending on the <var>Actor</var> in a + MembersChanged signal.</p> + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>No reason was provided for this change.</p> + + <p>In particular, this reason SHOULD be used when representing + users joining a named chatroom in the usual way, users leaving + a chatroom by their own request, and normal termination of a + StreamedMedia call by the remote user.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed from + a group for this reason and the actor is not the SelfHandle, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Terminated</code>.</p> + + <p>If the SelfHandle is removed from a group for this reason and + the actor is also the SelfHandle, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a user going offline. Also used when + user is already offline, but this wasn't known previously.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called is offline, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason Offline.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If a handle is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Offline</code>.</p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Kicked" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a kick operation.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Busy" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a busy indication.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called is busy, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason Busy.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Busy</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invited" value="4"> + <tp:docstring> + The change is due to an invitation. This reason SHOULD only be used + when contacts are added to the remote-pending set (to indicate that + the contact has been invited) or to the members (to indicate that + the contact has accepted the invitation). + + <tp:rationale> + Otherwise, what would it mean? + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Banned" value="5"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a kick+ban operation.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Error" value="6"> + <tp:docstring> + The change is due to an error occurring. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invalid_Contact" value="7"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because the requested contact does not exist.</p> + + <p>For instance, if the user invites a nonexistent contact to a + chatroom or attempts to call a nonexistent contact, this could + be indicated by the CM adding that contact's handle to + remote-pending for reason None or Invited, then removing it for + reason Invalid_Contact. In the case of a 1-1 StreamedMedia + call, the CM SHOULD remove the self handle from the Group + in the same signal.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="No_Answer" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because the requested contact did not respond.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called did not respond, or the + local user did not respond to an incoming call, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason No_Answer.</p> + + <tp:rationale> + Documenting existing practice. + </tp:rationale> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.NoAnswer</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Renamed" value="9"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because a contact's unique identifier changed. + There must be exactly one handle in the removed set and exactly + one handle in one of the added sets. The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref> + signal on the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref> + interface will have been emitted for the same handles, + shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Permission_Denied" value="10"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because there was no permission to contact the + requested handle.</p> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>. + </p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Separated" value="11"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If members are removed with this reason code, the change is + because the group has split into unconnected parts which can only + communicate within themselves (e.g. netsplits on IRC use this + reason code). + </p> + <p> + If members are added with this reason code, the change is because + unconnected parts of the group have rejoined. If this channel + carries messages (e.g. <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref> + channels) applications must + assume that the contacts being added are likely to have missed some + messages as a result of the separation, and that the contacts + in the group are likely to have missed some messages from the + contacts being added. + </p> + <p>Note that from the added contacts' perspective, they have been + in the group all along, and the contacts we indicate to be in + the group (including the local user) have just rejoined + the group with reason Separated. Application protocols in Tubes + should be prepared to cope with this situation. + </p> + + <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be + removed from channels with this reason.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="MembersChanged" tp:name-for-bindings="Members_Changed"> + <arg name="Message" type="s"> + <tp:docstring> + A string message from the server, or blank if not + </tp:docstring> + </arg> + <arg name="Added" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members added to the channel + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members removed from the channel + </tp:docstring> + </arg> + <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members who are pending local approval + </tp:docstring> + </arg> + <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members who are pending remote approval + </tp:docstring> + </arg> + <arg name="Actor" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact handle of the person who made the change, or 0 + if not known + </tp:docstring> + </arg> + <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason"> + <tp:docstring> + A reason for the change + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when contacts join any of the three lists (members, local + pending or remote pending) or when they leave any of the three lists. + There may also be a message from the server regarding this change, + which may be displayed to the user if desired.</p> + + <p>All channel-specific handles that are mentioned in this signal + MUST be represented in the value of the + <tp:member-ref>HandleOwners</tp:member-ref> property. + In practice, this will mean that + <tp:member-ref>HandleOwnersChanged</tp:member-ref> is + emitted <em>before</em> emitting a MembersChanged signal in which + channel-specific handles are added, but that it is emitted + <em>after</em> emitting a MembersChanged signal in which + channel-specific handles are removed.</p> + + <p>See <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + for an overview of how group state changes are used to indicate the + progress of a call.</p> + </tp:docstring> + </signal> + + <tp:mapping name="Handle_Identifier_Map"> + <tp:docstring> + A map from handles to the corresponding normalized string identifier. + </tp:docstring> + <tp:added version="0.17.17"/> + + <tp:member type="u" name="Handle" tp:type="Contact_Handle"> + <tp:docstring> + A nonzero handle + </tp:docstring> + </tp:member> + <tp:member type="s" name="Identifier"> + <tp:docstring> + The same string that would be returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> + for this handle. + </tp:docstring> + </tp:member> + </tp:mapping> + + <signal name="MembersChangedDetailed" + tp:name-for-bindings="Members_Changed_Detailed"> + <arg name="Added" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members added to the channel + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members removed from the channel + </tp:docstring> + </arg> + <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members who are pending local approval + </tp:docstring> + </arg> + <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members who are pending remote approval + </tp:docstring> + </arg> + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Information about the change, which may include the following + well-known keys:</p> + + <dl> + <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt> + <dd>The contact handle of the person who made the change; 0 or + omitted if unknown or not applicable.</dd> + + <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt> + <dd>A reason for the change.</dd> + + <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt> + <dd> + <p>The string identifiers for handles mentioned in this signal, to + give clients the minimal information necessary to react to the + event without waiting for round-trips. Connection managers + SHOULD include the identifiers for members added to the group and + for the actor (if any); they MAY omit the identifiers for handles + which have been removed from the group.</p> + + <tp:rationale> + <p>On IRC, an event such as a netsplit could cause the vast + majority of a channel to leave. Given that clients should + already know the identifiers of a channel's members, including + potentially hundreds of strings in the netsplit signal is + unnecessary.</p> + </tp:rationale> + + <p>Clients MUST NOT assume that the presence or absence of a + handle in this mapping is meaningful. This mapping is merely + an optimization for round-trip reduction, and connection + managers MAY add additional handles, omit some handles, or + omit the mapping completely.</p> + </dd> + + <dt>message (s)</dt> + <dd>A string message from the server regarding the change</dd> + + <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt> + <dd>A (possibly implementation-specific) DBus error describing the + change, providing more specific information than the + <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This + MUST only be present if it is strictly more informative than + 'change-reason'; if present, 'change-reason' MUST be set to the + closest available reason. + + <tp:rationale> + A SIP connection manager might want to signal "402 Payment + required" as something more specific than Error or + Permission_Denied so that a SIP-aware UI could handle it + specially; including a namespaced error permits this to be done + without <tp:type>Channel_Group_Change_Reason</tp:type> being + extended to encompass every error any CM ever wants to report. + </tp:rationale> + </dd> + + <dt>debug-message (s)</dt> + <dd>Debugging information on the change. SHOULD NOT be shown to + users in normal circumstances.</dd> + </dl> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when contacts join any of the three lists (members, local + pending or remote pending) or when they leave any of the three + lists. This signal provides a superset of the information provided by + <tp:member-ref>MembersChanged</tp:member-ref>; + if the channel's <tp:member-ref>GroupFlags</tp:member-ref> + contains Members_Changed_Detailed, then clients may listen exclusively + to this signal in preference to that signal.</p> + + <p>All channel-specific handles that are mentioned in this signal + MUST be represented in the value of the + <tp:member-ref>HandleOwners</tp:member-ref> property. In practice, + this will mean that + <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted + <em>before</em> emitting a MembersChangedDetailed signal in which + channel-specific handles are added, but that it is emitted + <em>after</em> emitting a MembersChangedDetailed signal in which + channel-specific handles are removed.</p> + + <p>See <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + for an overview of how group state changes are used to indicate the + progress of a call.</p> + </tp:docstring> + <tp:added version="0.17.16"/> + </signal> + + <method name="RemoveMembers" tp:name-for-bindings="Remove_Members"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of contact handles to remove from the channel + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="s"> + <tp:docstring> + A string message, which can be blank if desired + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Requests the removal of contacts from a channel, reject their + request for channel membership on the pending local list, or + rescind their invitation on the pending remote list.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group, + it can be removed via this method, in order to leave the group + gracefully. This is the recommended way to leave a chatroom, close + or reject a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call, and so on.</p> + + <p>Accordingly, connection managers SHOULD support + doing this, regardless of the value of + <tp:member-ref>GroupFlags</tp:member-ref>. + If doing so fails with PermissionDenied, this is considered to a bug + in the connection manager, but clients MUST recover by falling back + to closing the channel with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + method.</p> + + <p>Removing any contact from the local pending list is always + allowed. Removing contacts other than the + <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members + is allowed if and only if Channel_Group_Flag_Can_Remove is in the + <tp:member-ref>GroupFlags</tp:member-ref>, + while removing contacts other than the + <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list + is allowed if and only if Channel_Group_Flag_Can_Rescind is in the + <tp:member-ref>GroupFlags</tp:member-ref>.</p> + + <p>A message may be provided along with the request, which will be + sent to the server if supported. See the + Channel_Group_Flag_Message_Remove, + Channel_Group_Flag_Message_Depart, + Channel_Group_Flag_Message_Reject and + Channel_Group_Flag_Message_Rescind + <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this + message should be provided.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RemoveMembersWithReason" + tp:name-for-bindings="Remove_Members_With_Reason"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of contact handles to remove from the channel + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="s"> + <tp:docstring> + A string message, which can be blank if desired + </tp:docstring> + </arg> + <arg direction="in" name="Reason" type="u" + tp:type="Channel_Group_Change_Reason"> + <tp:docstring> + A reason for the change + </tp:docstring> + </arg> + <tp:docstring> + As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may + be provided where + appropriate. The reason code may be ignored if the underlying + protocol is unable to represent the given reason. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The provided reason code was invalid. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels which have multiple members, and where the members + of the channel can change during its lifetime. Your presence in the channel + cannot be presumed by the channel's existence (for example, a channel you + may request membership of but your request may not be granted).</p> + + <p>This interface implements three lists: a list of current members + (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending + and remote pending members + (<tp:member-ref>LocalPendingMembers</tp:member-ref> and + <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively). + Contacts on the remote + pending list have been invited to the channel, but the remote user has not + accepted the invitation. Contacts on the local pending list have requested + membership of the channel, but the local user of the framework must accept + their request before they may join. A single contact should never appear on + more than one of the three lists. The lists are empty when the channel is + created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal + (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains + Members_Changed_Detailed, the + <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal) + should be emitted when information + is retrieved from the server, or changes occur.</p> + + <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or + <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates + that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from + the channel, and the channel subsequently emits <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>, + clients SHOULD consider the details given in the MembersChanged or + MembersChangedDetailed signal to be the reason why the channel closed.</p> + + <p>Addition of members to the channel may be requested by using + <tp:member-ref>AddMembers</tp:member-ref>. If + remote acknowledgement is required, use of the AddMembers method will cause + users to appear on the remote pending list. If no acknowledgement is + required, AddMembers will add contacts to the member list directly. If a + contact is awaiting authorisation on the local pending list, AddMembers + will grant their membership request.</p> + + <p>Removal of contacts from the channel may be requested by using + <tp:member-ref>RemoveMembers</tp:member-ref>. If a contact is awaiting + authorisation on the local pending + list, RemoveMembers will refuse their membership request. If a contact is + on the remote pending list but has not yet accepted the invitation, + RemoveMembers will rescind the request if possible.</p> + + <p>It should not be presumed that the requester of a channel implementing this + interface is immediately granted membership, or indeed that they are a + member at all, unless they appear in the list. They may, for instance, + be placed into the remote pending list until a connection has been + established or the request acknowledged remotely.</p> + + <p>If the local user joins a Group channel whose members or other state + cannot be discovered until the user joins (e.g. many chat room + implementations), the connection manager should ensure that the channel + is, as far as possible, in a consistent state before adding the local + contact to the members set; until this happens, the local contact should + be in the remote-pending set. For instance, if the connection manager + queries the server to find out the initial members list for the + channel, it should leave the local contact in the remote-pending set + until it has finished receiving the initial members list. + </p> + + <p>If the protocol provides no reliable way to tell whether the complete + initial members list has been received yet, the connection manager + should make a best-effort attempt to wait for the full list + (in the worst case, waiting for a suitable arbitrary timeout) + rather than requiring user interfaces to do so on its behalf.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_HTML.xml b/spec/Channel_Interface_HTML.xml new file mode 100644 index 0000000..ad86867 --- /dev/null +++ b/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/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml new file mode 100644 index 0000000..ef5a08f --- /dev/null +++ b/spec/Channel_Interface_Hold.xml @@ -0,0 +1,222 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Hold" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"> + <tp:xor-requires> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> + </tp:xor-requires> + <tp:changed version="0.17.4">first API-stable version</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels where you may put the channel on hold. + This only makes sense for channels where + you are streaming media to or from the members. (To see whether the + other participant has put you on hold, see <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref>.)</p> + + <p>If you place a channel on hold, this indicates that you do not wish + to be sent media streams by any of its members and will be ignoring + any media streams you continue to receive. It also requests that the + connection manager free up any resources that are only needed for + an actively used channel (e.g. in a GSM or PBX call, it will be + necessary to place an active call on hold before you can start + another call).</p> + </tp:docstring> + + <method name="GetHoldState" tp:name-for-bindings="Get_Hold_State"> + <tp:docstring> + Return whether the local user has placed the channel on hold. + </tp:docstring> + + <arg name="HoldState" direction="out" type="u" + tp:type="Local_Hold_State"> + <tp:docstring> + The state of the channel + </tp:docstring> + </arg> + + <arg name="Reason" direction="out" type="u" + tp:type="Local_Hold_State_Reason"> + <tp:docstring> + The reason why the channel is in that state + </tp:docstring> + </arg> + </method> + + <signal name="HoldStateChanged" tp:name-for-bindings="Hold_State_Changed"> + <tp:docstring> + Emitted to indicate that the hold state has changed for this channel. + This may occur as a consequence of you requesting a change with + <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a + result of a request from + another process. + </tp:docstring> + + <arg name="HoldState" type="u" tp:type="Local_Hold_State"> + <tp:docstring> + The state of the channel + </tp:docstring> + </arg> + + <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason"> + <tp:docstring> + The reason for the state change + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Local_Hold_State" type="u"> + <tp:docstring> + The hold state of a channel. + </tp:docstring> + + <tp:enumvalue value="0" suffix="Unheld"> + <tp:docstring> + All streams are unheld (the call is active). New channels SHOULD + have this hold state. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Held"> + <tp:docstring> + All streams are held (the call is on hold) + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Pending_Hold"> + <tp:docstring> + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="3" suffix="Pending_Unhold"> + <tp:docstring> + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Local_Hold_State_Reason" type="u"> + <tp:docstring> + The reason for a change to the Local_Hold_State. Clients MUST + treat unknown values as equivalent to Local_Hold_State_Reason_None. + </tp:docstring> + + <tp:enumvalue value="0" suffix="None"> + <tp:docstring> + The reason cannot be described by any of the predefined values + (connection managers SHOULD avoid this reason, but clients MUST + handle it gracefully) + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Requested"> + <tp:docstring> + The change is in response to a user request + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Resource_Not_Available"> + <tp:docstring> + The change is because some resource was not available + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="RequestHold" tp:name-for-bindings="Request_Hold"> + <arg direction="in" name="Hold" type="b"> + <tp:docstring> + A boolean indicating whether or not the channel should be on hold + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the channel be put on hold (be instructed not to send + any media streams to you) or be taken off hold.</p> + + <p>If the connection manager can immediately tell that the requested + state change could not possibly succeed, this method SHOULD + return the NotAvailable error. If the requested state is the + same as the current state, this method SHOULD return successfully + without doing anything.</p> + + <p>Otherwise, this method SHOULD immediately set the hold state to + Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold + (as appropriate), emitting + <tp:member-ref>HoldStateChanged</tp:member-ref> if this is a change, + and return successfully.</p> + + <p>The eventual success or failure of the request is indicated by a + subsequent HoldStateChanged signal, changing the hold state to + Local_Hold_State_Held or Local_Hold_State_Unheld.</p> + + <p>If the channel has multiple streams, and the connection manager + succeeds in changing the hold state of one stream but fails to + change the hold state of another, it SHOULD attempt to revert + all streams to their previous hold states.</p> + + <p>The following state transitions SHOULD be used, where + appropriate:</p> + + <ul> + <li>Successful hold: + (Unheld, any reason) → (Pending_Hold, Requested) → + (Held, Requested) + </li> + <li>Successful unhold: + (Held, any reason) → (Pending_Unhold, Requested) → + (Unheld, Requested) + </li> + <li>Attempting to unhold fails at the first attempt to acquire a + resource: + (Held, any reason) → (Pending_Unhold, Requested) → + (Held, Resource_Not_Available) + </li> + <li>Attempting to unhold acquires one resource, but fails to acquire + a second, and takes time to release the first: + (Held, any reason) → (Pending_Unhold, Requested) → + (Pending_Hold, Resource_Not_Available) → + (Held, Resource_Not_Available) + </li> + </ul> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested hold state cannot be achieved; for example, + if only a limited number of channels can be in the "not on hold" + state, attempts to exceed this number will raise NotAvailable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml new file mode 100644 index 0000000..242c952 --- /dev/null +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -0,0 +1,235 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for signalling a channel containing synchronised media + sessions which can contain an arbitrary number of streams. The + presence of this interface on a Channel indicates that the connection + manager will not carry out the actual streaming for this channel, + and that the client handling the channel is responsible for doing + so; in most cases we recommend doing this by using the + telepathy-farsight library.</p> + + <tp:rationale> + <p>Streaming audio and (particularly) video requires a high level of + integration with the UI, and having the connection manager act as + a proxy would be likely to introduce unacceptable latency. As a + result, audio/video streaming is offloaded into the client + where possible, as an exception to the general design of + Telepathy.</p> + </tp:rationale> + + <p>The negotiation interface is based on the API of the + <a href="http://farsight.freedesktop.org/">Farsight</a> library. + This, in turn, is based upon the IETF MMusic ICE drafts, where + connections are established by signalling potential connection + candidates to the peer until a usable connection is found, and + codecs are negotiated with an SDP-style offer and answer. However, + the principles should be applicable to other media streaming methods + and the API re-used without difficulty.</p> + + <p>Note that the naming conventions used in the MediaStreamHandler + and MediaSessionHandler interfaces are rather confusing; methods + have signal-like names and signals have method-like names, due to + the API being based rather too closely on that of Farsight. This + is for historical reasons and will be fixed in a future release + of the Telepathy specification.</p> + </tp:docstring> + + <tp:simple-type name="Media_Session_Type" type="s"> + <tp:docstring>The type of a media session. Currently, the only supported + value is "rtp".</tp:docstring> + </tp:simple-type> + + <tp:struct name="Media_Session_Handler_Info" + array-name="Media_Session_Handler_Info_List"> + <tp:docstring>A struct representing a active session handler.</tp:docstring> + <tp:member type="o" name="Session_Handler"> + <tp:docstring>The object path of the session handler, which is on the + same bus name as the channel.</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type"> + <tp:docstring>The media session's type</tp:docstring> + </tp:member> + </tp:struct> + + <method name="GetSessionHandlers" + tp:name-for-bindings="Get_Session_Handlers"> + <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]" + name="Session_Handlers"/> + <tp:docstring> + Returns all currently active session handlers on this channel + as a list of (session_handler_path, type). + </tp:docstring> + </method> + + <signal name="NewSessionHandler" tp:name-for-bindings="New_Session_Handler"> + <arg name="Session_Handler" type="o"> + <tp:docstring> + Object path of the new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Media.SessionHandler</tp:dbus-ref> + object + </tp:docstring> + </arg> + <arg name="Session_Type" tp:type="Media_Session_Type" type="s"> + <tp:docstring> + String indicating type of session, eg "rtp" + </tp:docstring> + </arg> + <tp:docstring> + Signal that a session handler object has been created. The client + should create a session object and create streams for the streams + within. + </tp:docstring> + </signal> + + <tp:property name="nat-traversal" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + A string indicating the NAT traversal techniques employed by the + streams within this channel if they do not have a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property. The possible values are the same as for the NATTraversal + property on the streams. + </tp:docstring> + </tp:property> + + <tp:property name="stun-server" type="s"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + The IP address or hostname of the STUN server to use for NAT traversal + if the individual streams do not specify one. + </tp:docstring> + </tp:property> + + <tp:property name="stun-port" type="q"> + <tp:deprecated version="0.17.22">Use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> + property on the Media.StreamHandler, if available; use this + as a fallback.</tp:deprecated> + <tp:docstring> + The UDP port number to use on the provided STUN server. + </tp:docstring> + </tp:property> + + <tp:property name="gtalk-p2p-relay-token" type="s"> + <tp:deprecated version="0.17.22">XMPP connection managers + supporting the Google Talk relay server SHOULD make the necessary + HTTP requests to find a username and password, and use those + to populate the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref> + property on the Media.StreamHandler.</tp:deprecated> + <tp:docstring> + The authentication token for use with the Google Talk peer-to-peer relay + server. + </tp:docstring> + </tp:property> + + <tp:hct name="gtalk-p2p"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>gtalk-p2p</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="ice-udp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>ice-udp</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="wlm-8.5"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>wlm-8.5</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="wlm-2009"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> + property is <code>wlm-2009</code>.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="video/h264" is-family="yes"> + <tp:docstring> + <p>The client supports media streaming with H264 (etc.).</p> + + <p>This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.</p> + + <tp:rationale> + <p>For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + <code>video/h264</code> on StreamedMedia channels.</p> + </tp:rationale> + + <p>For example, a client could advertise support for + Speex, Theora and H264 by having three + handler capability tokens, + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>, + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and + <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>, + in its <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> + property.</p> + + <p>Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.</p> + + <tp:rationale> + <p>This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.</p> + </tp:rationale> + </tp:docstring> + </tp:hct> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml new file mode 100644 index 0000000..cd606c1 --- /dev/null +++ b/spec/Channel_Interface_Mergeable_Conference.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Mergeable_Conference" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Conference"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for multi-user conference channels that can have + additional individual channels merged into them after they are + created.</p> + + <tp:rationale> + <p>This interface addresses part of freedesktop.org <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug + #24906</a> (GSM-compatible conference calls). GSM is currently + the only protocol known to implement this; PBXs might implement + it too.</p> + + <p>It might be made into a mandatory-to-implement part of Conference, + or kept as a separate interface, when stabilized.</p> + </tp:rationale> + </tp:docstring> + + <method name="Merge" + tp:name-for-bindings="Merge"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given channel be incorporated into this + channel.</p> + + <p>The given channel SHOULD be added to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Conference.Channels</tp:dbus-ref> if and only if the + underlying protocol signals the merge in some way. It MUST NOT be + added to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Conference.InitialChannels</tp:dbus-ref> (to preserve + immutability).</p> + + <tp:rationale> + <p>In GSM it is possible to merge additional calls into an ongoing + conference.</p> + + <p>In XMPP this method could be implemented to merge a 1-1 Text + channel into a MUC Text channel by inviting the peer from the Text + channel into the MUC, or to merge a 1-1 Jingle call into a Muji + call by inviting the peer from the Jingle call into the Muji call. + (MUC and Muji channels are both implemented by XMPP MUCs, with + Handle_Type_Room.)</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Channel" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel with the same <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref> + as this one, but with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> = CONTACT.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given channel isn't suitable for merging into this one: for + instance, it might have the wrong channel type or handle type. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It will never be possible to merge channels into this particular + conference. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The given channel is theoretically suitable for merging into this + one, but that's not currently possible for some reason (for + instance, this SHOULD be raised if a limit on the number of + channels in a conference is exceeded). + <strong>[FIXME: PermissionDenied?]</strong> + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml new file mode 100644 index 0000000..62e8384 --- /dev/null +++ b/spec/Channel_Interface_Messages.xml @@ -0,0 +1,1433 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Messages" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Channel.Interface.Messages"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + <tp:added version="0.17.16">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface extends the <tp:dbus-ref + namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref> + interface to support more general messages, including:</p> + + <ul> + <li>messages with attachments (like MIME multipart/mixed)</li> + <li>groups of alternatives (like MIME multipart/alternative)</li> + <li>delivery reports (which replace <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>), + addding support for protocols where the message content is not echoed + back to the sender on failure and for receiving positive + acknowledgements, as well as ensuring that incoming delivery reports + are not lost if no client is handling the channel yet;</li> + <li>any extra types of message we need in future</li> + </ul> + + <p>Incoming messages, outgoing messages, and delivery reports are all + represented as lists of <tp:type>Message_Part</tp:type> structures, + with a format reminiscent of e-mail. Messages are sent by calling + <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are + announced to other clients which may be interested in the channel by + the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming + messages and delivery reports are signalled by + <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the + the <tp:member-ref>PendingMessages</tp:member-ref> property until + acknowledged by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>. + Only the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + for a channel should acknowledge messages; <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s + (such as loggers) and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s + for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p> + + <tp:rationale> + <p>If observers were allowed to acknowledge messages, then messages + might have been acknowledged before the handler even got to see the + channel, and hence could not be shown to the user.</p> + </tp:rationale> + + <p>If this interface is present, clients that support it SHOULD + listen for the <tp:member-ref>MessageSent</tp:member-ref> and + <tp:member-ref>MessageReceived</tp:member-ref> signals, and + ignore the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> + signals on the Text interface (which are guaranteed to duplicate + signals from this interface).</p> + + <p>Although this specification supports formatted (rich-text) + messages with unformatted alternatives, implementations SHOULD NOT + attempt to send formatted messages until the Telepathy specification + has also been extended to cover capability discovery for message + formatting.</p> + + <tp:rationale> + We intend to expose all rich-text messages as XHTML-IM, but on some + protocols, formatting is an extremely limited subset of that format + (e.g. there are protocols where foreground/background colours, font + and size can be set, but only for entire messages). + Until we can tell UIs what controls to offer to the user, it's + unfriendly to offer the user controls that may have no effect. + </tp:rationale> + </tp:docstring> + + <property name="SupportedContentTypes" type="as" access="read" + tp:name-for-bindings="Supported_Content_Types" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of MIME types supported by this channel, with more preferred + MIME types appearing earlier in the list. The list MAY include "*/*" + to indicate that attachments with arbitrary MIME types can be sent. + This list MUST NOT be empty, since all Messages implementations + MUST accept messages containing a single "text/plain" part.</p> + + <p>Items in this list MUST be normalized to lower-case.</p> + + <p>Some examples of how this property interacts with the + <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p> + + <dl> + <dt>A simple IM implementation: only plain text messages are + allowed</dt> + <dd>SupportedContentTypes = ['text/plain'], + MessagePartSupportFlags = 0</dd> + + <dt>Formatted text with a plain text alternative is allowed (see the + HTML interface draft)</dt> + <dd>SupportedContentTypes = ['text/html', 'text/plain'], + MessagePartSupportFlags = 0</dd> + + <dt>JPEG or PNG images may be sent, but without any attached + text</dt> + <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = 0</dd> + + <dt>Unformatted text to which an optional JPEG or PNG image may be + attached</dt> + <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = One_Attachment</dd> + + <dt>Formatted text to which arbitrarily many images may be + attached</dt> + <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg', + 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments</dd> + + <dt>A full SIP implementation: arbitrary MIME messages are + allowed</dt> + <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments</dd> + </dl> + </tp:docstring> + </property> + + <property name="MessageTypes" type="au" + tp:type="Channel_Text_Message_Type[]" access="read" + tp:name-for-bindings="Message_Types" + tp:immutable="yes"> + <tp:added version="0.21.5"> + This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text" + >GetMessageTypes</tp:dbus-ref>; fall back to that method for + compatibility with older connection managers. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of message types which may be sent on this channel.</p> + </tp:docstring> + </property> + + <property name="MessagePartSupportFlags" type="u" + tp:type="Message_Part_Support_Flags" access="read" + tp:name-for-bindings="Message_Part_Support_Flags" + tp:immutable="yes"> + <tp:docstring> + Flags indicating the level of support for message parts on this + channel. + </tp:docstring> + </property> + + <tp:flags name="Message_Part_Support_Flags" + value-prefix="Message_Part_Support_Flag" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Flags indicating the level of support for message parts on this + channel. They are designed such that setting more flags always + implies that the channel has more capabilities.</p> + + <p>If no flags are set, this indicates that messages may contain + a single message part whose content-type is any of the types + from SupportedContentTypes, possibly with some alternatives.</p> + + <p>There is no flag indicating support for alternatives. This is + because the SendMessage implementation can always accept messages + containing alternatives, even if the underlying protocol does not, + by deleting all alternatives except the first (most preferred) + that is supported.</p> + + <tp:rationale> + Each of the flags so far implies the previous flag, so we could + have used a simple enumeration here; however, we've defined + the message-part support indicator as a flag set for future + expansion. + </tp:rationale> + + <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some + examples.</p> + </tp:docstring> + + <tp:flag suffix="One_Attachment" value="1"> + <tp:docstring> + <tp:member-ref>SendMessage</tp:member-ref> will accept messages + containing a textual message body, + plus a single attachment of any type listed in the + SupportedContentTypes property. It does not make sense for this + flag to be set if Message_Part_Support_Flag_Data_Only is not also set + (because the connection manager can trivially provide an empty text + part if necessary). + </tp:docstring> + </tp:flag> + <tp:flag suffix="Multiple_Attachments" value="2"> + <tp:docstring> + SendMessage will accept messages containing a textual message body, + plus an arbitrary number of attachments of any type listed in the + SupportedContentTypes property. It does not make sense for this + flag to be set if Message_Part_Support_Flag_One_Attachment is not + also set. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:mapping name="Message_Part" array-name="Message_Part_List" + array-depth="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Part of a message's content. In practice, this mapping never + appears in isolation: incoming messages are represented by a list of + <tp:type>Message_Part</tp:type> mappings in the + <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing + messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as + a list of these mappings.</p> + + <p>The first part of the message contains "headers", which refer + to the entire message. The second and subsequent parts contain the + message's content, including plain text, formatted text and/or + attached files. Well-known keys for the header and body parts are + defined by the <tp:type>Message_Header_Key</tp:type> and + <tp:type>Message_Body_Key</tp:type> types, respectively. It is an + error for a connection manager to put keys referring to the message + as a whole in the second or subsequent Message_Part, or keys intended + for body parts in the first Message_Part; clients MUST recover from + this error by ignoring these mis-placed keys.</p> + + <tp:rationale> + <p>Instead of representing messages as aa{sv} where the first + dictionary is special (a dictionary of headers), we could have + used a signature like (a{sv}aa{sv}) to separate out the headers + and the body parts.</p> + + <p>However, this would make access to the messages more awkward. + In Python, the syntax for access to a header field would remain + <code>message[0]['message-type']</code>, but access to a body + field in the second body part would change from + <code>message[2]['content'] to message[1][1]['content']</code>. In + GLib, the message would change from being a + <code>GPtrArray(GHashTable)</code> to being a + <code>GValueArray(GHashTable, GPtrArray(GHashTable))</code> which + is rather inconvenient to dereference.</p> + </tp:rationale> + + <p>In any group of parts with the same non-empty value for the + <tt>alternative</tt> key (which represent alternative versions of the + same content), more faithful versions of the intended message MUST + come before less faithful versions (note that this order is the + opposite of MIME <tt>multipart/alternative</tt> parts). Clients + SHOULD display the first alternative that they understand.</p> + + <tp:rationale> + <p>Specifying the preference order means that if the underlying + protocol doesn't support alternatives, the CM can safely delete + everything apart from the first supported alternative when + sending messages.</p> + + <p>The order is the reverse of MIME because MIME's rationale for + placing the "plainest" part first (legibility in pre-MIME UAs) + does not apply to us, and placing the most preferred part + first simplifies display (a client can iterate the message + in order, display the first alternative that it understands, + and skip displaying all subsequent parts with the same + "alternative" key).</p> + </tp:rationale> + + <p>Clients SHOULD present all parts that are not redundant + alternatives in the order they appear in this array, possibly + excluding parts that are referenced by another displayed part. + It is implementation-specific how the parts are presented to the + user.</p> + + <tp:rationale> + <p>This allows CMs to assume that all parts are actually shown to + the user, even if they are not explicitly referenced - we do + not yet recommend formatted text, and there is no way for + plain text to reference an attachment since it has no concept of + markup or references. This also forces clients to do something + sensible with messages that consist entirely of "attachments", + with no "body" at all.</p> + + <p>For instance, when displaying the above example, a client that + understands the HTML part should display the JPEG image once, + between the two lines "Here is a photo of my cat:" and + "Isn't it cute?"; it may additionally present the image in some + way for a second time, after "Isn't it cute?", or may choose + not to.</p> + + <p>A client that does not understand HTML, displaying the same + message, should display the plain-text part, followed by the JPEG + image.</p> + </tp:rationale> + + <p>Connection managers, clients and extensions to this specification + SHOULD NOT include <tp:type>Handle</tp:type>s as values in a + Message_Part, except for <code>message-sender</code> in the + header.</p> + + <tp:rationale> + <p>Reference-counting handles in clients becomes problematic if + the channel proxy cannot know whether particular map values + are handles or not.</p> + </tp:rationale> + + <h4>Example messages</h4> + + <p>A rich-text message, with an embedded image, might be represented + as:</p> + + <pre> +[ + { + 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c', + 'message-sender': 42, + 'message-sent': 1210067943, + 'message-received': 1210067947, + 'message-type': 0, # = Channel_Text_Message_Type_Normal + 'pending-message-id': 437, + }, + { 'alternative': 'main', + 'content-type': 'text/html', + 'content': 'Here is a photo of my cat:<br />' + + '<img src="cid:catphoto" alt="lol!" />' + + '<br />Isn't it cute?', + }, + { 'alternative': 'main', + 'content-type': 'text/plain', + 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?', + }, + { 'identifier': 'catphoto', + 'content-type': 'image/jpeg', + 'size': 101000, + 'needs-retrieval': True, + }, +]</pre> + + <p>telepathy-ring, Nokia's GSM connection manager, represents vCards + sent via SMS as:</p> + + <pre> +[ + { + 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c', + 'message-sender': 42, + 'message-sent': 1210067943, + 'message-received': 1210067947, + 'message-type': 0, # = Channel_Text_Message_Type_Normal + 'pending-message-id': 437, + }, + { 'content-type': 'text/x-vcard', + 'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes + }, +]</pre> + + <h3>Delivery reports</h3> + + <div> + <p>Delivery reports are also represented as messages with the + <tt>message-type</tt> header mapping to + <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report. + Delivery reports SHOULD contain the <tt>message-sender</tt> header, + mapping to the intended recipient of the original message, if + possible; other headers specific to delivery reports are defined by + the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second + and subsequent parts, if present, are a human-readable report from + the IM service.</p> + + <p>For backwards- and forwards-compatibility, whenever a delivery + error report is signalled—that is, with <tt>delivery-status</tt> + mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or + Permanently_Failed—<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> + SHOULD also be emitted; whenever <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> + is emitted, a delivery report MUST also be signalled. + Delivery report messages on this interface MUST be represented in + emissions of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> + as messages with the Non_Text_Content + <tp:type>Channel_Text_Message_Flags</tp:type>; clients which + understand this interface SHOULD ignore the SendError signal in + favour of listening for delivery reports, as mentioned in the + introduction.</p> + + <p>The result of attempting to send delivery reports using + <tp:member-ref>SendMessage</tp:member-ref> is currently + undefined.</p> + + <h4>Example delivery reports</h4> + + <dl> + <dt>A minimal delivery report indicating permanent failure of the + sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown + reason</dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +]</pre></dd> + + <dt>A delivery report where the failed message is echoed back to the + sender rather than being referenced by ID, and the failure reason + is that this protocol cannot send messages to offline contacts + such as the contact with handle 123</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Temporarily_Failed, +'delivery-error': Channel_Text_Send_Error_Offline, +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], + +# no body +]</pre></dd> + + <dt>A maximally complex delivery report: the server reports a + bilingual human-readable failure message because the user sent + a message "Hello, world!" with token + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact + with handle 123, but that handle represents a contact who does not + actually exist</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-error': Channel_Text_Send_Error_Invalid_Contact, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], +}, +{ # message from server (alternative in English) +'alternative': '404', +'content-type': 'text/plain', +'lang': 'en', +'content': 'I have no contact with that name', +}, +{ # message from server (alternative in German) +'alternative': '404'. +'content-type': 'text/plain', +'lang': 'de', +'content', 'Ich habe keinen Kontakt mit diesem Namen', +} +]</pre></dd> + + <dt>A minimal delivery report indicating successful delivery + of the sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Delivered, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +]</pre></dd> + + </dl> + + </div> + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring> + A key, which SHOULD be one of the well-known keys specified by + <tp:type>Message_Header_Key</tp:type>, + <tp:type>Message_Body_Key</tp:type> or + <tp:type>Delivery_Report_Header_Key</tp:type> if possible. + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring> + The value corresponding to the given key, which SHOULD be one of the + specified types for well-known keys. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:simple-type type="s" name="Message_Header_Key"> + <tp:added version="0.19.8"/> + <tp:changed version="0.21.5"> + Removed <tt>protocol-token</tt>—which had never been implemented—and + respecified <tt>message-token</tt> not to have unimplementable + uniqueness guarantees. + </tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a + message, which contains metadata about the message as a whole, along + with the corresponding value types. Some keys make sense for both + incoming and outgoing messages, while others are only meaningful for + one or the other.</p> + + <dl> + <dt>message-token (s - + <tp:type>Protocol_Message_Token</tp:type>) + </dt> + <dd> + <p>An opaque identifier for the message, as used by the + underlying protocol. For outgoing messages, this SHOULD be + globally unique; for incoming messages, this is <em>not</em> + guaranteed to uniquely identify a message, <em>even within the + scope of a single channel or contact</em>; the only guarantee + made is that two messages with different <tt>message-token</tt> + headers are different messages.</p> + + <p>Clients wishing to determine whether a new message with the + <tt>scrollback</tt> header matches a previously-logged message + with the same <tt>message-token</tt> SHOULD compare the + message's sender, contents, <tt>message-sent</tt> or + <tt>message-received</tt> timestamp, etc. Note that, in XMPP, + the server only supplies a timestamp for scrollback messages, + not for messages received while you are in a room; thus, + non-scrollback messages will lack a <tt>message-sent</tt> + timestamp.</p> + + <tp:rationale> + <p>In practice, most protocols do not provide globally-unique + identifiers for messages. Connection managers, being + stateless, do not have the necessary information — namely, IM + logs — to generate reliable unique tokens for messages.</p> + + <p>For instance, some XMPP clients (including Gabble) stamp + messages they send with unique identifiers, but others number + outgoing messages in a conversation from 1 upwards.</p> + </tp:rationale> + </dd> + + <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> + <dd>The time the message was sent (if unavailable, the time + it arrived at a central server MAY be used). Omitted if no + reasonable approximation is available; SHOULD always be present + on outgoing messages.</dd> + + <dt>message-received (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> + <dd>The time the message was received locally. SHOULD always + be present.</dd> + + <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>)</dt> + <dd>The contact who sent the message. If 0 or omitted, the contact + who sent the message could not be determined.</dd> + + <dt>message-sender-id (s)</dt> + <dd>The identifier of the contact who sent the message, + i.e. the result of calling <tp:dbus-ref + namespace="ofdT.Connection">InspectHandles</tp:dbus-ref> + on <code>message-sender</code>. If omitted, clients MUST + fall back to looking at <code>message-sender</code>.</dd> + + <dt>sender-nickname (s)</dt> + <dd>The nickname chosen by the sender of the message, which can be + different for each message in a conversation.</dd> + + <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>) + </dt> + <dd>The type of message; if omitted, + Channel_Text_Message_Type_Normal MUST be assumed. MAY + be omitted for normal chat messages.</dd> + + <dt>supersedes (s – <tp:type>Protocol_Message_Token</tp:type>)</dt> + <dd>If present, this message supersedes a previous message, + identified by its <tt>protocol-token</tt> or + <tt>message-token</tt> header. The user interface MAY, for + example, choose to replace the superseded message with this + message, or grey out the superseded message. + + <tp:rationale>Skype, for example, allows the user to amend + messages they have already sent (to correct typos, + etc.).</tp:rationale> + </dd> + + <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt> + <dd>The incoming message ID. This MUST NOT be present on outgoing + messages. Clients SHOULD NOT store this key - it is only valid + for as long as the message remains unacknowledged.</dd> + + <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt> + <dd>This message is specific to the given interface, which is + neither Text nor Messages. It SHOULD be ignored if that + interface is not supported. (Note that an 'interface' key + can also appear on the second and subsequent parts, where + it indicates that that part (only) should be ignored if + unsupported.)</dd> + + <dt>scrollback (b)</dt> + <dd>If present and true, the incoming message was part of a + replay of message history (this matches the Scrollback flag in + <tp:type>Channel_Text_Message_Flags</tp:type>). This flag + does not make sense on outgoing messages and SHOULD NOT + appear there.</dd> + + <dt>rescued (b)</dt> + <dd>If present and true, the incoming message has been seen in + a previous channel during the lifetime of the Connection, + but had not been acknowledged when that channel closed, causing + an identical channel (in which the message now appears) to open. + This matches the Rescued flag in + <tp:type>Channel_Text_Message_Flags</tp:type>; it + does not make sense on outgoing messages, and SHOULD NOT + appear there.</dd> + </dl> + + </tp:docstring> + </tp:simple-type> + + <tp:simple-type type="s" name="Message_Body_Key"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the second and subsequent + <tp:type>Message_Part</tp:type>s of a message, which contain the + message content, along with the corresponding value types.</p> + + <dl> + <dt>identifier (s — + <tp:type>Protocol_Content_Identifier</tp:type>)</dt> + <dd>An opaque identifier for this part. + Parts of a message MAY reference other parts by treating + this identifier as if it were a MIME Content-ID and using + the cid: URI scheme.</dd> + + <dt>alternative (s)</dt> + <dd> + <p>If present, this part of the message is an alternative for + all other parts with the same value for "alternative". + Clients SHOULD only display one of them (this is expected to + be used for XHTML messages in a future version of this + specification).</p> + + <p>If omitted, this part is not an alternative for any other + part.</p> + + <p>Parts of a message MAY reference the group of alternatives + as a whole (i.e. a reference to whichever of them is chosen) + by treating this identifier as if it were the MIME Content-ID + of a multipart/alternative part, and using the cid: URI + scheme.</p> + </dd> + + <dt>content-type (s)</dt> + <dd> + <p>The MIME type of this part. See the documentation + for <tp:member-ref>MessageReceived</tp:member-ref> and + <tp:member-ref>MessageSent</tp:member-ref> for notes on the + special status of "text/plain" parts.</p> + + <p>Connection managers MUST NOT signal parts without a + 'content-type' key; if a protocol provides no way to determine + the MIME type, the connection manager is responsible for + guessing it, but MAY fall back to "text/plain" for text and + "application/octet-stream" for non-text.</p> + + <p>Clients MUST ignore parts without a 'content-type' key, which + are reserved for future expansion.</p> + + <p>When sending messages, clients SHOULD normalize the + content-type to lower case, but connection managers SHOULD NOT + rely on this. When signalling sent or received messages, + connection managers MUST normalize the content-type to lower + case.</p> + </dd> + + <dt>lang (s)</dt> + <dd>The natural language of this part, identified by a + RFC 3066 language tag. + + <tp:rationale> + XMPP allows alternative-selection by language as well as + by content-type. + </tp:rationale> + </dd> + + <dt>size (u)</dt> + <dd>The size in bytes (if needs-retrieval is true, this MAY be an + estimated or approximate size). SHOULD be omitted if 'content' + is provided. + + <tp:rationale> + There's no point in providing the size if you're already + providing all the content. + </tp:rationale> + </dd> + + <dt>thumbnail (b)</dt> + <dd> + <p>This part is a thumbnail. To represent an image together with + its thumbnail in a single message, there should be one part for + the full image followed by a part for the thumbnail (following + the “more complete versions first” requirement), with the same + 'alternative' value. For example:</p> + + <pre> +[ ... , + { 'alternative': 'catphoto', + 'content-type': 'image/jpeg', + 'size': 150000, + 'content': [0xFF, 0xD8, ... 0xFF 0xD9], + }, + { 'alternative': 'catphoto', + 'content-type': 'image/jpeg' + 'size': 1024, + 'thumbnail': True, + 'content': [0xFF, 0xD8, ... 0xFF 0xD9], + }, + ... +]</pre> + </dd> + + <dt>needs-retrieval (b)</dt> + <dd>If false or omitted, the connection + manager already holds this part in memory. If present and true, + this part must be retrieved on demand (like MIME's + <tt>message/external-body</tt>) by a mechanism to be defined later. + + <tp:rationale>The mechanism was meant to be + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, but + that didn't work out. It's worth leaving the header in in + preparation for a future mechanism. + </tp:rationale> + </dd> + + <dt>truncated (b)</dt> + <dd>The content available via the 'content' key has been truncated + by the server or connection manager (equivalent to + Channel_Text_Message_Flag_Truncated in the Text interface). + </dd> + + <dt>content (s or ay)</dt> + <dd>The part's content, if it is available and + sufficiently small to include here (implies that + 'needs-retrieval' is false or omitted). Otherwise, omitted. + If the part is human-readable text or HTML, the value for this + key MUST be a UTF-8 string (D-Bus signature 's'). + If the part is not text, the value MUST be a byte-array + (D-Bus signature 'ay'). If the part is a text-based format + that is not the main body of the message (e.g. an iCalendar + or an attached XML document), the value SHOULD be a UTF-8 string, + transcoding from another charset to UTF-8 if necessary, but + MAY be a byte-array (of unspecified character set) if + transcoding fails or the source charset is not known.</dd> + + <!-- FIXME: "sufficiently small to include" is not currently + defined; we should add some API so clients can tell the + CM how large a message it should emit in the signal.--> + + <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt> + <dd>This part is specific to the given interface, which is + neither Text nor Messages. It SHOULD be ignored if that + interface is not supported. (Note that an 'interface' key + can also appear on the first part, where it indicates that the + entire message should be ignored if unsupported.)</dd> + </dl> + </tp:docstring> + </tp:simple-type> + + <tp:simple-type type="s" name="Delivery_Report_Header_Key"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a + delivery report, along with the corresponding value types. Some of + these are special-cases of headers defined by + <tp:type>Message_Header_Key</tp:type>.</p> + + <dl> + <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>, as + defined by <tp:type>Message_Header_Key</tp:type>)</dt> + <dd>MUST be the intended recipient of the original message, if + available (zero or omitted if the intended recipient is + unavailable or is not a contact, e.g. a chatroom), even if the + delivery report actually came from an intermediate server.</dd> + + <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>, + as defined by <tp:type>Message_Header_Key</tp:type>)</dt> + <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd> + + <dt>delivery-status (u - <tp:type>Delivery_Status</tp:type>)</dt> + <dd>The status of the message. All delivery reports MUST contain + this key in the first Message_Part.</dd> + + <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt> + + <dd> + <p>An identifier for the message to which this delivery report + refers. MUST NOT be an empty string. Omitted if not + available.</p> + + <p>Clients may match this against the token produced by the + SendMessage method and MessageSent signal. A status report + with no token could match any sent message, and a sent + message with an empty token could match any status report. + If multiple sent messages match, clients SHOULD use some + reasonable heuristic.</p> + + <tp:rationale> + In an ideal world, we could unambiguously match reports + against messages; however, deployed protocols are not ideal, + and not all reports and messages can be matched. + </tp:rationale> + </dd> + + <dt>delivery-error (u - + <tp:type>Channel_Text_Send_Error</tp:type>)</dt> + <dd> + The reason for the failure. MUST be omitted if this was a + successful delivery; SHOULD be omitted if it would be + Channel_Text_Send_Error_Unknown. + </dd> + + <dt>delivery-dbus-error (s - + <tp:type>DBus_Error_Name</tp:type>)</dt> + <dd> + The reason for the failure, specified as a (possibly + implementation-specific) D-Bus error. MUST be omitted if this was + a successful delivery. If set, the 'delivery-error' key SHOULD be + set to the closest available value. + </dd> + + <dt>delivery-error-message (s)</dt> + <dd> + Debugging information on why the message could not be delivered. + MUST be omitted if this was a successful delivery; MAY always be + omitted. + </dd> + + <dt>delivery-echo (aa{sv} - <tp:type>Message_Part[]</tp:type>)</dt> + <dd> + <p>The message content, as defined by the Messages interface. + Omitted if no content is available. Content MAY have been + truncated, message parts MAY have been removed, and message + parts MAY have had their content removed (i.e. the message part + metadata is present, but the 'content' key is not).</p> + + <tp:rationale> + Some protocols, like XMPP, echo the failing message back to + the sender. This is sometimes the only way to match it + against the sent message, so we include it here. + </tp:rationale> + </dd> + + </dl> + </tp:docstring> + </tp:simple-type> + + <tp:simple-type type="u" name="Message_Part_Index" + array-name="Message_Part_Index_List"> + <tp:deprecated version="0.21.5"> + This type is only used by + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is + unimplemented and deprecated. + </tp:deprecated> + <tp:added version="0.17.17"/> + <tp:docstring> + The index of a message part within a message. + </tp:docstring> + </tp:simple-type> + + <tp:mapping name="Message_Part_Content_Map"> + <tp:added version="0.17.17"/> + <tp:deprecated version="0.21.5"> + This structure is only used by + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is + unimplemented and deprecated. + </tp:deprecated> + <tp:docstring> + A mapping from message part indexes to their content, as returned by + <tp:member-ref>GetPendingMessageContent</tp:member-ref>. + </tp:docstring> + + <tp:member type="u" tp:type="Message_Part_Index" name="Part"> + <tp:docstring> + Indexes into the array of <tp:type>Message_Part</tp:type>s that + represents a message. The "headers" part (which is not a valid + argument to GetPendingMessageContent) is considered to be part 0, + so the valid part numbers start at 1 (for the second message part). + </tp:docstring> + </tp:member> + + <tp:member type="v" name="Content"> + <tp:docstring> + The message part's content. The variant MUST contain either type + 's' or 'ay' (UTF-8 text string, or byte array), following the + same rules as for the value of the 'content' key in + the <tp:type>Message_Part</tp:type> mappings. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:simple-type type="s" name="Protocol_Message_Token" + array-name="Protocol_Message_Token_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An opaque token used to identify messages in the underlying. + protocol. As a special case, the empty string indicates that there + is no particular identification for a message.</p> + + <p>CM implementations SHOULD use an identifier expected to be unique, + such as a UUID, for outgoing messages (if possible).</p> + + <p>Some protocols can only track a limited number of messages + in a small message-ID space (SMS messages are identified by a single + byte), and some implementations send non-unique identifiers (some + XMPP clients use very simple message IDs, such as an incrementing + integer that resets to 1 at the beginning of each connection). As a + result, clients MUST NOT assume that protocol tokens will not be + re-used.</p> + + <p>In particular, clients SHOULD use a heuristic to assign delivery + reports to messages, such as matching on message content or + timestamp (if available), or assuming that the delivery report + refers to the most recent message with that ID.</p> + </tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Protocol_Content_Identifier" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A protocol-specific identifier for a blob of content, as used for + the <tt>identifier</tt> key in a <tp:type>Message_Part</tp:type>. The + same identifier MAY be re-used if the same content, byte-for-byte, + appears as a part of several messages.</p> + + <tp:rationale> + <p>On XMPP, these identifiers might be Content-IDs for custom + smileys implemented using <a + href="http://xmpp.org/extensions/xep-0231.html">XEP-0232 Bits of + Binary</a>; the same smiley might well appear in multiple + messages.</p> + </tp:rationale> + </tp:docstring> + </tp:simple-type> + + <method name="SendMessage" tp:name-for-bindings="Send_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Submit a message to the server for sending. + If this method returns successfully, the message has been submitted + to the server and the <tp:member-ref>MessageSent</tp:member-ref> + signal is emitted. A corresponding + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref> + signal on the Text interface MUST also be emitted.</p> + + <p>This method MUST return before the MessageSent signal is + emitted.</p> + + <tp:rationale> + <p>This means that the process sending the message is the first + to see the <tp:type>Protocol_Message_Token</tp:type>, and can + relate the message to the corresponding + <tp:member-ref>MessageSent</tp:member-ref> signal by comparing + message tokens (if supported by the protocol).</p> + </tp:rationale> + + <p>If this method fails, message submission to the server has failed + and no signal on this interface (or the Text interface) is + emitted.</p> + + <p>If this method succeeds, message submission to the server has + succeeded, but the message has not necessarily reached its intended + recipient. If a delivery failure is detected later, this is + signalled by receiving a message whose <code>message-type</code> + header maps to + <tp:type>Channel_Text_Message_Type</tp:type>_Delivery_Report. + Similarly, if delivery is detected to have been successful + (which is not possible in all protocols), a successful delivery + report will be signalled.</p> + </tp:docstring> + + <arg direction="in" type="aa{sv}" tp:type="Message_Part[]" + name="Message"> + <tp:docstring> + The message content, including any attachments or alternatives. + This MUST NOT include the following headers, or any others that + do not make sense for a client to specify: + <code>message-sender</code>, <code>message-sender-id</code>, + <code>message-sent</code>, <code>message-received</code>, + <code>pending-message-id</code>. + </tp:docstring> + </arg> + <arg direction="in" name="Flags" type="u" + tp:type="Message_Sending_Flags"> + <tp:docstring> + Flags affecting how the message is sent. The channel MAY ignore some + or all flags, depending on + <tp:member-ref>DeliveryReportingSupport</tp:member-ref>; the flags + that were handled by the CM are provided in + <tp:member-ref>MessageSent</tp:member-ref>. + </tp:docstring> + </arg> + + <arg direction="out" type="s" tp:type="Protocol_Message_Token" + name="Token"> + <tp:docstring> + An opaque token used to match any incoming delivery or failure + reports against this message, or an empty string if the message + is not readily identifiable. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The requested message is malformed and cannot be sent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag" + type="u"> + <tp:docstring> + Flags altering the way a message is sent. The "most usual" action + should always be to have these flags unset. Some indication of which + flags are supported is provided by the + <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. + </tp:docstring> + + <tp:flag suffix="Report_Delivery" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a successful delivery report if possible, even if this is + not the default for this protocol. Ignored if delivery reports are + not possible on this protocol.</p> + + <tp:rationale> + <p>In some protocols, like XMPP, it is not conventional to request + or send positive delivery notifications.</p> + </tp:rationale> + + <p>Delivery failure reports SHOULD always be sent, but if this flag + is present, the connection manager MAY also try harder to obtain + failed delivery reports or allow them to be matched to outgoing + messages.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Report_Read" value="2"> + <tp:added version="0.19.9"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a delivery report when the message is read by the + recipient, even if this is not the default for this protocol. + Ignored if read reports are not possible on this protocol.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Report_Deleted" value="4"> + <tp:added version="0.19.9"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a delivery report when the message is deleted by the + recipient, even if this is not the default for this protocol. + Ignored if such reports are not possible on this protocol.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + + <signal name="MessageSent" tp:name-for-bindings="Message_Sent"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that a message has been submitted for sending. This + MUST be emitted exactly once per emission of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref> + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter if this interface is present, as mentioned + in the introduction.</p> + + <p>This SHOULD be emitted as soon as the CM determines it's + theoretically possible to send the message (e.g. the parameters are + supported and correct).</p> + + <tp:rationale> + <p>This signal allows a process that is not the caller of + SendMessage to log sent messages.</p> + </tp:rationale> + </tp:docstring> + + <arg type="aa{sv}" tp:type="Message_Part[]" name="Content"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The message content (see <tp:type>Message_Part</tp:type> for full + details). If the message that was passed to + <tp:member-ref>SendMessage</tp:member-ref> has a formatted text + part that the connection manager recognises, but no + <tt>text/plain</tt> alternative, the CM MUST use the formatted text + part to generate a <tt>text/plain</tt> alternative which is also + included in this signal argument.</p> + + <p>The connection manager SHOULD include the + <code>message-sender</code>, <code>message-sender-id</code> and + <code>message-sent</code> headers in the representation of the + message that is signalled here. If the channel has + channel-specific handles, the <code>message-sender</code> and + <code>message-sender-id</code> SHOULD reflect the sender that + other contacts will see.</p> + + <p>If the connection manager can predict that the message will be + altered during transmission, this argument SHOULD reflect what + other contacts will receive, rather than being a copy of the + argument to SendMessage (if the message is truncated, + formatting or alternatives are dropped, etc., then the edited + version SHOULD appear in this signal).</p> + </tp:docstring> + </arg> + + <arg name="Flags" type="u" tp:type="Message_Sending_Flags"> + <tp:docstring> + <p>Flags affecting how the message was sent. The flags might be a + subset of those passed to SendMessage if the caller requested + unsupported flags.</p> + </tp:docstring> + </arg> + + <arg name="Message_Token" type="s" tp:type="Protocol_Message_Token"> + <tp:docstring> + An opaque token used to match any incoming delivery or failure + reports against this message, or an empty string if the message + is not readily identifiable. + </tp:docstring> + </arg> + </signal> + + <property name="PendingMessages" type="aaa{sv}" access="read" + tp:type="Message_Part[][]" tp:name-for-bindings="Pending_Messages"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of incoming messages that have neither been acknowledged nor + rejected. This list is a more detailed version of the one returned + by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>, + and contains the same messages, uniquely identified by the same + pending message IDs. Its items can be removed using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.</p> + + <p>Change notification is via + <tp:member-ref>MessageReceived</tp:member-ref> and + <tp:member-ref>PendingMessagesRemoved</tp:member-ref>.</p> + </tp:docstring> + </property> + + <signal name="PendingMessagesRemoved" + tp:name-for-bindings="Pending_Messages_Removed"> + <tp:docstring> + The messages with the given IDs have been removed from the + <tp:member-ref>PendingMessages</tp:member-ref> list. Clients SHOULD NOT + attempt to acknowledge those messages. + + <tp:rationale> + This completes change notification for the PendingMessages property + (previously, there was change notification when pending messages + were added, but not when they were removed). + </tp:rationale> + </tp:docstring> + + <arg name="Message_IDs" type="au" tp:type="Message_ID[]"> + <tp:docstring> + The messages that have been removed from the pending message list. + </tp:docstring> + </arg> + </signal> + + <method name="GetPendingMessageContent" + tp:name-for-bindings="Get_Pending_Message_Content"> + <tp:deprecated version='0.21.5' + xmlns="http://www.w3.org/1999/xhtml"> + This method has never been implemented, and in any case would have been + impossible to use correctly when multiple clients (such as a logger and + the handler) are interested in a text channel. See <a + href='https://bugs.freedesktop.org/show_bug.cgi?id=26417'>freedesktop.org + bug #26417</a> for more details. + </tp:deprecated> + <tp:docstring> + Retrieve the content of one or more parts of a pending message. + Note that this function may take a considerable amount of time + to return if the part's 'needs-retrieval' flag is true; consider + extending the default D-Bus method call timeout. Additional API is + likely to be added in future, to stream large message parts. + </tp:docstring> + + <arg name="Message_ID" type="u" tp:type="Message_ID" direction="in"> + <tp:docstring> + The ID of a pending message + </tp:docstring> + </arg> + + <arg name="Parts" type="au" direction="in" + tp:type="Message_Part_Index[]"> + <tp:docstring> + The desired entries in the array of message parts, identified by + their position. The "headers" part (which is not a valid argument + to this method) is considered to be part 0, so the valid part + numbers start at 1 (for the second Message_Part). + </tp:docstring> + </arg> + + <arg name="Content" type="a{uv}" direction="out" + tp:type="Message_Part_Content_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The content of the requested parts. The keys in this mapping + are positions in the array of message parts; the values are + either of type 's' or 'ay' (UTF-8 text string, or byte array), + following the same rules as for the value of the 'content' key in + the <tp:type>Message_Part</tp:type> mappings.</p> + + <p>If the one of the requested part numbers was greater than zero + but referred to a part that had no content (i.e. it had no + 'content-type' key or no 'content' key), it is simply omitted from + this mapping; this is not considered to be an error condition.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Either there is no pending message with the given message ID, + or one of the part numbers given was 0 or too large. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <signal name="MessageReceived" tp:name-for-bindings="Message_Received"> + <tp:docstring> + Signals that a message has been received and added to the pending + messages queue. This MUST be emitted exactly once per emission of the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter in favour of this signal if this interface is + present, as mentioned in the introduction. + </tp:docstring> + + <arg type="aa{sv}" tp:type="Message_Part[]" name="Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The message content, including any attachments or alternatives. If + the incoming message contains formatted text without a plain text + alternative, the connection manager MUST generate a + <tt>text/plain</tt> alternative from the formatted text, and + include it in this message (both here, and in the + <tp:member-ref>PendingMessages</tp:member-ref> property).</p> + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" + plural="Delivery_Statuses" type="u"> + <tp:docstring> + <p>The status of a message as indicated by a delivery report.</p> + + <p>If this enum is extended in future specifications, this should + only be to add new, non-overlapping conditions (i.e. all failures + should still be signalled as either Temporarily_Failed + or Permanently_Failed). If additional detail is required (e.g. + distinguishing between the various types of permanent failure) this + will be done using additional + <tp:type>Delivery_Report_Header_Key</tp:type>s.</p> + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The message's disposition is unknown. + Clients SHOULD consider all messages to have status + Delivery_Status_Unknown unless otherwise specified; connection + managers SHOULD NOT signal this delivery status explicitly. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Delivered" value="1"> + <tp:docstring> + The message has been delivered to the intended recipient. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Temporarily_Failed" value="2"> + <tp:docstring> + Delivery of the message has failed. Clients SHOULD notify the user, + but MAY automatically try sending another copy of the message. + + <tp:rationale> + Similar to errors with type="wait" in XMPP; analogous to + 4xx errors in SMTP. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Permanently_Failed" value="3"> + <tp:docstring> + Delivery of the message has failed. Clients SHOULD NOT try again + unless by specific user action. If the user does not modify the + message or alter configuration before re-sending, this error is + likely to happen again. + + <tp:rationale> + Similar to errors with type="cancel", type="modify" + or type="auth" in XMPP; analogous to 5xx errors in SMTP. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Accepted" value="4"> + <tp:docstring> + An intermediate server has accepted the message but the message + has not been yet delivered to the ultimate recipient. The + connection manager might send a Failed report or Delivered report + later. + + <tp:rationale> + Similar to "202 Accepted" success code in SIP; analogous to + 251 and 252 responses in SMTP. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Read" value="5"> + <tp:added version="0.19.9"/> + <tp:docstring> + The message has been read by the intended recipient. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Deleted" value="6"> + <tp:added version="0.19.9"/> + <tp:docstring> + The message has been deleted by the intended recipient. This MAY be + signalled on its own if the message is deleted without being read, or + after <code>Read</code> if the message was read before being deleted. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Delivery_Reporting_Support_Flags" + value-prefix="Delivery_Reporting_Support_Flag" type="u"> + <tp:docstring> + Flags indicating the level of support for delivery reporting on this + channel, as found on the + <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. Any + future flags added to this set will conform to the + convention that the presence of an extra flag implies that + more operations will succeed. Note that CMs may always provide more + reports than are requested in the + <tp:type>Message_Sending_Flags</tp:type> passed to + <tp:member-ref>SendMessage</tp:member-ref>. + + <tp:rationale> + If senders want delivery reports, they should ask for them. If they + don't want delivery reports, they can just ignore them, so there's no + need to have capability discovery for what will happen if a delivery + report isn't requested. + </tp:rationale> + </tp:docstring> + + <tp:flag suffix="Receive_Failures" value="1"> + <tp:docstring> + Clients MAY expect to receive negative delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Receive_Successes" value="2"> + <tp:docstring> + Clients MAY expect to receive positive delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Receive_Read" value="4"> + <tp:added version="0.19.9"/> + <tp:docstring> + Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> + <code>Read</code> reports if Message_Sending_Flag_Report_Read + is specified when sending. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Receive_Deleted" value="8"> + <tp:added version="0.19.9"/> + <tp:docstring> + Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> + <code>Deleted</code> reports if Message_Sending_Flag_Report_Deleted + is specified when sending. + </tp:docstring> + </tp:flag> + </tp:flags> + + <property name="DeliveryReportingSupport" access="read" + tp:type="Delivery_Reporting_Support_Flags" type="u" + tp:name-for-bindings="Delivery_Reporting_Support" + tp:immutable="yes"> + <tp:docstring> + A bitfield indicating features supported by this channel. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml new file mode 100644 index 0000000..4e201dd --- /dev/null +++ b/spec/Channel_Interface_Password.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> +Copyright © 2005-2009 Collabora Limited +Copyright © 2005-2009 Nokia Corporation +Copyright © 2006 INdT + </tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Password"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:flags name="Channel_Password_Flags" value-prefix="Channel_Password_Flag" type="u"> + <tp:flag suffix="Provide" value="8"> + <tp:docstring> + The <tp:member-ref>ProvidePassword</tp:member-ref> method must be + called now for the user to join the channel + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="GetPasswordFlags" tp:name-for-bindings="Get_Password_Flags"> + <arg direction="out" type="u" tp:type="Channel_Password_Flags" + name="Password_Flags"> + <tp:docstring> + An integer with the logical OR of all the flags set + (values of ChannelPasswordFlags) + </tp:docstring> + </arg> + <tp:docstring> + Returns the bitwise-OR of the flags relevant to the password on this + channel. The user interface can use this to present information about + which operations are currently valid. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + <signal name="PasswordFlagsChanged" + tp:name-for-bindings="Password_Flags_Changed"> + <arg name="Added" type="u" tp:type="Channel_Password_Flags"> + <tp:docstring> + A bitwise OR of the flags which have been set + </tp:docstring> + </arg> + <arg name="Removed" type="u" tp:type="Channel_Password_Flags"> + <tp:docstring> + A bitwise OR of the flags which have been cleared + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the flags as returned by + <tp:member-ref>GetPasswordFlags</tp:member-ref> are changed. + The user interface should be updated as appropriate. + </tp:docstring> + </signal> + <method name="ProvidePassword" tp:name-for-bindings="Provide_Password"> + <arg direction="in" name="Password" type="s"> + <tp:docstring> + The password + </tp:docstring> + </arg> + <arg direction="out" type="b" name="Correct"> + <tp:docstring> + A boolean indicating whether or not the password was correct + </tp:docstring> + </arg> + <tp:docstring> + Provide the password so that the channel can be joined. Must be + called with the correct password in order for channel joining to + proceed if the 'provide' password flag is set. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels that may have a password set that users need + to provide before being able to join, or may be able to view or change + once they have joined the channel.</p> + + <p>The <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the + associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref> + signal indicate whether the channel has a password, whether the user + must now provide it to join, and whether it can be viewed or changed + by the user.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml new file mode 100644 index 0000000..ffdf4a9 --- /dev/null +++ b/spec/Channel_Interface_Room.xml @@ -0,0 +1,373 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Room" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.19.11">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Different IM protocols use a variety of ways to name chat rooms. The + simplest example is perhaps IRC, where chat rooms have short, + persistent, human-readable string names, and are generally global + across the network. Skype chat rooms have persistent string names, so + you can leave and re-join a room, but these names are opaque unique + identifiers. MSN chat rooms are unnamed, and you can only join one by + being invited. And XMPP wins the coveted “most complicated chat rooms” + prize: chat rooms may be hosted by different servers with different DNS + names; normally they have human-readable names, except that all MUCs on + Google Talk's conference server have UUIDs as names, and <a + href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym + title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4 + <q>Requesting a Unique Room Name</q></a> defines a protocol for + requesting a unique, opaque room name on the server.</p> + + <p>This interface intends to support and differentiate these mechanisms + more clearly than the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + properties can alone. It initially contains a pair of properties used + to represent the human-readable parts of a + <tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples + for different protocols are represented as follows:</p> + + <ul> + <li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a + channel with properties + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"#telepathy"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has a human-readable identifier, and is not confined to + a particular server on the network. + + <tp:rationale> + Actually, IRC supports creating “local” channels specific to the + server they are created on. These channels have identifiers + starting with <tt>&</tt> rather than <tt>#</tt>. These could be + represented by setting <tp:member-ref>Server</tp:member-ref> + appropriately. + </tp:rationale> + </li> + + <li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"0xdeadbeef"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has an identifier but no human-readable name. + </li> + + <li>An MSN group chat has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>None</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has neither an identifier (so it cannot be re-joined + later) nor a human-readable name. + </li> + + <li>A standard Jabber multi-user chat + <tt>jdev@conference.jabber.org</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"jdev@conference.jabber.org"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>, + <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>. + </li> + + <li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = + <code>"groupchat.google.com"</code>, indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. + </li> + + <li>Similarly, a XEP-0045 §10.1.4 uniquely-named room + <tt>lrcgsnthzvwm@conference.jabber.org</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"lrcgsnthzvwm@conference.jabber.org"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = + <code>"conference.jabber.org"</code>, indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. + </li> + </ul> + + <h4>Requestable channel classes</h4> + + <p>If the connection supports joining text chat rooms by unique + identifier, like Skype, it should advertise a + <tp:type>Requestable_Channel_Class</tp:type> matching:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: Room, + }, + Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>, + ] +)</pre></blockquote> + + <p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>.</p> + + <p>If, like IRC, the room identifiers are also human-readable, the + RCCs should also include RoomID in <var>Allowed_Properties</var>:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: Room, + }, + Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>, + ...<tp:member-ref>RoomID</tp:member-ref> + ] +), + +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref> + }, + Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>, + ] +)</pre></blockquote> + + <p>Requests may specify the RoomID in place of + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + . Note how <tp:member-ref>RoomID</tp:member-ref> appears + in <var>Allowed_Properties</var> of a different RCC because + when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> is omitted (or is None), both + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref> must also be omitted. + <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction + with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + in some situations, as explained below in the <em>Requesting room + channels</em> section. + </p> + + <p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref> + should also be included in the allowed properties, but + CMs MUST use a reasonable default + <tp:member-ref>Server</tp:member-ref> if not explicitly + specified in a channel request. The CM's default server MAY + be configurable by a connection parameter specified on a + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> call, similarly to how the + fallback conference server is specified on jabber connections in + gabble.</p> + + <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref> + should be fixed to the empty string, and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + should be None:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: None, + ...<tp:member-ref>RoomID</tp:member-ref>: "", + }, + Allowed = [ ] +)</pre></blockquote> + + <h4>Requesting room channels</h4> + + <p>When explicitly joining a room, the CM cannot know whether the room + ID is unique or not. As a result, if this is the case, adding an + empty string <tp:member-ref>RoomID</tp:member-ref> into the channel + request will ensure the CM knows. For example:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org", + ...<tp:member-ref>RoomID</tp:member-ref>: "" +}</pre></blockquote> + + <p>If <tp:member-ref>RoomID</tp:member-ref> features in + <var>Allowed_Properties</var> then the only value allowed in conjunction + with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + is the empty string. Requests with conflicting + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + and <tp:member-ref>RoomID</tp:member-ref> properties + will fail with InvalidArgument.</p> + + <p>To create a XEP-0045 §10.1.4 uniquely-named room channel + on the conference.jabber.org server, then the following channel + request should be made:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" +}</pre> + </blockquote> + + <p>If everything is successful, then when the channel request is + satisfied, a new channel will appear with the following properties:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org", + ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" +}</pre> + </blockquote> + + <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) + and then created a room with such a name on the said server. The empty + <tp:member-ref>RoomID</tp:member-ref> property shows that the room name + is not human-readable.</p> + + </tp:docstring> + + <property name="RoomID" tp:name-for-bindings="Room_ID" type="s" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The human-readable identifier of a chat room. Note that if + non-empty, this property (and perhaps also + <tp:member-ref>Server</tp:member-ref>) should be sufficient in + a channel request to join the room. XMPP MUCs have a room name + concept which is more like a topic, except more + persistent. This D-Bus property is <strong>not</strong> this + XMPP room name, but the bit before the @ in the room jid.</p> + + <p>This property cannot change during the lifetime of the channel. It + should appear in the <var>Allowed_Properties</var> of a + <tp:type>Requestable_Channel_Class</tp:type> for the connection if + rooms on this connection have human-readable names, and can be joined + by name.</p> + </tp:docstring> + </property> + + <property name="Server" tp:name-for-bindings="Server" type="s" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For protocols with a concept of chatrooms on multiple servers with + different DNS names (like XMPP), the DNS name of the server hosting + this channel (for example, <tt>"conference.jabber.org"</tt> or + <tt>"groupchat.google.com"</tt>). For other protocols, the empty + string.</p> + + <p>This property cannot change during the lifetime of the channel. It + should appear in the <var>Allowed_Properties</var> of a + <tp:type>Requestable_Channel_Class</tp:type> for the connection if + and only if non-empty values are supported.</p> + </tp:docstring> + </property> + + <tp:struct name="Room_Subject"> + <tp:docstring> + A struct representing the subject of a room channel. + </tp:docstring> + <tp:member type="s" name="Subject"> + <tp:docstring> + A human-readable description of the current subject of + conversation in the channel, similar to /topic in IRC. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Actor"> + <tp:docstring> + A normalized contact ID representing who last modified the + subject, or the empty string if it is not known. + </tp:docstring> + </tp:member> + <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp"> + <tp:docstring> + A unix timestamp indicating when the subject was last modified. + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="Subject" tp:name-for-bindings="Subject" + type="(ssx)" tp:type="Room_Subject" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The subject on the room such as the topic in an IRC channel, + or the room name in XMPP MUCs. In protocols which do not support + subjects (like MSN), this property should be ("", "", 0).</p> + + <tp:rationale>This property replaces the subject, subject-contact, and + subject-timestamp Telepathy properties of Text channels, as Telepathy + properties are soon to be deprecated completely.</tp:rationale> + + <p>This property may change during the lifetime of the channel and + MUST not be included in a channel request.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_SASL_Authentication.xml b/spec/Channel_Interface_SASL_Authentication.xml new file mode 100644 index 0000000..38568b1 --- /dev/null +++ b/spec/Channel_Interface_SASL_Authentication.xml @@ -0,0 +1,704 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_SASL_Authentication" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel interface for SASL authentication, + as defined by + <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>. + When this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, it represents authentication with the server. In future, + it could also be used to authenticate with secondary services, + or even to authenticate end-to-end connections with contacts. As a result, + this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type" + >ServerAuthentication</tp:dbus-ref> to allow for a potential future + Channel.Type.PeerAuthentication interface.</p> + + <p>In any protocol that requires a password, the connection manager can + use this channel to let a user interface carry out a simple SASL-like + handshake with it, as a way to get the user's credentials + interactively. This can be used to connect to protocols that may + require a password, without requiring that the password is saved in + the <tp:dbus-ref + namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> + + <p>In some protocols, such as XMPP, authentication with the server + is also carried out using SASL. In these protocols, a channel with this + interface can provide a simple 1:1 mapping of the SASL negotiations + taking place in the protocol, allowing more advanced clients to + perform authentication via SASL mechanisms not known to the + connection manager.</p> + + <tp:rationale> + <p>By providing SASL directly when the protocol supports it, we can + use mechanisms like Kerberos or Google's <code>X-GOOGLE-TOKEN</code> + without specific support in the connection manager.</p> + </tp:rationale> + + <p>For channels managed by a + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>, + only the channel's <tp:dbus-ref + namespace="ofdT.Client">Handler</tp:dbus-ref> may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.</p> + + <tp:rationale> + <p>There can only be one Handler, which is a good fit for SASL's + 1-1 conversation between a client and a server.</p> + </tp:rationale> + </tp:docstring> + + <tp:simple-type name="SASL_Mechanism" type="s" + array-name="SASL_Mechanism_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A SASL mechanism, as defined by + <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a> + and registered in + <a href="http://www.iana.org/assignments/sasl-mechanisms">the + IANA registry of SASL mechanisms</a>, or an unregistered + SASL mechanism such as <code>X-GOOGLE-TOKEN</code> used in the + same contexts.</p> + + <p>As a special case, pseudo-mechanisms starting with + <code>X-TELEPATHY-</code> are defined by this specification. + Use of these pseudo-mechanisms indicates that the user's credentials + are to be passed to the connection manager, which will then use + them for authentication with the service, either by implementing + the client side of some SASL mechanisms itself or by using a + non-SASL protocol. The only such pseudo-mechanism currently + defined is <code>X-TELEPATHY-PASSWORD</code>.</p> + + <p>The <code>X-TELEPATHY-PASSWORD</code> mechanism is extremely + simple:</p> + + <ul> + <li>The client MUST call + <tp:member-ref>StartMechanismWithData</tp:member-ref>, with + Initial_Data set to the password encoded in UTF-8. + For simplicity, calling <tp:member-ref>StartMechanism</tp:member-ref> + followed by calling <tp:member-ref>Respond</tp:member-ref> is not + allowed in this mechanism.</li> + + <li>The connection manager uses the password, together with + authentication details from the Connection parameters, to + authenticate itself to the server.</li> + + <li>When the connection manager finishes its attempt to authenticate + to the server, the channel's state changes to + either SASL_Status_Server_Succeeded or + SASL_Status_Server_Failed as appropriate.</li> + </ul> + </tp:docstring> + </tp:simple-type> + + <property name="AvailableMechanisms" + tp:name-for-bindings="Available_Mechanisms" + type="as" tp:type="SASL_Mechanism[]" + access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The SASL mechanisms as offered by the server, plus any + pseudo-SASL mechanisms supported by the connection manager for + credentials transfer. For instance, in a protocol that + natively uses SASL (like XMPP), this might be + <code>[ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", + "SCRAM-SHA-1" ]</code>.</p> + + <p>To make it possible to implement a very simple password-querying + user interface without knowledge of any particular SASL mechanism, + implementations of this interface MUST implement the + pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>, unless none + of the available mechanisms use a password at all.</p> + </tp:docstring> + </property> + + <property name="HasInitialData" tp:name-for-bindings="Has_Initial_Data" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>StartMechanismWithData</tp:member-ref> + can be expected to work for SASL mechanisms not starting with + <code>X-TELEPATHY-</code> (this is the case in most, but not all, + protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref> + must be used instead.</p> + + <p>This property does not affect the <code>X-TELEPATHY-</code> + pseudo-mechanisms such as <code>X-TELEPATHY-PASSWORD</code>, + which can use + <tp:member-ref>StartMechanismWithData</tp:member-ref> regardless + of the value of this property.</p> + </tp:docstring> + </property> + + <property name="CanTryAgain" tp:name-for-bindings="Can_Try_Again" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>StartMechanism</tp:member-ref> and (if + supported) <tp:member-ref>StartMechanismWithData</tp:member-ref> + can be expected to work when in one of the Failed states. If + false, the only thing you can do after failure is to close the + channel.</p> + + <tp:rationale> + <p>Retrying isn't required to work, although some protocols and + implementations allow it.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property type="u" tp:type="SASL_Status" access="read" + name="SASLStatus" tp:name-for-bindings="SASL_Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The current status of this channel. + Change notification is via the + <tp:member-ref>SASLStatusChanged</tp:member-ref> signal. + </tp:docstring> + </property> + + <property type="s" tp:type="DBus_Error_Name" access="read" + name="SASLError" tp:name-for-bindings="SASL_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for the <tp:member-ref>SASLStatus</tp:member-ref>, or + an empty string if the state is neither + Server_Failed nor Client_Failed.</p> + + <p>In particular, an ordinary authentication failure (as would + be produced for an incorrect password) SHOULD be represented by + <tp:error-ref>AuthenticationFailed</tp:error-ref>, + cancellation by the user's request SHOULD be represented + by <tp:error-ref>Cancelled</tp:error-ref>, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + <tp:error-ref>ServiceConfused</tp:error-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, this error code SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="SASLErrorDetails" + tp:name-for-bindings="SASL_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>SASLError</tp:member-ref> is non-empty, + any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, these details SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="AuthorizationIdentity" + tp:name-for-bindings="Authorization_Identity" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The identity for which authorization is being attempted, + typically the 'account' from the <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref> + parameters, normalized and formatted according to the + conventions used for SASL in this protocol.</p> + + <tp:rationale> + <p>The normalization used for SASL might not be the same + normalization used elsewhere: for instance, in a protocol + with email-like identifiers such as XMPP or SIP, the user + "juliet@example.com" might have to authenticate to the + example.com server via SASL PLAIN as "juliet".</p> + </tp:rationale> + + <p>This is usually achieved by using the authorization identity for + authentication, but an advanced Handler could offer the option + to authenticate under a different identity.</p> + + <p>The terminology used here is that the authorization identity + is who you want to act as, and the authentication identity is + used to prove that you may do so. For instance, if Juliet is + authorized to access a role account, "sysadmin@example.com", + and act on its behalf, it might be possible to authenticate + as "juliet@example.com" with her own password, but request to + be authorized as "sysadmin@example.com" instead of her own + account. See + <a href="http://tools.ietf.org/html/rfc4422#section-3.4.1">RFC + 4422 §3.4.1</a> for more details.</p> + + <tp:rationale> + <p>In SASL the authorization identity is normally guessed from + the authentication identity, but the information available + to the connection manager is the identity for which + authorization is required, such as the desired JID in XMPP, + so that's what we signal to UIs; it's up to the UI to + choose whether to authenticate as the authorization identity + or some other identity.</p> + + <p>As a concrete example, the "sysadmin" XMPP account mentioned + above would have <code>{ 'account': 'sysadmin@example.com' }</code> + in its Parameters, and this property would also be + 'sysadmin@example.com'. A simple Handler would + merely prompt for sysadmin@example.com's password, + and use that JID as both the authorization and authentication + identity, which might result in SASL PLAIN authentication with the + initial response + '\000sysadmin@example.com\000root'.</p> + + <p>A more advanced Handler might also ask for an authentication + identity, defaulting to 'sysadmin@example.com'; if Juliet + provided authentication identity 'juliet@example.com' and + password 'romeo', the Handler might perform SASL PLAIN + authentication using the initial response + 'sysadmin@example.com\000juliet@example.com\000romeo'.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="DefaultUsername" + tp:name-for-bindings="Default_Username" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default username for use with SASL mechanisms that deal + with a "simple username" (as defined in <a + href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>). If + such a SASL mechanism is in use, clients SHOULD default to + using the DefaultUsername; also, if the client uses + the DefaultUsername, it SHOULD assume that the authorization + identity <tp:member-ref>AuthorizationIdentity</tp:member-ref> + will be derived from it by the server.</p> + + <tp:rationale> + <p>In XMPP, <a href="http://trac.tools.ietf.org/wg/xmpp/trac/ticket/49"> + servers typically expect</a> "user@example.com" to + authenticate with username "user"; this was a SHOULD in <a + href="http://tools.ietf.org/html/rfc3920">RFC 3920</a>.</p> + + <p><a + href="http://tools.ietf.org/html/draft-ietf-xmpp-3920bis-19">3920bis</a> + weakens that SHOULD to "in the absence of local information + provided by the server, an XMPP client SHOULD assume that + the authentication identity for such a SASL mechanism is the + combination of a user name and password, where the simple + user name is the localpart of the user's JID".</p> + </tp:rationale> + + <p>For example, in the simple case, if the user connects with + <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>user@example.com</tt>" }) and use PLAIN with + password "password", he or she should authenticate like so: + "<tt>\0user\0password</tt>" and the channel will look like + this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "user", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "user@example.com } +</pre></blockquote> + + <p>In the complex case, if the same user is using his or her + sysadmin powers to log in as the "announcements" role address, + he or she would connect with <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>announcements@example.com</tt>" }) and the SASL + channel would look like this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "announcements", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "announcements@example.com } +</pre></blockquote> + + <p>A sufficiently elaborate UI could give the opportunity + to override the username from "announcements" to "user". + The user's simple username is still "user", and the password is + still "password", but this time he or she is trying to authorize + to act as <tt>announcements@example.com</tt>, so the UI would + have to perform SASL PLAIN with this string: + "<tt>announcements@example.com\0user\0password</tt>", where + "announcements@example.com" is the + <tp:member-ref>AuthorizationIdentity</tp:member-ref>.</p> + </tp:docstring> + </property> + + <property name="DefaultRealm" tp:name-for-bindings="Default_Realm" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default realm (as defined in + <a href="http://tools.ietf.org/html/rfc2831#section-2.1.1">RFC + 2831</a>) to use for authentication, if the server does not + supply one.</p> + + <tp:rationale> + <p>The server is not required to provide a realm; if it doesn't, + the client is expected to ask the user or provide a sensible + default, typically the requested DNS name of the server. + In some implementations of <code>DIGEST-MD5</code>, the + server does not specify a realm, but expects that the client + will choose a particular default, and authentication will + fail if the client's default is different. Connection + managers for protocols where this occurs are more easily able + to work around these implementations than a generic client + would be.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="StartMechanism" tp:name-for-bindings="Start_Mechanism"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, without + sending initial data (an "initial response" as defined in RFC + 4422).</p> + + <tp:rationale> + <p>This method is appropriate for mechanisms where the client + cannot send anything until it receives a challenge from the + server, such as + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> + in "initial authentication" mode.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism. Choose a SASL mechanism from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StartMechanismWithData" + tp:name-for-bindings="Start_Mechanism_With_Data"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <arg direction="in" name="Initial_Data" type="ay"> + <tp:docstring> + Initial data (an "initial response" in RFC 4422's terminology) to send + with the mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, and send + <var>Initial_Data</var> as the "initial response" defined in + <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422 + §3.3</a>.</p> + + <tp:rationale> + <p>This method is appropriate for mechanisms where the client may + send data first, such as <code>PLAIN</code>, or must send data + first, such as + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> + in "subsequent authentication" mode.</p> + + <p>Having two methods allows any mechanism where it makes a difference + to distinguish between the absence of an initial response + (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte + initial response (StartMechanismWithData, with Initial_Data + empty).</p> + </tp:rationale> + + <p>If the <tp:member-ref>HasInitialData</tp:member-ref> + property is false, this indicates that the underlying protocol + does not make it possible to send initial data. In such protocols, + this method may only be used for the <code>X-TELEPATHY-</code> + pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>), + and will fail if used with an ordinary SASL mechanism.</p> + + <tp:rationale> + <p>For instance, the IRC SASL extension implemented in Charybdis and + Atheme does not support initial data - the first message in the + exchange only carries the mechanism. This is significant if using + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>, + which cannot be used in the faster "subsequent authentication" + mode on a protocol not supporting initial data.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism (choose one from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable), or doesn't allow + initial data to be sent (as indicated by + <tp:member-ref>HasInitialData</tp:member-ref>; call + <tp:member-ref>StartMechanism</tp:member-ref> instead). + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Respond" tp:name-for-bindings="Respond"> + <arg direction="in" name="Response_Data" type="ay"> + <tp:docstring> + The response data. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Send a response to the the last challenge received via + <tp:member-ref>NewChallenge</tp:member-ref>.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is not In_Progress, or no challenge has been + received yet, or you have already responded to the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AcceptSASL" tp:name-for-bindings="Accept_SASL"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the channel's status is SASL_Status_Server_Succeeded, + this method confirms successful authentication and advances + the status of the channel to SASL_Status_Succeeded.</p> + + <p>If the channel's status is SASL_Status_In_Progress, calling this + method indicates that the last + <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact + additional data sent after a successful SASL negotiation, and + declares that from the client's point of view, authentication + was successful. This advances the state of the channel to + SASL_Status_Client_Accepted.</p> + + <p>In mechanisms where the server authenticates itself to the client, + calling this method indicates that the client considers this to have + been successful. In the case of <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channels, this means that the connection manager MAY continue to + connect, and MAY advance the <tp:dbus-ref + namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is neither In_Progress nor Server_Succeeded, or no + challenge has been received yet, or you have already responded to + the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AbortSASL" tp:name-for-bindings="Abort_SASL"> + <arg direction="in" name="Reason" type="u" tp:type="SASL_Abort_Reason"> + <tp:docstring> + Reason for abort. + </tp:docstring> + </arg> + <arg direction="in" name="Debug_Message" type="s"> + <tp:docstring> + Debug message for abort. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Abort the current authentication try.</p> + + <p>If the current status is SASL_Status_Server_Failed or + SASL_Status_Client_Failed, this method returns successfully, but has + no further effect. If the current status is SASL_Status_Succeeded + or SASL_Status_Client_Accepted then NotAvailable is raised. + Otherwise, it changes the channel's state to + SASL_Status_Client_Failed, with an appropriate error name and + reason code.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The current state is either Succeeded or Client_Accepted. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="SASLStatusChanged" tp:name-for-bindings="SASL_Status_Changed"> + <tp:docstring> + Emitted when the status of the channel changes. + </tp:docstring> + <arg type="u" tp:type="SASL_Status" name="Status"> + <tp:docstring> + The new value of <tp:member-ref>SASLStatus</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="s" tp:type="DBus_Error_Name" name="Reason"> + <tp:docstring> + The new value of <tp:member-ref>SASLError</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="a{sv}" tp:type="String_Variant_Map" name="Details"> + <tp:docstring> + The new value of <tp:member-ref>SASLErrorDetails</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="NewChallenge" tp:name-for-bindings="New_Challenge"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new challenge is received from the server, or when + a message indicating successful authentication and containing + additional data is received from the server.</p> + + <p>When the channel's handler is ready to proceed, it should respond + to the challenge by calling <tp:member-ref>Respond</tp:member-ref>, + or respond to the additional data by calling + <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call + <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p> + </tp:docstring> + <arg name="Challenge_Data" type="ay"> + <tp:docstring> + The challenge data or additional data from the server. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="SASL_Abort_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why SASL authentication was aborted by the client.</p> + </tp:docstring> + + <tp:enumvalue suffix="Invalid_Challenge" value="0"> + <tp:docstring> + The server sent an invalid challenge or data. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="User_Abort" value="1"> + <tp:docstring> + The user aborted the authentication. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="SASL_Status" type="u" plural="SASL_Statuses"> + <tp:enumvalue suffix="Not_Started" value="0"> + <tp:docstring> + The initial state. The Handler SHOULD either + call <tp:member-ref>AbortSASL</tp:member-ref>, or connect to the + <tp:member-ref>NewChallenge</tp:member-ref> signal then call + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref>. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="In_Progress" value="1"> + <tp:docstring> + The challenge/response exchange is in progress. The Handler SHOULD + call either <tp:member-ref>Respond</tp:member-ref> or + <tp:member-ref>AcceptSASL</tp:member-ref> exactly once per emission + of <tp:member-ref>NewChallenge</tp:member-ref>, or call + <tp:member-ref>AbortSASL</tp:member-ref> at any time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Succeeded" value="2"> + <tp:docstring> + The server has indicated successful authentication, and the + connection manager is waiting for confirmation from the Handler. + The Handler must call either <tp:member-ref>AcceptSASL</tp:member-ref> or + <tp:member-ref>AbortSASL</tp:member-ref> to indicate whether it + considers authentication to have been successful. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Accepted" value="3"> + <tp:docstring> + The Handler has indicated successful authentication, and the + connection manager is waiting for confirmation from the server. + The state will progress to either Succeeded or Server_Failed when + confirmation is received. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Succeeded" value="4"> + <tp:docstring> + Everyone is happy (the server sent success, and the client has called + <tp:member-ref>AcceptSASL</tp:member-ref>). Connection to the server + will proceed as soon as this state is reached. The Handler SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + to close the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Failed" value="5"> + <tp:docstring> + The server has indicated an authentication failure. + If <tp:member-ref>CanTryAgain</tp:member-ref> is true, + the client may try to authenticate again, by calling + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref> again. + Otherwise, it should give up completely, by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Failed" value="6"> + <tp:docstring> + The client has indicated an authentication failure. The + possible actions are the same as for Server_Failed. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml new file mode 100644 index 0000000..4cfe3f2 --- /dev/null +++ b/spec/Channel_Interface_SMS.xml @@ -0,0 +1,179 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_SMS" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Channel.Interface.SMS"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + <tp:added version='0.19.12'>Imported from + rtcom-telepathy-glib, with the unused properties removed and the + documentation tidied up.</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains SMS-specific properties for text + channels.</p> + + <p>The presence of this interface on a channel does not imply that + messages will be delivered via SMS.</p> + + <p>This interface MAY appear in the + <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property + of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be + immutable and false. It SHOULD appear on channels where + <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and + also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is + mutable (i.e. channels that might fall back to sending SMS at any + time, such as on MSN).</p> + + <h4>Handler filters</h4> + + <p>A handler for class 0 SMSes should advertise the following filter:</p> + + <blockquote><code> +{ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>: + ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/> + ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>: + <tp:type>Handle_Type</tp:type>_Contact,<br/> + ...<tp:dbus-ref namespace='ofdT.Channel.Interface'>SMS.Flash</tp:dbus-ref>: + True,<br/> +}</code></blockquote> + + <p>It should also set its <tp:dbus-ref + namespace='ofdT.Client.Handler'>BypassApproval</tp:dbus-ref> property + to <code>True</code>, so that it is invoked immediately for new + channels.</p> + </tp:docstring> + + <property name="Flash" tp:name-for-bindings="Flash" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <code>True</code>, then this channel is exclusively for + receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref + namespace='ofdT.Channel.Interface.Messages'>SendMessage</tp:dbus-ref> + on this channel). If <code>False</code>, no incoming class 0 SMSes + will appear on this channel.</p> + + <p>This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests" + >NewChannels</tp:dbus-ref> signals.</p> + + <tp:rationale> + <p>Class 0 SMSes should be displayed immediately to the user, and + need not be saved to the device memory unless the user explicitly + chooses to do so. This is unlike “normal”, class 1 SMSes, which + must be stored, but need not be shown immediately in their entirity + to the user.</p> + + <p>Separating class 0 SMSes into their own channel with this + immutable property allows them to be dispatched to a different + <tp:dbus-ref namespace='ofdT.Client'>Handler</tp:dbus-ref>—which + would include this property in its <tp:dbus-ref + namespace='ofdT.Client.Handler' + >HandlerChannelFilter</tp:dbus-ref>—avoiding the normal Text + channel handler having to decide for each message whether it should + be displayed to the user immediately or handled normally.</p> + + <p>Currently, no mechanism is defined for <em>sending</em> class 0 + SMSes. It seems reasonable to support specifying the class of an + outgoing SMS in its header <tp:type>Message_Part</tp:type>, rather + than requiring the UI to request a special channel for such SMSes; + hence, we define here that channels with Flash set to + <code>True</code> are read-only.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="SMSChannel" + tp:name-for-bindings="SMS_Channel" + type="b" + access="read" tp:requestable="yes" tp:immutable="sometimes"> + <tp:added version="0.21.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If TRUE, messages sent and received on this channel are transmitted + via SMS.</p> + + <p>If this property is included in the channel request, the + Connection Manager MUST return an appropriate channel (i.e. if TRUE + the channel must be for SMSes, if FALSE it must not), or else fail + to provide the requested channel with the + <tp:error-ref>NotCapable</tp:error-ref> + error.</p> + + <p>For example, to explicitly request an SMS channel to a contact. + You might construct a channel request like:</p> + + <blockquote><pre>{ + Channel.Type: Channel.Type.Text, + Channel.TargetHandleType: Handle_Type_Contact, + Channel.TargetID: escher.cat, + Channel.Interface.SMS.SMSChannel: True, +}</pre></blockquote> + + <tp:rationale> + Some protocols allow us to send SMSes to a remote contact, without + knowing the phone number to which those SMSes will be sent. This + provides a mechanism to request such channels. + </tp:rationale> + + <p>If this property is not included in the channel request, the + Connection Manager MAY return an SMS channel if that is the most + appropriate medium (i.e. if the channel target is a phone + number).</p> + + <tp:rationale> + To some types of identifiers (i.e. phone numbers) it only makes + sense to return an SMS channel, this is what happens currently with + telepathy-ring. We don't want to break this behaviour when we are + not explicit about the type of channel we want. Alternatively, for + protocols where there is an SMS fallback for IM messages, it's + possible that we don't care what sort of channel we get, and simply + want notification of the transport. + </tp:rationale> + + <p>Some protocols have a fallback to deliver IM messages via SMS. + On these protocols, the Connection Manager SHOULD set the property + value as appropriate, and notify its change with + <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p> + + <tp:rationale> + Protocols such as MSN can fall back to delivering IM messages via + SMS. Where possible we want clients to be able to inform the user + that their messages are going to be redirected to the remote + contact's phone. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="SMSChannelChanged" + tp:name-for-bindings="SMS_Channel_Changed"> + <tp:added version="0.21.7"/> + <arg name="SMSChannel" type="b"> + <tp:docstring> + The new value for <tp:member-ref>SMSChannel</tp:member-ref>. + </tp:docstring> + </arg> + <tp:docstring> + This signal indicates a change in the + <tp:member-ref>SMSChannel</tp:member-ref> property. + </tp:docstring> + </signal> + </interface> +</node> diff --git a/spec/Channel_Interface_Securable.xml b/spec/Channel_Interface_Securable.xml new file mode 100644 index 0000000..d9d9713 --- /dev/null +++ b/spec/Channel_Interface_Securable.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Securable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright> + + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Securable"> + <tp:added version="0.21.5">as stable API</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to expose security information about + <tp:dbus-ref namespace="ofdT">Channel</tp:dbus-ref>s. The two + properties are sometimes immutable and can be used to make + decisions on how cautious to be about transferring sensitive + data. The special case of <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channels is one example of where the two properties are + immutable.</p> + + <p>For example, clients MAY use these properties to decide + whether the <code>PLAIN</code> mechanism is acceptable for a + <tp:dbus-ref + namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref> + channel.</p> + </tp:docstring> + + <property name="Encrypted" + tp:name-for-bindings="Encrypted" type="b" + access="read" tp:immutable="sometimes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel occurs over an encrypted + connection. This <strong>does not</strong> imply that steps + have been taken to avoid man-in-the-middle attacks.</p> + + <tp:rationale> + <p>For future support for <a + href="http://tools.ietf.org/html/rfc5056">RFC 5056 Channel + Binding</a> it is desirable to be able to use some SASL + mechanisms over an encrypted connection to an unverified peer, + which can prove that it is the desired destination during + the SASL negotiation.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="Verified" + tp:name-for-bindings="Verified" type="b" + access="read" tp:immutable="sometimes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel occurs over a connection that is + protected against tampering, and has been verified to be with + the desired destination: for instance, one where TLS was + previously negotiated, and the TLS certificate has been + verified against a configured certificate authority or + accepted by the user.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml new file mode 100644 index 0000000..787397b --- /dev/null +++ b/spec/Channel_Interface_Service_Point.xml @@ -0,0 +1,86 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint"> + <tp:added version="0.19.7">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for channels + that can indicate when/if they are connected to some form + of service point. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.</p> + + <p>Note that while the majority of examples given in this + documentation are for GSM calls, they could just as easily be + SIP calls, GSM SMS's, etc.</p> + </tp:docstring> + + <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point" + type="(us)" tp:type="Service_Point" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This property is used to indicate that the channel target is a + well-known service point. Please note that the CM (or lower layers + of the stack or network) may forward the connection to other other + service points, which the CM SHOULD indicate via + <tp:member-ref>ServicePointChanged</tp:member-ref> + signal.</p> + + <p>This property SHOULD be set for channel requests that are + specifically targeting service points.</p> + </tp:docstring> + </property> + + <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point" + type="(us)" tp:type="Service_Point" access="read"> + <tp:docstring> + The service point that the channel is connected to. If the channel is + not connected to a service point, the CM MUST set the + <tp:type>Service_Point_Type</tp:type> field to None; for instance, + this will be the case for ordinary calls. + </tp:docstring> + </property> + + <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed"> + <tp:docstring> + <p>Emitted when a channel changes the service point that it's connected to. This + might be a new call being connected to a service, a call connected to + a service being routed to a different service + (ie, an emergency call being routed from a generic emergency PSAP to + a poison control PSAP), or any number of other things.</p> + + <p>Note that this should be emitted as soon as the CM has been notified + of the switch, and has updated its internal state. The CM MAY still + be in the process of connecting to the new service point.</p> + </tp:docstring> + + <arg name="Service_Point" type="(us)" tp:type="Service_Point"> + <tp:docstring> + The new service point that is being used. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml new file mode 100644 index 0000000..760c134 --- /dev/null +++ b/spec/Channel_Interface_Splittable.xml @@ -0,0 +1,71 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Splittable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Channel.Interface.Splittable.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for channels that can be made conceptually part of a + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Conference</tp:dbus-ref>, and can then be detached from that + conference.</p> + + <tp:rationale> + <p>This interface addresses part of freedesktop.org <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug + #24906</a> (GSM-compatible conference calls). GSM is currently + the only protocol known to implement this; PBXs might implement + it too.</p> + </tp:rationale> + </tp:docstring> + + <method name="Split" + tp:name-for-bindings="Split"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that this channel is removed from any + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Conference</tp:dbus-ref> of which it is a part.</p> + + <p>This implies that the media streams within the conference are put on + hold and the media streams within the member channel leaving the + conference are unheld.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + This channel isn't in a conference. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This channel is in a conference but can't currently be split away + from it. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> diff --git a/spec/Channel_Interface_Transfer.xml b/spec/Channel_Interface_Transfer.xml new file mode 100644 index 0000000..02591c1 --- /dev/null +++ b/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/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml new file mode 100644 index 0000000..858a15d --- /dev/null +++ b/spec/Channel_Interface_Tube.xml @@ -0,0 +1,258 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A <i>tube</i> is a mechanism for arbitrary data transfer between + two or more IM users, used to allow applications on the users' + systems to communicate without having to establish network + connections themselves. Currently, two types of tube exist: + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Type.DBusTube</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains + the properties, signals and methods common to both types of tube; + you can only create channels of a specific tube type, not of this + type. A tube channel contains exactly one tube; if you need several + tubes, you have to create several tube channels.</p> + + <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type> + Contact (for 1-1 communication) or Room (to communicate with others in + the room simultaneously).</p> + + <p>As an exception to the usual handling of capabilities, connection managers + for protocols with capability discovery (such as XMPP) SHOULD advertise the + capability representing each Tube type that they support + (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>) + even if no client has indicated via + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> + that such a tube is supported. They SHOULD also allow clients to offer tubes with any + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref> + to any contact which supports the corresponding tube capability.</p> + + <tp:rationale> + <p>This lowers the barrier to entry for those writing new tube + applications, and preserves interoperability with older versions of + the Telepathy stack which did not support rich capabilities.</p> + </tp:rationale> + </tp:docstring> + + <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" + access="read" tp:name-for-bindings="Parameters"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Each tube has a dictionary of arbitrary parameters. Parameters are + commonly used to bootstrap legacy protocols where you can't + negotiate parameters in-band. The allowable keys, + types and values are defined by the service, but connection managers + must support the value being a string (D-Bus type <tt>'s'</tt>), + array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus + type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean + (D-Bus type <tt>'b'</tt>).</p> + + <p>When the tube is offered, the parameters are transmitted with the + offer and appear as a property of the incoming tube for other + participants.</p> + + <p>For example, a stream tube for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> + <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might + use the following properties, as defined in <a + href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782) + Service Types</a>:</p> + + <pre> +{ 'u': 'some-username', + 'p': 'top-secret-password', + 'path': '/etc/passwd', +}</pre> + + <p>When requesting a tube with + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, + this property MUST NOT be included in the request; instead, it is set + when <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref> + (as appropriate) is called. Its value is undefined until the tube is + offered; once set, its value MUST NOT change.</p> + + <p>When receiving an incoming tube, this property is immutable and so advertised in the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="State" type="u" tp:type="Tube_Channel_State" access="read" + tp:name-for-bindings="State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>State of the tube in this channel.</p> + + <p>When requesting a tube with + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, + this property MUST NOT be included in the request.</p> + </tp:docstring> + </property> + + <tp:enum name="Tube_Channel_State" type="u"> + <tp:enumvalue suffix="Local_Pending" value="0"> + <tp:docstring> + The initiator offered the tube. The tube is waiting to be + accepted/closed locally. If the client accepts the tube, the tube's + state will be Open. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:docstring> + The tube is waiting to be accepted/closed remotely. If the + recipient accepts the tube, the tube's state will be Open. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="2"> + <tp:docstring> + The initiator offered the tube and the recipient accepted it. The + tube is open for traffic. The tube's state stays in this state until + it is closed. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Offered" value="3"> + <tp:docstring> + The tube channel has been requested but the tube is not yet offered. + The client should offer the tube to the recipient and the tube's + state will be Remote_Pending. The method used to offer the tube + depends on the tube type. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="TubeChannelStateChanged" + tp:name-for-bindings="Tube_Channel_State_Changed"> + <tp:docstring> + Emitted when the state of the tube channel changes. Valid state + transitions are documented with <tp:type>Tube_Channel_State</tp:type>. + </tp:docstring> + <arg name="State" type="u" tp:type="Tube_Channel_State"> + <tp:docstring> + The new state of the tube. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Socket_Address_Type" type="u"> + <tp:enumvalue suffix="Unix" value="0"> + <tp:docstring> + A Unix socket. The address variant contains a byte-array, signature 'ay', + containing the path of the socket. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Abstract_Unix" value="1"> + <tp:docstring> + An abstract Unix socket. The address variant contains a byte-array, + signature 'ay', containing the path of the socket including the + leading null byte. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="IPv4" value="2"> + <tp:docstring> + An IPv4 socket. The address variant contains a Socket_Address_IPv4, + i.e. a structure with signature (sq) + in which the string is an IPv4 dotted-quad address literal + (and must not be a DNS name), while the 16-bit unsigned integer is + the port number. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="IPv6" value="3"> + <tp:docstring> + An IPv6 socket. The address variant contains a Socket_Address_IPv6, + i.e. a structure with signature (sq) + in which the string is an IPv6 address literal as specified in + RFC2373 (and must not be a DNS name), while the 16-bit unsigned + integer is the port number. + </tp:docstring> + </tp:enumvalue> + + </tp:enum> + + <tp:enum name="Socket_Access_Control" type="u" + array-name="Socket_Access_Control_List"> + <tp:enumvalue suffix="Localhost" value="0"> + <tp:docstring> + The IP or Unix socket can be accessed by any local user (e.g. + a Unix socket that accepts all local connections, or an IP socket + listening on 127.0.0.1 (or ::1) or rejecting connections not from + that address). The associated variant must be ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Port" value="1"> + <tp:docstring> + May only be used on IP sockets. The associated variant must contain + a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the string form of an IP address of the appropriate + version, and a port number. The socket can only be accessed if the + connecting process has that address and port number; all other + connections will be rejected. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Netmask" value="2"> + <tp:deprecated version="0.17.25">This has never been implemented. + If you want to share a service to your whole LAN, Telepathy is + not the way to do it.</tp:deprecated> + <tp:docstring> + May only be used on IP sockets. The associated variant must contain + a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with + signature (sy), containing the string form of an + IP address of the appropriate version, and a prefix length "n". + The socket can only be accessed if the first n bits of the + connecting address match the first n bits of the given address. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Credentials" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>May only be used on UNIX sockets. + The connecting process must send a byte when + it first connects, which is not considered to be part of the data + stream. If the operating system uses sendmsg() with SCM_CREDS or + SCM_CREDENTIALS to pass credentials over sockets, the connecting + process must do so if possible; if not, it must still send the + byte.</p> + + <p>The listening process will disconnect the connection unless it + can determine by OS-specific means that the connecting process + has the same user ID as the listening process.</p> + + <p>The associated variant must be ignored.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml new file mode 100644 index 0000000..1a9c397 --- /dev/null +++ b/spec/Channel_Request.xml @@ -0,0 +1,300 @@ +<?xml version="1.0" ?> +<node name="/Channel_Request" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, + MA 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelRequest"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel request is an object in the ChannelDispatcher representing + an ongoing request for some channels to be created or found. There + can be any number of ChannelRequest objects at the same time.</p> + + <p>Its well-known bus name is the same as that of the ChannelDispatcher, + "org.freedesktop.Telepathy.ChannelDispatcher".</p> + + <tp:rationale> + <p>See + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.CreateChannel</tp:dbus-ref> + for rationale for ChannelRequest being a separate object.</p> + </tp:rationale> + + <p>A channel request can be cancelled by any client (not just the one + that requested it). This means that the ChannelDispatcher will + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + the resulting channel, or refrain from requesting it at all, rather + than dispatching it to a handler.</p> + </tp:docstring> + + <property name="Account" tp:name-for-bindings="Account" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + on which this request was made. This property cannot change. + </tp:docstring> + </property> + + <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" + type="x" tp:type="User_Action_Timestamp" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <property name="PreferredHandler" tp:name-for-bindings="Preferred_Handler" + type="s" tp:type="DBus_Well_Known_Name" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable.</p> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}" + tp:type="Qualified_Property_Value_Map[]" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of dictionaries containing desirable properties for + the channel or channels to be created.</p> + + <tp:rationale> + <p>This is an array so that we could add a CreateChannels method in + future without redefining the API of ChannelRequest.</p> + </tp:rationale> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel request. + This property cannot change. + </tp:docstring> + </property> + + <method name="Proceed" tp:name-for-bindings="Proceed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Proceed with the channel request.</p> + + <tp:rationale> + <p>The client that created this object calls this method + when it has connected signal handlers for + <tp:member-ref>Succeeded</tp:member-ref> and + <tp:member-ref>Failed</tp:member-ref>.</p> + </tp:rationale> + + <p>Clients other than the client which created the ChannelRequest + MUST NOT call this method.</p> + + <p>This method SHOULD return immediately; on success, the request + might still fail, but this will be indicated asynchronously + by the <tp:member-ref>Failed</tp:member-ref> signal.</p> + + <p>Proceed cannot fail, unless clients have got the life-cycle + of a ChannelRequest seriously wrong (e.g. a client calls this + method twice, or a client that did not create the ChannelRequest + calls this method). If it fails, clients SHOULD assume that the + whole ChannelRequest has become useless.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This method has already been called, so it is no longer + available. Stop calling it. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Cancel" tp:name-for-bindings="Cancel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Cancel the channel request. The precise effect depends on the + current progress of the request.</p> + + <p>If the connection manager has not already been asked to create + a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted + immediately, and the channel request is removed.</p> + + <p>If the connection manager has already been asked to create a + channel but has not produced one yet (e.g. if <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + has been called, but has not yet returned), then the + ChannelDispatcher will remember that the request has been cancelled. + When the channel appears, it will be closed (if it was newly + created and can be closed), and will not be dispatched to a + handler.</p> + + <p>If the connection manager has already returned a channel, but the + channel has not yet been dispatched to a handler + then the channel dispatcher will not dispatch that + channel to a handler. If the channel was newly created for this + request, the channel dispatcher will close it with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>; + otherwise, the channel dispatcher will ignore it. In either case, + <tp:member-ref>Failed</tp:member-ref> will be emitted when processing + has been completed.</p> + + <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to + this method, the error SHOULD be + <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> + + <p>If the channel has already been dispatched to a handler, then + it's too late to call this method, and the channel request will + no longer exist.</p> + </tp:docstring> + </method> + + <signal name="Failed" tp:name-for-bindings="Failed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has failed. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error. This can come from various sources, + including the error raised by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, + or an error generated + to represent failure to establish the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + If the first argument of the D-Bus error message was a string, + that string. Otherwise, an empty string. + </tp:docstring> + </arg> + </signal> + + <signal name="Succeeded" tp:name-for-bindings="Succeeded"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has succeeded. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + </signal> + + <property name="Hints" tp:name-for-bindings="Hints" + type="a{sv}" access="read"> + <tp:added version="0.21.5"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary of metadata provided by the channel + requester, which the handler and other clients MAY choose to + interpret. Currently no standard keys are defined; clients MAY + choose to use platform-specific keys for their own purposes, but MUST + ignore unknown keys and MUST cope with expected keys being + missing. Clients SHOULD namespace hint names by having them + start with a reversed domain name, in the same way as D-Bus + interface names.</p> + + <tp:rationale>This property might be used to pass a contact ID for a + telephone number shared between two contacts from the address book to + the call UI, so that if you try to call “Mum”, the call UI knows this + rather than having to guess or show “Calling Mum or Dad”. The format + of these contact IDs would be platform-specific, so we leave the + definition of the dictionary entry up to the platform in question. + But third-party channel requesters might not include the contact ID, + so the call UI has to be able to deal with it not being + there.</tp:rationale> + + <p>The channel dispatcher does not currently interpret any of these + hints: they are solely for communication between cooperating + clients. If hints that do affect the channel dispatcher are added in + future, their names will start with an appropriate reversed domain + name (e.g. <code>org.freedesktop.Telepathy</code> for hints defined + by this specification, or an appropriate vendor name for third-party + plugins).</p> + + <p>This property may be set when the channel request is created, and + can never change. Since it is immutable, it SHOULD be included in the + dictionary of properties passed to <tp:dbus-ref + namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref> + by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p> + </tp:docstring> + </property> + + <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel"> + <tp:added version="0.21.5"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Variant of the <tp:dbus-ref + namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal + allowing to get the channel which has been created.</p> + + <p>This signal MUST be emitted if the + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>'s + <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">SupportsRequestHints</tp:dbus-ref> + property is true. If supported, it MUST be emitted before + the <tp:member-ref>Succeeded</tp:member-ref> signal.</p> + </tp:docstring> + + <arg name="Connection" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Connection owning the channel.</p> + </tp:docstring> + </arg> + + <arg name="Connection_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A subset of the Connection's properties, currently unused. + This parameter may be used in future.</p> + </tp:docstring> + </arg> + + <arg name="Channel" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel which has been created.</p> + </tp:docstring> + </arg> + + <arg name="Channel_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same immutable properties of the Channel that would appear + in a <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests" + >NewChannels</tp:dbus-ref> signal.</p> + </tp:docstring> + </arg> + + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml new file mode 100644 index 0000000..039c1f9 --- /dev/null +++ b/spec/Channel_Type_Call.xml @@ -0,0 +1,1429 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for making audio and video calls. Call + channels supersede the old <tp:dbus-ref + namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref> + channel type. Call channels are much more flexible than its + predecessor and allow more than two participants.</p> + + <p>Handlers are advised against executing all the media + signalling, codec and candidate negotiation themselves but + instead use a helper library such as <a + href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a> + which when given a new Call channel will set up the + transports and codecs and create GStreamer pads which + can be added to the handler UI. This is useful as it means + the handler does not have to worry how exactly the + connection between the call participants is being made.</p> + + <p>The <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> + properties in a Call channel refer to the contact that the + user initially called, or which contact initially called the + user. Even in a conference call, where there are multiple + contacts in the call, these properties refer to the + initial contact, who might have left the conference since + then. As a result, handlers should not rely on these + properties.</p> + + <h4>Contents</h4> + + <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> + objects represent the actual media that forms the Call (for + example an audio content and a video content). Calls always + have one or more Content objects associated with them. As a + result, a new Call channel request MUST have either + <tp:member-ref>InitialAudio</tp:member-ref>=True, or + <tp:member-ref>InitialVideo</tp:member-ref>=True, or both, + as the Requestable Channel Classes will document.</p> + + <p><tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have + one or more stream associated with them. More information on + these streams and how to maniuplate them can be found on the + <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> + interface page.</p> + + <h4>Outgoing calls</h4> + + <p>To make an audio-only call to a contact <tt>foo@example.com</tt> + handlers should call:</p> + + <blockquote> + <pre> +<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + ...<tp:member-ref>InitialAudio</tp:member-ref>: True, +})</pre></blockquote> + + <p>As always, <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used + in place of + <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> + if the contact's handle is already known. To make an audio + and video call, the handler should also specify + <tp:member-ref>InitialVideo</tp:member-ref> The + connection manager SHOULD return a channel whose immutable + properties contain the local user as the <tp:dbus-ref + namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the + remote contact as the <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> = + <code>True</code> (indicating the call is outgoing).</p> + + <p>After a new Call channel is requested, the + <tp:member-ref>CallState</tp:member-ref> property will be + <tp:type>Call_State</tp:type>_Pending_Initiator. As the local + user is the initiator, the call must be accepted by the handler + by calling the <tp:member-ref>Accept</tp:member-ref> method. + At this point, <tp:member-ref>CallState</tp:member-ref> changes + to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies + that the call is ringing, waiting for the remote contact to + accept the call. All changes to + <tp:member-ref>CallState</tp:member-ref> property are signalled + using the <tp:member-ref>CallStateChanged</tp:member-ref> + signal.</p> + + <p>When the call is accepted by the remote contact, the + <tp:member-ref>CallStateChanged</tp:member-ref> signal fires + again to show that <tp:member-ref>CallState</tp:member-ref> = + <tp:type>Call_State</tp:type>_Accepted.</p> + + <p>At this point <a + href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a> + will signal that a pad is available for the handler to show + in the user interface.</p> + + <h5>Missed calls</h5> + + <p>If the remote contact does not accept the call in time, then + the call can be terminated by the server. Note that this only + happens in some protocols. Most XMPP clients, for example, do + not do this and rely on the call initiator terminating the call. + A missed call is shown in a Call channel by the + <tp:member-ref>CallState</tp:member-ref> property changing to + <tp:type>Call_State</tp:type>_Ended, and the + <tp:member-ref>CallStateReason</tp:member-ref> property changing + to (remote contact, + <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p> + + <h5>Rejected calls</h5> + + <p>If the remote contact decides he or she does not feel like + talking to the local user, he or she can reject his or her + incoming call. This will be shown in the Call channel by + <tp:member-ref>CallState</tp:member-ref> changing to + <tp:type>Call_State</tp:type>_Ended and the + <tp:member-ref>CallStateReason</tp:member-ref> property + changing to (remote contact, + <tp:type>Call_State</tp:type>_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").</p> + + <h4>Incoming calls</h4> + + <p>When an incoming call occurs, something like the following + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal will occur:</p> + + <blockquote> + <pre> +<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([ + /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel, + { + ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42, + ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False, + ...<tp:member-ref>InitialAudio</tp:member-ref>: True, + ...<tp:member-ref>InitialVideo</tp:member-ref>: True, + ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio", + ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video", + ...<tp:member-ref>MutableContents</tp:member-ref>: True, + }])</pre></blockquote> + + <p>The <tp:member-ref>InitialAudio</tp:member-ref> and + <tp:member-ref>InitialVideo</tp:member-ref> properties show that + the call has been started with two contents: one for audio + streaming and one for video streaming. The + <tp:member-ref>InitialAudioName</tp:member-ref> and + <tp:member-ref>InitialVideoName</tp:member-ref> properties also + show that the aforementioned audio and video contents have names + "audio" and "video".</p> + + <p>Once the handler has notified the local user that there is an + incoming call waiting for acceptance, the handler should call + <tp:member-ref>SetRinging</tp:member-ref> to let the CM know. + The new channel should also be given to telepathy-farsight to + work out how the two participants will connect together. + telepathy-farsight will call the appropriate methods on the call's + <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s + to negotiate codecs and transports.</p> + + <p>To pick up the call, the handler should call + <tp:member-ref>Accept</tp:member-ref>. The + <tp:member-ref>CallState</tp:member-ref> property changes to + <tp:type>Call_State</tp:type>_Accepted and once media is + being transferred, telepathy-farsight will notify the + handler of a new pad to be shown to the local user in the + UI</p> + + <p>To reject the call, the handler should call the + <tp:member-ref>Hangup</tp:member-ref> method. The + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and the + <tp:member-ref>CallStateReason</tp:member-ref> property will + change to (self handle, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").</p> + + <h4>Ongoing calls</h4> + + <h5>Adding and removing contents</h5> + + <p>When a call is open, new contents can be added as long as the + CM supports it. The + <tp:member-ref>MutableContents</tp:member-ref> property will let + the handler know whether further contents can be added or + existing contents removed. An example of this is starting a + voice call between a contact and then adding a video content. + To do this, the should call + <tp:member-ref>AddContent</tp:member-ref> like this:</p> + + <blockquote> + <pre><tp:member-ref>AddContent</tp:member-ref>("video", + <tp:type>Media_Stream_Type</tp:type>_Video)</pre> + </blockquote> + + <p>Assuming no errors, the new video content will be added to + the call. telepathy-farsight will pick up the new content and + perform the transport and codec negotiation automatically. + telpathy-farsight will signal when the video is ready to + show in the handler's user interface.</p> + + <p>A similar method is used for removing contents from a call, + except that the <tp:dbus-ref + namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method + is on the <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p> + + <h5>Ending the call</h5> + + <p>To end the call, the handler should call the + <tp:member-ref>Hangup</tp:member-ref> method. The + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and + <tp:member-ref>CallStateReason</tp:member-ref> will change + to (self handle, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Cancelled").</p> + + <p>If the other participant hangs up first then the + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and + <tp:member-ref>CallStateReason</tp:member-ref> will change + to (remote contact, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated").</p> + + <h4>Multi-party calls</h4> + + [TODO] + + <h4>Call states</h4> + + <p>There are many combinations of the + <tp:member-ref>CallState</tp:member-ref> and + <tp:member-ref>CallStateReason</tp:member-ref> properties which + mean different things. Here is a table to try to make these + meanings clearer:</p> + + <table> + <tr> + <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th> + <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th> + <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th> + <th rowspan="2">Meaning</th> + </tr> + <tr> + <th>Actor</th> + <th>Reason</th> + <th>DBus_Reason</th> + </tr> + <!-- Pending_Initiator --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Pending_Initiator</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td> + </tr> + <!-- Pending_Receiver --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The outgoing call is waiting for the remote contact to pick up the call.</td> + </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> + <td>0</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td> + <td>""</td> + <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td> + </tr> + <!-- Accepted --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Accepted</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The remote contact accepted the outgoing call.</td> + </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Accepted</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The local user accepted the incoming call.</td> + </tr> + <!-- Ended --> + <tr> + <td>True or False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>Cancelled</tp:error-ref></td> + <td>The local user hung up the incoming or outgoing call.</td> + </tr> + <tr> + <td>True or False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>Terminated</tp:error-ref></td> + <td>The remote contact hung up the incoming or outgoing call.</td> + </tr> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td> + <td>""</td> + <td>The outgoing call was not picked up and the call ended.</td> + </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td> + <td>The incoming call was ended because it was picked up elsewhere.</td> + </tr> + </table> + + <h4>Requestable channel classes</h4> + + <p>The <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + for <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + can be:</p> + + <blockquote> + <pre> +[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:member-ref>InitialVideo</tp:member-ref>: True + }, + Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>, + ...<tp:member-ref>InitialAudio</tp:member-ref>, + ...<tp:member-ref>InitialAudioName</tp:member-ref> + ] +), +( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:member-ref>InitialAudio</tp:member-ref>: True + }, + Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>, + ...<tp:member-ref>InitialVideo</tp:member-ref>, + ...<tp:member-ref>InitialVideoName</tp:member-ref> + ] +)]</pre></blockquote> + + <p>Clients aren't allowed to make outgoing calls that have + neither initial audio nor initial video. Clearly, CMs + which don't support video should leave out the first class and + omit <tp:member-ref>InitialVideo</tp:member-ref> from the second + class, and vice versa for CMs without audio support.</p> + + <p>Handlers should not close <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + without first calling <tp:member-ref>Hangup</tp:member-ref> on + the channel. If a Call handler crashes, the <tp:dbus-ref + namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the + channel which SHOULD also imply a call to + <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated", "") before + actually closing the channel.</p> + + </tp:docstring> + + <method name="SetRinging" tp:name-for-bindings="Set_Ringing"> + <tp:changed version="0.21.2">renamed from Ringing</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Indicate that the local user has been alerted about the incoming + call.</p> + + <p>This method is only useful if the + channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> + property is False, and + the <tp:member-ref>CallState</tp:member-ref> is + <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming + call waiting on the local user to pick up). While this is + the case, this method SHOULD change the + <tp:member-ref>CallFlags</tp:member-ref> to include + <tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the + remote contact that the local user has been alerted (if the + protocol implements this); repeated calls to this method + SHOULD succeed, but have no further effect.</p> + + <p>In all other states, this method SHOULD fail with the error + NotAvailable.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The call was <tp:dbus-ref namespace="ofdT.Channel" + >Requested</tp:dbus-ref>, so ringing does not make sense. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The call is no longer in state + <tp:type>Call_State</tp:type>_Pending_Receiver. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Accept" tp:name-for-bindings="Accept"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For incoming calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver, accept the + incoming call; this changes the + <tp:member-ref>CallState</tp:member-ref> to + <tp:type>Call_State</tp:type>_Accepted.</p> + + <p>For outgoing calls in state + <tp:type>Call_State</tp:type>_Pending_Initiator, actually + call the remote contact; this changes the + <tp:member-ref>CallState</tp:member-ref> to + <tp:type>Call_State</tp:type>_Pending_Receiver.</p> + + <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> + + <p>This method should be called exactly once per Call, by whatever + client (user interface) is handling the channel.</p> + + <p>When this method is called, for each <tp:dbus-ref + namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose + <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" + >Disposition</tp:dbus-ref> is + <tp:type>Call_Content_Disposition</tp:type>_Initial, any + streams where the <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> + is <tp:type>Sending_State</tp:type>_Pending_Send will be + moved to <tp:type>Sending_State</tp:type>_Sending as if + <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" + >SetSending</tp:dbus-ref>(True) had been called.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The call is not in one of the states where this method makes sense. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Hangup" tp:name-for-bindings="Hangup"> + <tp:docstring> + Request that the call is ended. All contents will be removed + from the Call so that the + <tp:member-ref>Contents</tp:member-ref> property will be the + empty list. + </tp:docstring> + + <arg direction="in" name="Reason" + type="u" tp:type="Call_State_Change_Reason"> + <tp:docstring> + A generic hangup reason. + </tp:docstring> + </arg> + + <arg direction="in" name="Detailed_Hangup_Reason" + type="s" tp:type="DBus_Error_Name"> + <tp:docstring> + A more specific reason for the call hangup, if one is available, or + an empty string otherwise. + </tp:docstring> + </arg> + + <arg direction="in" name="Message" type="s"> + <tp:docstring> + A human-readable message to be sent to the remote contact(s). + + <tp:rationale> + XMPP Jingle allows calls to be terminated with a human-readable + message. + </tp:rationale> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The call has already been ended. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="AddContent" tp:name-for-bindings="Add_Content"> + <tp:docstring> + Request that a new <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type + Content_Type is added to the Call. Handlers should check the + value of the <tp:member-ref>MutableContents</tp:member-ref> + property before trying to add another content as it might not + be allowed. + </tp:docstring> + <arg direction="in" name="Content_Name" type="s"> + <tp:docstring> + <p>The suggested name of the content to add.</p> + + <tp:rationale> + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. + </tp:rationale> + + <p>If there is already a content with the same name as this + property then a sensible suffix should be added. For example, + if this argument is "audio" but a content of the same name + already exists, a sensible suffix such as " (1)" is appended + to name the new content "audio (1)". A further content with the + name "audio" would then be named "audio (2)".</p> + + </tp:docstring> + </arg> + <arg direction="in" name="Content_Type" type="u" + tp:type="Media_Stream_Type"> + <tp:docstring> + The media stream type of the content to be added to the + call. + </tp:docstring> + </arg> + <arg direction="out" name="Content" type="o"> + <tp:docstring> + Path to the newly-created <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Call.Content.DRAFT</tp:dbus-ref> object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The media stream type given is invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The media stream type requested is not implemented by the + CM. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The content type requested cannot be added to this + call. Examples of why this might be the case include + because a second video stream cannot be added, or a + content cannot be added when the content set isn't + mutable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="ContentAdded" + tp:name-for-bindings="Content_Added"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> is added to the call.</p> + </tp:docstring> + <arg name="Content" type="o"> + <tp:docstring> + Path to the newly-created <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> object. + </tp:docstring> + </arg> + </signal> + + <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> + </tp:docstring> + <arg name="Content" type="o"> + <tp:docstring> + The <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> which was removed. + </tp:docstring> + </arg> + </signal> + + <property name="Contents" type="ao" access="read" + tp:name-for-bindings="Contents"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that + are part of this call. Change notification is via the + <tp:member-ref>ContentAdded</tp:member-ref> and + <tp:member-ref>ContentRemoved</tp:member-ref> signals. + </p> + </tp:docstring> + </property> + + <tp:enum type="u" name="Call_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The state of a call, as a whole.</p> + + <p>The allowed transitions are:</p> + + <ul> + <li>Pending_Initiator → Pending_Receiver (for outgoing calls, + when <tp:member-ref>Accept</tp:member-ref> is called)</li> + <li>Pending_Receiver → Accepted (for incoming calls, when + <tp:member-ref>Accept</tp:member-ref> is called; for outgoing + calls to a contact, when the remote contact accepts the call; + for joining a conference call, when the local user successfully + joins the conference)</li> + <li>Accepted → Pending_Receiver (when transferred to another + contact)</li> + <li>any state → Ended (when the call is terminated normally, or + when an error occurs)</li> + </ul> + + <p>Clients MAY consider unknown values from this enum to be an + error - additional values will not be defined after the Call + specification is declared to be stable.</p> + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value = "0"> + <tp:docstring> + The call state is not known. This call state MUST NOT appear as a + value of the <tp:member-ref>CallState</tp:member-ref> property, but + MAY be used by client code to represent calls whose state is as yet + unknown. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Initiator" value = "1"> + <tp:docstring> + The initiator of the call hasn't accepted the call yet. This state + only makes sense for outgoing calls, where it means that the local + user has not yet sent any signalling messages to the remote user(s), + and will not do so until <tp:member-ref>Accept</tp:member-ref> is + called. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Receiver" value = "2"> + <tp:docstring> + The receiver (the contact being called) hasn't accepted the call yet. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Accepted" value = "3"> + <tp:docstring> + The contact being called has accepted the call. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Ended" value = "4"> + <tp:docstring> + The call has ended, either via normal termination or an error. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u"> + <tp:docstring> + A set of flags representing the status of the call as a whole, + providing more specific information than the + <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make + sense in a particular state. + </tp:docstring> + + <tp:flag suffix="Locally_Ringing" value="1"> + <tp:docstring> + The local contact has been alerted about the call but has not + responded; if possible, the remote contact(s) have been informed of + this fact. This flag only makes sense on incoming calls in + state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD + be set when <tp:member-ref>SetRinging</tp:member-ref> is + called successfully, and unset when the state changes. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Queued" value="2"> + <tp:docstring> + The contact is temporarily unavailable, and the call has been placed + in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). + This flag only makes sense on outgoing 1-1 calls in + state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be + set or unset according to informational messages from other + contacts. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Locally_Held" value="4"> + <tp:docstring> + The call has been put on hold by the local user, e.g. using + the <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Hold</tp:dbus-ref> interface. This flag SHOULD only be set + if there is at least one Content, and all Contents are + locally held; it makes sense on calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver + or <tp:type>Call_State</tp:type>_Accepted. + + <tp:rationale> + Otherwise, in transient situations where some but not all contents + are on hold, UIs would falsely indicate that the call as a whole + is on hold, which could lead to the user saying something they'll + regret, while under the impression that the other contacts can't + hear them! + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Forwarded" value="8"> + <tp:docstring> + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. This flag only makes sense on outgoing calls, in state + <tp:type>Call_State</tp:type>_Pending_Receiver or + <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset + according to informational messages from other contacts. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="In_Progress" value="16"> + <tp:docstring> + Progress has been made in placing the outgoing call, but the + contact may not have been made aware of the call yet + (so the Ringing state is not appropriate). This corresponds to SIP's + status code 183 Session Progress, and could be used when the + outgoing call has reached a gateway, for instance. + This flag only makes sense on outgoing calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set + or unset according to informational messages from servers, gateways + and other infrastructure. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Clearing" value="32"> + <tp:docstring> + This flag only occurs when the CallState is Ended. The call with + this flag set has ended, but not all resources corresponding to the + call have been freed yet. + + Depending on the protocol there might be some audible feedback while + the clearing flag is set. + + <tp:rationale> + In calls following the ITU-T Q.931 standard there is a period of + time between the call ending and the underlying channel being + completely free for re-use. + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Muted" value="64"> + <tp:docstring> + The call has been muted by the local user, e.g. using the + <tp:dbus-ref namespace="ofdT.Call.Content.Interface" + >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only + be set if there is at least one Content, and all Contents + are locally muted; it makes sense on calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver or + <tp:type>Call_State</tp:type>_Accepted. + </tp:docstring> + </tp:flag> + </tp:flags> + + <property name="CallStateDetails" + tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map used to provide optional extensible details for the + <tp:member-ref>CallState</tp:member-ref>, + <tp:member-ref>CallFlags</tp:member-ref> and/or + <tp:member-ref>CallStateReason</tp:member-ref>.</p> + + <p>Well-known keys and their corresponding value types include:</p> + + <dl> + <dt>hangup-message - s</dt> + <dd>An optional human-readable message sent when the call was ended, + corresponding to the Message argument to the + <tp:member-ref>Hangup</tp:member-ref> method. This is only + applicable when the call state is <tp:type>Call_State</tp:type>_Ended. + <tp:rationale> + XMPP Jingle can send such messages. + </tp:rationale> + </dd> + + <dt>queue-message - s</dt> + <dd>An optional human-readable message sent when the local contact + is being held in a queue. This is only applicable when + <tp:type>Call_Flags</tp:type>_Queued is in the call flags. + <tp:rationale> + SIP 182 notifications can have human-readable messages attached. + </tp:rationale> + </dd> + + <dt>debug-message - s</dt> + <dd>A message giving further details of any error indicated by the + <tp:member-ref>CallStateReason</tp:member-ref>. This will not + normally be localized or suitable for display to users, and is only + applicable when the call state is + <tp:type>Call_State</tp:type>_Ended.</dd> + </dl> + </tp:docstring> + </property> + + <property name="CallState" type="u" access="read" + tp:name-for-bindings="Call_State" tp:type="Call_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The current high-level state of this call. The + <tp:member-ref>CallFlags</tp:member-ref> provide additional + information, and the <tp:member-ref>CallStateReason</tp:member-ref> + and <tp:member-ref>CallStateDetails</tp:member-ref> explain the + reason for the current values for those properties.</p> + + <p>Note that when in a conference call, this property is + purely to show your state in joining the call. The receiver + (or remote contact) in this context is the conference server + itself. The property does not change when other call members' + states change.</p> + + <p>Clients MAY consider unknown values in this property to be an + error.</p> + </tp:docstring> + </property> + + <property name="CallFlags" type="u" access="read" + tp:name-for-bindings="Call_Flags" tp:type="Call_Flags"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Flags representing the status of the call as a whole, + providing more specific information than the + <tp:member-ref>CallState</tp:member-ref>.</p> + + <p>Clients are expected to ignore unknown flags in this property, + without error.</p> + + <p>When an ongoing call is active and not on hold or has any + other problems, this property will be 0.</p> + </tp:docstring> + </property> + + <tp:enum name="Call_State_Change_Reason" type="u"> + <tp:docstring> + A simple representation of the reason for a change in the call's + state, which may be used by simple clients, or used as a fallback + when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type> + struct is not understood. + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="User_Requested" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change was requested by the contact indicated by the Actor + member of a <tp:type>Call_State_Reason</tp:type> struct.</p> + + <p>If the Actor is the local user, the DBus_Reason SHOULD be the + empty string.</p> + + <p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty + string if the call was terminated normally, but MAY be a non-empty + error name to indicate error-like call termination reasons (call + rejected as busy, kicked from a conference by a moderator, etc.).</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Forwarded" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The call was forwarded. If known, the handle of the contact + the call was forwarded to will be indicated by the Actor member + of a <tp:type>Call_State_Reason</tp:type> struct.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="No_Answer" value="3"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed from + <tp:type>Call_State</tp:type>_Pending_Receiver to + <tp:type>Call_State</tp:type>_Ended because the initiator + ended the call before the receiver accepted it. With an + incoming call this state change reason signifies a missed + call.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Call_State_Reason"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A description of the reason for a change to the + <tp:member-ref>CallState</tp:member-ref> and/or + <tp:member-ref>CallFlags</tp:member-ref>.</p> + </tp:docstring> + + <tp:member type="u" tp:type="Contact_Handle" name="Actor"> + <tp:docstring> + The contact responsible for the change, or 0 if no contact was + responsible. + </tp:docstring> + </tp:member> + + <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason"> + <tp:docstring> + The reason, chosen from a limited set of possibilities defined by + the Telepathy specification. If + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then + the Actor member will dictate whether it was the local user or + a remote contact responsible. + </tp:docstring> + </tp:member> + + <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specific reason for the change, which may be a D-Bus error in + the Telepathy namespace, a D-Bus error in any other namespace + (for implementation-specific errors), or the empty string to + indicate that the state change was not an error.</p> + + <p>This SHOULD be an empty string for changes to any state other + than Ended.</p> + + <p>The errors Cancelled and Terminated SHOULD NOT be used here; + an empty string SHOULD be used instead.</p> + + <tp:rationale> + <p>Those error names are used to indicate normal call + termination by the local user or another user, respectively, + in contexts where a D-Bus error name must appear.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason" + type="(uus)" access="read" tp:type="Call_State_Reason"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for the last change to the + <tp:member-ref>CallState</tp:member-ref> and/or + <tp:member-ref>CallFlags</tp:member-ref>. The + <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional + information.</p> + </tp:docstring> + </property> + + <signal name="CallStateChanged" + tp:name-for-bindings="Call_State_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the state of the call as a whole changes.</p> + + <p>This signal is emitted for any change in the properties + corresponding to its arguments, even if the other properties + referenced remain unchanged.</p> + </tp:docstring> + + <arg name="Call_State" type="u" tp:type="Call_State"> + <tp:docstring> + The new value of the <tp:member-ref>CallState</tp:member-ref> + property. + </tp:docstring> + </arg> + + <arg name="Call_Flags" type="u" tp:type="Call_Flags"> + <tp:docstring> + The new value of the <tp:member-ref>CallFlags</tp:member-ref> + property. + </tp:docstring> + </arg> + + <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason"> + <tp:docstring> + The new value of the <tp:member-ref>CallStateReason</tp:member-ref> + property. + </tp:docstring> + </arg> + + <arg name="Call_State_Details" type="a{sv}"> + <tp:docstring> + The new value of the <tp:member-ref>CallStateDetails</tp:member-ref> + property. + </tp:docstring> + </arg> + </signal> + + <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this property is True, all of the media streaming is done by some + mechanism outside the scope of Telepathy.</p> + + <tp:rationale> + <p>A connection manager might be intended for a specialized hardware + device, which will take care of the audio streaming (e.g. + telepathy-yafono, which uses GSM hardware which does the actual + audio streaming for the call).</p> + </tp:rationale> + + <p>If this is False, the handler is responsible for doing the actual + media streaming for at least some contents itself. Those contents + will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface" + >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary + information to a streaming implementation. Connection managers SHOULD + operate like this, if possible.</p> + + <tp:rationale> + <p>Many connection managers (such as telepathy-gabble) only do the + call signalling, and expect the client to do the actual streaming + using something like + <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve + latency and allow better UI integration.</p> + </tp:rationale> + </tp:docstring> + </property> + + <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A set of flags representing the status of a remote contact in a + call.</p> + + <p>It is protocol- and client-specific whether a particular contact + will ever have a particular flag set on them, and Telepathy clients + SHOULD NOT assume that a flag will ever be set.</p> + + <tp:rationale> + <p>180 Ringing in SIP, and its equivalent in XMPP, are optional + informational messages, and implementations are not required + to send them. The same applies to the messages used to indicate + hold state.</p> + </tp:rationale> + </tp:docstring> + + <tp:flag suffix="Ringing" value = "1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The remote contact's client has told us that the contact has been + alerted about the call but has not responded.</p> + + <tp:rationale> + <p>This is a flag per member, not a flag for the call as a whole, + because in Muji conference calls, you could invite someone and + have their state be "ringing" for a while.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Held" value = "2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The call member has put this call on hold.</p> + + <tp:rationale> + <p>This is a flag per member, not a flag for the call as a whole, + because in conference calls, any member could put the conference + on hold.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Conference_Host" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List"> + <tp:docstring>A mapping from handles to their current state in the call. + </tp:docstring> + <tp:member type="u" tp:type="Handle" name="key"/> + <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/> + </tp:mapping> + + <signal name="CallMembersChanged" + tp:name-for-bindings="Call_Members_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property + changes in any way, either because contacts have been added to the + call, contacts have been removed from the call, or contacts' flags + have changed. + </tp:docstring> + + <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map"> + <tp:docstring> + A map from members of the call to their new call member flags, + including at least the members who have been added to + <tp:member-ref>CallMembers</tp:member-ref>, and the members whose + flags have changed. + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of members who have left the call, i.e. keys to be removed + from <tp:member-ref>CallMembers</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <property name="CallMembers" tp:name-for-bindings="Call_Members" + type="a{uu}" access="read" tp:type="Call_Member_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping from the remote contacts that are part of this call to flags + describing their status. This mapping never has the local user's handle + as a key.</p> + + <p>When the call ends, this property should be an empty list, + and notified with + <tp:member-ref>CallMembersChanged</tp:member-ref></p> + + <p>If the Call implements + <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Group</tp:dbus-ref> and the Group members are + channel-specific handles, then this call SHOULD also use + channel-specific handles.</p> + + <p>Anonymous members are exposed as channel-specific handles + with no owner.</p> + </tp:docstring> + </property> + + <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" + type="u" tp:type="Stream_Transport_Type" access="read" + tp:requestable="yes" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If set on a requested channel, this indicates the transport that + should be used for this call. Where not applicable, this property + is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown, + in particular, on CMs with hardware streaming.</p> + + <tp:rationale> + When implementing a voip gateway one wants the outgoing leg of the + gatewayed to have the same transport as the incoming leg. This + property allows the gateway to request a Call with the right + transport from the CM. + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" + type="b" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If set to True in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.</p> + + <p>If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.</p> + + <p>If True on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.</p> + + <p>If True on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + <tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT" + >Contents</tp:dbus-ref>).</p> + + <p>The name of this new content can be decided by using the + <tp:member-ref>InitialAudioName</tp:member-ref> property.</p> + + <p>Connection managers that support the <tp:dbus-ref + namespace="ofdT.Connection.Interface">ContactCapabilities</tp:dbus-ref> + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = Call + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.</p> + </tp:rationale> + + <p>Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling <tp:dbus-ref + namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> + (clients of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their <tp:dbus-ref + namespace="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + properties):</p> + + <ul> + <li>{ ChannelType = Call }</li> + <li>{ ChannelType = Call, InitialAudio = True } + if receiving calls with audio is supported</li> + <li>{ ChannelType = Call, InitialVideo = True } + if receiving calls with video is supported</li> + </ul> + + <tp:rationale> + <p>Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialVideo" tp:name-for-bindings="Initial_Video" + type="b" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for + a video stream. This property is immutable (cannot change).</p> + + <p>In particular, note that if this property is False, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.</p> + + <p>This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.</p> + </tp:docstring> + </property> + + <property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name" + type="s" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to + True, then this property will name the intial audio content + with the value of this property.</p> + + <tp:rationale> + <p>Content names are meant to be significant, but if no name + can be given to initial audio content, then its name cannot + be meaningful or even localized.</p> + </tp:rationale> + + <p>If this property is empty or missing from the channel + request and InitialAudio is True, then the CM must come up + with a sensible for the content, such as "audio".</p> + + <p>If the protocol has no concept of stream names then this + property will not show up in the allowed properties list of + the Requestable Channel Classes for call channels.</p> + </tp:docstring> + </property> + + <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name" + type="s" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as + <tp:member-ref>InitialAudioName</tp:member-ref>, but for a + video stream created by setting + <tp:member-ref>InitialVideo</tp:member-ref> to True. This + property is immutable and so cannot change.</p> + </tp:docstring> + </property> + + <property name="MutableContents" tp:name-for-bindings="Mutable_Contents" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If True, a stream of a different content type can be added + after the Channel has been requested </p> + + <p>If this property is missing, clients SHOULD assume that it is False, + and thus that the channel's streams cannot be changed once the call + has started.</p> + + <p>If this property isn't present in the "allowed" set in any of the + Call entries contact capabilities, then user interfaces MAY choose to + show a separate "call" option for each class of call.</p> + + <tp:rationale> + <p>For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + must be requested at the start of the call if video is desired. + User interfaces may use this pseudo-capability as a hint to + display separate "Audio call" and "Video call" buttons, rather + than a single "Call" button with the option to add and remove + video once the call has started for contacts without this flag. + </p> + </tp:rationale> + </tp:docstring> + </property> + + <tp:hct name="audio"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This client supports audio calls.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="video"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This client supports video calls.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="gtalk-p2p"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="ice"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="wlm-2009"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="shm"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p> + </tp:docstring> + </tp:hct> + + <tp:hct name="video/h264" is-family="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client supports media streaming with H264 (etc.).</p> + + <p>This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.</p> + + <tp:rationale> + <p>For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + <code>video/h264</code> on Call channels.</p> + </tp:rationale> + + <p>For example, a client could advertise support for audio and video + calls using Speex, Theora and H264 by having five handler capability + tokens in its <tp:dbus-ref + namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref> + property:</p> + + <ul> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li> + </ul> + + <p>Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.</p> + + <tp:rationale> + <p>This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.</p> + </tp:rationale> + </tp:docstring> + </tp:hct> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Contact_List.xml b/spec/Channel_Type_Contact_List.xml new file mode 100644 index 0000000..5a0d333 --- /dev/null +++ b/spec/Channel_Type_Contact_List.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.ContactList"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for representing a list of people on the server which is + not used for communication. This is intended for use with the interface + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> + for managing buddy lists and privacy lists + on the server. This channel type has no methods because all of the + functionality it represents is available via the group interface.</p> + + <p>There are currently two types of contact list: + HANDLE_TYPE_LIST is a "magic" server-defined list, and + HANDLE_TYPE_GROUP is a user-defined contact group.</p> + + <p>For server-defined lists like the subscribe list, singleton instances + of this channel type should be created by the connection manager at + connection time if the list exists on the server, or may be requested + by using the appropriate handle. These handles can be obtained using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_LIST and one of the + following identifiers:</p> + + <ul> + <li>subscribe - the group of contacts for whom you receive presence</li> + <li>publish - the group of contacts who may receive your presence</li> + <li>hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence</li> + <li>allow - a group of contacts who may send you messages</li> + <li>deny - a group of contacts who may not send you messages</li> + <li>stored - on protocols where the user's contacts are stored, this + contact list contains all stored contacts regardless of subscription + status.</li> + </ul> + + <p>A contact can be in several server-defined lists. All lists are optional + to implement. If <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> + for a particular contact list raises an error, this indicates that the + connection manager makes no particular statement about the list's contents; + clients MUST NOT consider this to be fatal.</p> + + <p>If a client wants to list all of a user's contacts, it is appropriate to + use the union of the subscribe, publish and stored lists, including the + local and remote pending members.</p> + + <p>For example in XMPP, contacts who have the subscription type "none", + "from", "to" and "both" can be respectively in the lists:</p> + + <ul> + <li>"none": stored</li> + <li>"from": stored and publish</li> + <li>"to": stored and subscribe</li> + <li>"both": stored, publish and subscribe</li> + </ul> + + <p>These contact list channels may not be closed.</p> + + <p>For user-defined contact groups, instances of this channel type should + be created by the connection manager at connection time for each group + that exists on the server. New, empty groups can be created by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_GROUP and with the + name set to the human-readable UTF-8 name of the group.</p> + + <p>User-defined groups may be deleted by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> on the + channel, but only if + the group is already empty. Closing a channel to a non-empty group is + not allowed; its members must be set to the empty set first.</p> + + <p>On some protocols (e.g. XMPP) empty groups are not represented on the + server, so disconnecting from the server and reconnecting might cause + empty groups to vanish.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml new file mode 100644 index 0000000..fefa77a --- /dev/null +++ b/spec/Channel_Type_Contact_Search.xml @@ -0,0 +1,462 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.19.10"> + as stable API. Changes from draft 2: + <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers + rather than handles; consequently, the values need not include + <tt>x-telepathy-identifier</tt>. + </tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for searching server-stored user directories. A new + channel should be requested by a client for each search attempt, and + closed when the search is completed or the required result has been + found. Channels of this type should have <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>None</code> (and hence <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and + <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref> + <code>""</code>). Requests for channels of this type need only + optionally specify the <tp:member-ref>Server</tp:member-ref> property + (if it is an allowed property in the connection's <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p> + + <p>Before searching, the + <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be + inspected to determine the valid search keys which can be provided to + the <tp:member-ref>Search</tp:member-ref> method. A search request is + then started by providing some of these terms to the Search method, and + the <tp:member-ref>SearchState</tp:member-ref> will change from + <code>Not_Started</code> to <code>In_Progress</code>. As results are + returned by the server, the + <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted + for each contact found; when the search is complete, the search state + will be set to <code>Completed</code>. If the search fails after Search + has been called, the state will change to <code>Failed</code>. A + running search can be cancelled by calling + <tp:member-ref>Stop</tp:member-ref>.</p> + + <p>If the protocol supports limiting the number of results returned by a + search and subsequently requesting more results, after + <tp:member-ref>Limit</tp:member-ref> results have been received the + search state will be set to <code>More_Available</code>. Clients may + call <tp:member-ref>More</tp:member-ref> to request another + <tp:member-ref>Limit</tp:member-ref> results. If allowed by the + connection manager, clients may specify the "page size" by specifying + <tp:member-ref>Limit</tp:member-ref> when calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + </p> + + <p>The client should call the channel's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + method when it is finished with the channel.</p> + + <p>Each channel can only be used for a single search; a new channel + should be requested for each subsequent search. Connection managers + MUST support multiple ContactSearch channels being open at once (even + to the same server, if applicable).</p> + + <p>It does not make sense to request this channel type using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>; + clients SHOULD request channels of this type using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref> + instead.</p> + + <tp:rationale> + <p>A contact search channel that is already in use for a different + search isn't useful.</p> + </tp:rationale> + </tp:docstring> + + <tp:enum name="Channel_Contact_Search_State" type="u"> + <tp:enumvalue suffix="Not_Started" value="0"> + <tp:docstring>The search has not started</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="In_Progress" value="1"> + <tp:docstring>The search is in progress</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="More_Available" value="2"> + <tp:docstring>The search has paused, but more results can be retrieved + by calling <tp:member-ref>More</tp:member-ref>.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Completed" value="3"> + <tp:docstring>The search has been completed</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Failed" value="4"> + <tp:docstring>The search has failed</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="SearchState" tp:name-for-bindings="Search_State" + access="read" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring> + The current state of this search channel object. Change notification + is via <tp:member-ref>SearchStateChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="SearchStateChanged" + tp:name-for-bindings="Search_State_Changed"> + <arg name="State" type="u" tp:type="Channel_Contact_Search_State"> + <tp:docstring>The new search state</tp:docstring> + </arg> + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + If the new state is <code>Failed</code>, the name of a D-Bus error + describing what went wrong. Otherwise, the empty string. + </tp:docstring> + </arg> + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about the state transition, which may + include the following well-known keys:</p> + + <dl> + <dt>debug-message (s)</dt> + <dd>Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + </dl> + + <tp:rationale> + <p>This argument allows for future extensions. For instance, + if moving to state <code>Failed</code> because the server + rejected one of our search terms, we could define a key + that indicates which terms were invalid.</p> + </tp:rationale> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property + changes. The implementation MUST NOT make transitions other than the + following:</p> + + <ul> + <li><code>Not_Started</code> → <code>In_Progress</code></li> + <li><code>In_Progress</code> → <code>More_Available</code></li> + <li><code>More_Available</code> → <code>In_Progress</code></li> + <li><code>In_Progress</code> → <code>Completed</code></li> + <li><code>In_Progress</code> → <code>Failed</code></li> + </ul> + </tp:docstring> + </signal> + + <tp:simple-type name="Contact_Search_Key" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Any of the following search keys, with the indicated result for + the search:</p> + + <dl> + <dt>The empty string</dt> + <dd>Search for the search term in some implementation-dependent + set of fields, using an implementation-dependent algorithm + (e.g. searching for each word mentioned) + <tp:rationale> + The "one big search box" approach to searching, as is familiar + from Google. The Sametime plugin to Pidgin appears to search in + this way. + </tp:rationale> + </dd> + + <dt>A <tp:type>VCard_Field</tp:type></dt> + <dd>Search for the search term in fields matching that name (for + instance, <code>nickname</code> would search nicknames, and + <code>tel</code> would search any available phone number, + regardless of its work/home/mobile/... status).</dd> + + <dt>A <tp:type>VCard_Field</tp:type> followed by + "<code>;</code>" and a + <tp:type>VCard_Type_Parameter</tp:type> of the form + "<code>type=...</code>"</dt> + <dd>Search for the search term in fields of that name and type + only (for instance, <code>tel;type=mobile</code>).</dd> + + <dt><code>x-telepathy-identifier</code></dt> + <dd>Search for contacts whose identifier in the IM protocol + matches the search term (e.g. contains it as a substring) + <tp:rationale> + Otherwise, starting a search by identifier would require the UI + to know the vCard field name corresponding to identifiers in + this protocol, which might be non-standard (like + <code>x-jabber</code>) or not exist at all. + </tp:rationale> + </dd> + + <dt><code>x-gender</code></dt> + <dd>For the search term "male" or "female", search only for contacts + listed as male or female, respectively. The results for other + search terms are undefined; it is likely that contacts with + unspecified gender will only be matched if this search key + is omitted from the request. + <tp:rationale> + Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu + also supports limiting search results by gender. + </tp:rationale> + </dd> + + <dt><code>x-n-family</code></dt> + <dd>Search for the search term in contacts' family names + (the first component of the vCard field <code>n</code>). + <tp:rationale> + Gadu-Gadu and TOC seem to support this mode of searching. + </tp:rationale> + </dd> + + <dt><code>x-n-given</code></dt> + <dd>Search for the search term in contacts' given names + (the second component of the vCard field <code>n</code>). + <tp:rationale> + As for <code>x-n-family</code>. + </tp:rationale> + </dd> + + <dt><code>x-online</code></dt> + <dd>For the search term "yes", search only for contacts who are + currently online. The results for other search terms are undefined. + <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale> + </dd> + + <dt><code>x-adr-locality</code></dt> + <dd>Search for the search term as a locality or city (the fourth + component of the vCard field <code>adr</code>). + <tp:rationale> + Gadu-Gadu and TOC appear to support this. + </tp:rationale> + </dd> + </dl> + </tp:docstring> + </tp:simple-type> + + <property name="Limit" type="u" access="read" tp:name-for-bindings="Limit" + tp:immutable='yes' tp:requestable='sometimes'> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If supported by the protocol, the maximum number of results that + should be returned, where <code>0</code> represents no limit. If the + protocol does not support limiting results, this should be + <code>0</code>.</p> + + <p>For example, if the terms passed to + <tp:member-ref>Search</tp:member-ref> match <i>Antonius</i>, + <i>Bridget</i> and <i>Charles</i> and this property is + <code>2</code>, the search service SHOULD only return <i>Antonius</i> + and <i>Bridget</i>.</p> + + <p>This property SHOULD be requestable if and only if the protocol + supports specifying a limit; implementations SHOULD use + <code>0</code> as the default if possible, or a protocol-specific + sensible default otherwise.</p> + </tp:docstring> + </property> + + <property name="AvailableSearchKeys" type="as" access="read" + tp:name-for-bindings="Available_Search_Keys" tp:immutable='yes'> + <tp:docstring> + The set of search keys supported by this channel. Example values + include [""] (for protocols where several address fields are + implicitly searched) or ["x-n-given", "x-n-family", "nickname", + "email"] (for XMPP XEP-0055, without extensibility via Data Forms). + + <tp:rationale> + It can be in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal for round-trip reduction. + </tp:rationale> + </tp:docstring> + </property> + + <tp:mapping name="Contact_Search_Map"> + <tp:docstring>A map from search keys to search terms.</tp:docstring> + <tp:member name="Key" type="s" tp:type="Contact_Search_Key"> + <tp:docstring> + The search key to match against + </tp:docstring> + </tp:member> + + <tp:member name="Term" type="s"> + <tp:docstring> + The term or terms to be searched for in the search key; depending on + the protocol and the server implementation, this may be matched by + exact or approximate equality, substring matching, word matching + or any other matching algorithm + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="Search" tp:name-for-bindings="Search"> + <arg direction="in" name="Terms" + type="a{ss}" tp:type="Contact_Search_Map"> + <tp:docstring> + A dictionary mapping search key names to the desired values + </tp:docstring> + </arg> + <tp:docstring> + Send a request to start a search for contacts on this connection. This + may only be called while the <tp:member-ref>SearchState</tp:member-ref> + is Not_Started; a valid search request will cause the + <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted + with the state In_Progress. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is no longer + Not_Started, so this method is no longer available. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The search terms included something this connection manager cannot + search for. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="More" tp:name-for-bindings="More"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Request that a search in <tp:member-ref>SearchState</tp:member-ref> + <code>More_Available</code> move back to state <code>In_Progress</code> + and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is not + <code>More_Available</code>. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Stop" tp:name-for-bindings="Stop"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Stop the current search. This may not be called while the + <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called + while the SearchState is In_Progress, + <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, + with the state Failed and the error + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> + + <p>Calling this method on a search in state Completed or Failed + succeeds, but has no effect.</p> + + <tp:rationale> + <p>Specifying Stop to succeed when the search has finished means that + clients who call Stop just before receiving + <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to + handle a useless error.</p> + </tp:rationale> + + <p>Depending on the protocol, the connection manager may not be + able to prevent the server from sending further results after this + method returns; if this is the case, it MUST ignore any further + results.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so + this method is not yet available. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:mapping name="Contact_Search_Result_Map"> + <tp:docstring>A map from contact identifier to search result, emitted in + the <tp:member-ref>SearchResultReceived</tp:member-ref> + signal.</tp:docstring> + + <tp:member name="Contact_Identifier" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The identifier of a contact matching the search terms. + + <tp:rationale> + This is an identifier rather than a handle in case we make handles + immortal; see <a + href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a> + and <a + href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347 + comment 5</a>. + </tp:rationale> + </tp:docstring> + </tp:member> + + <tp:member name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of fields representing information about this + contact, in the same format used in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo</tp:dbus-ref> + interface. It is possible that a separate call to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref> + would return more information than this signal provides.</p> + </tp:docstring> + </tp:member> + </tp:mapping> + + <signal name="SearchResultReceived" + tp:name-for-bindings="Search_Result_Received"> + <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map"> + <tp:docstring>A mapping from contact identifier to an array of fields + representing information about this contact.</tp:docstring> + </arg> + + <tp:docstring> + Emitted when a some search results are received from the server. + This signal can be fired arbitrarily many times so clients MUST NOT + assume they'll get only one signal. + </tp:docstring> + </signal> + + <property name="Server" tp:name-for-bindings="Server" + type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'> + <tp:docstring> + <p>For protocols which support searching for contacts on multiple + servers with different DNS names (like XMPP), the DNS name of the + server being searched by this channel, e.g. + "characters.shakespeare.lit". Otherwise, the empty string.</p> + + <tp:rationale> + <p>XEP 0055 defines a mechanism for XMPP clients to search services + of their choice for contacts, such as users.jabber.org (the "Jabber + User Directory").</p> + </tp:rationale> + + <p>This property SHOULD be requestable if and only if the + protocol supports querying multiple different servers; + implementations SHOULD use a sensible default if possible if this + property is not specified in a channel request.</p> + + <tp:rationale> + <p>This allows a client to perform searches on a protocol it knows + nothing about without requiring the user to guess a valid server's + hostname.</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml new file mode 100644 index 0000000..9615763 --- /dev/null +++ b/spec/Channel_Type_DBus_Tube.xml @@ -0,0 +1,189 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus + traffic.</p> + + <p>For each D-Bus tube, the connection manager listens on a D-Bus + server address, as detailed in the D-Bus specification. On this + address, it emulates a bus upon which each tube participant appears + as an endpoint.</p> + + <p>The objects and interfaces which are expected to exist on the + emulated bus depend on the well-known name; typically, either the + participant who initiated the tube is expected to export the same + objects/interfaces that would be exported by a service of that name + on a bus, or all participants are expected to export those + objects/interfaces.</p> + + <p>In a multi-user context (Handle_Type_Room) the tube behaves + like the D-Bus bus daemon, so participants can send each other + private messages, or can send broadcast messages which are + received by everyone in the tube (including themselves). + Each participant has a D-Bus unique name; connection managers + MUST prevent participants from sending messages with the wrong + sender unique name, and SHOULD attempt to avoid participants + receiving messages not intended for them.</p> + + <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like + a peer-to-peer D-Bus connection - arbitrary D-Bus messages with + any sender and/or destination can be sent by each participant, + and each participant receives all messages sent by the other + participant.</p> + + </tp:docstring> + + <method name="Offer" tp:name-for-bindings="Offer"> + <tp:docstring> + Offers a D-Bus tube providing the service specified. + </tp:docstring> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> + <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the connection manager applies to the D-Bus socket. + </tp:docstring> + </arg> + <arg direction="out" name="address" type="s"> + <tp:docstring> + The string describing the address of the private bus. The client + SHOULD NOT attempt to connect to the address until the tube is open. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact associated with this channel doesn't have tubes + capabilities. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Accept" tp:name-for-bindings="Accept"> + <tp:docstring> + Accept a D-Bus tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref> + signal is emitted. + </tp:docstring> + <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the connection manager applies to the D-Bus socket. + </tp:docstring> + </arg> + <arg direction="out" name="address" type="s"> + <tp:docstring> + The string describing the address of the private bus. The client + SHOULD NOT attempt to connect to the address until the tube is open. + </tp:docstring> + </arg> + </method> + + <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed"> + <tp:docstring> + Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a + participant opens or closes the tube. This provides change + notification for the <tp:member-ref>DBusNames</tp:member-ref> property. + </tp:docstring> + <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants"> + <tp:docstring> + Array of handles and D-Bus names of new participants. + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + Array of handles of former participants. + </tp:docstring> + </arg> + </signal> + + <property name="ServiceName" type="s" access="read" + tp:name-for-bindings="Service_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string representing the service name that will be used over the + tube. It SHOULD be a well-known D-Bus service name, of the form + <tt>com.example.ServiceName</tt>.</p> + <p>When the tube is offered, the service name is transmitted to the + other end.</p> + <p>When requesting a channel with + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>, + this property MUST be included in the request.</p> + </tp:docstring> + </property> + + <property name="DBusNames" tp:name-for-bindings="DBus_Names" + access="read" type="a{us}" tp:type="DBus_Tube_Participants"> + <tp:docstring> + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping + between contact handles and their unique bus names on this tube. + For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty + dictionary. Change notification is via + <tp:member-ref>DBusNamesChanged</tp:member-ref>. + </tp:docstring> + </property> + + <tp:mapping name="DBus_Tube_Participants"> + <tp:docstring>Represents the participants in a multi-user D-Bus tube, as + used by the <tp:member-ref>DBusNames</tp:member-ref> property and the + <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The handle of a participant in this D-Bus tube. + </tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> + <tp:docstring> + That participant's unique name. + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="SupportedAccessControls" type="au" + tp:type="Socket_Access_Control[]" access="read" + tp:name-for-bindings="Supported_Access_Controls"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the access control types that are supported with this channel. + Note that only Socket_Access_Control_Localhost and + Socket_Access_Control_Credentials can be used with D-Bus tubes.</p> + + <p>When requesting a channel with + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, + this property MUST NOT be included in the request.</p> + + </tp:docstring> + </property> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml new file mode 100644 index 0000000..19dda06 --- /dev/null +++ b/spec/Channel_Type_File_Transfer.xml @@ -0,0 +1,531 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright © 2008-2009 Collabora Limited + </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.18">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for transferring files. The + transmission of data between contacts is achieved by reading from + or writing to a socket. The type of the socket (local Unix, IPv4, + etc.) is decided on when the file transfer is offered or accepted.</p> + + <p>A socket approach is used to make the transfer less dependent on both + client and connection manager knowing the same protocols. As an example, + when browsing an SMB share in a file manager, one selects "Send file" + and chooses a contact. Instead of passing a URL which would then require + the connection manager to connect to the SMB share itself, the client + passes a stream from which the connection manager reads, requiring no + further connection to the share. It also allows connection managers to + be more restricted in their access to the system, allowing tighter + security policies with eg SELinux, or more flexible deployments which + cross user or system boundaries.</p> + + <p>The Telepathy client should connect to the socket or address that + the connection manager has set up and provided back to the clients + through the two methods.</p> + + <ul><li>In order to send a file, one should request a FileTransfer + channel for a contact, including at least the mandatory properties + (<tp:member-ref>Filename</tp:member-ref>, + <tp:member-ref>Size</tp:member-ref> and <tp:member-ref>ContentType</tp:member-ref>). + Then, one should + call <tp:member-ref>ProvideFile</tp:member-ref> to configure the socket that + will be used to transfer the file.</li> + + <li>In order to receive an incoming file transfer, one should call + <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state + changes to Open. When the receiver wants to resume a transfer, the Offset + argument should be should be set to a non-zero value when calling + <tp:member-ref>AcceptFile</tp:member-ref>.</li> + + <li>Once the offset has been negotiated, the + <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal + is emitted and the <tp:member-ref>InitialOffset</tp:member-ref> property + is defined. The <tp:member-ref>InitialOffsetDefined</tp:member-ref> + signal is emitted before channel becomes Open. + The receiver MUST check the value of + <tp:member-ref>InitialOffset</tp:member-ref> for a difference in offset + from the requested value in AcceptFile.</li> + + <li>When the state changes to Open, Clients can start the transfer of the + file using the offset previously announced. + </li></ul> + + <p>If something goes wrong with the transfer, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + should be called on the channel.</p> + + <p>The File channel type may be requested for handles of type + HANDLE_TYPE_CONTACT. If the channel is requested for any other + handle type then the behaviour is undefined.</p> + + <p>Connection managers SHOULD NOT advertise support for file transfer to + other contacts unless it has been indicated by a call to + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>. + </p> + <tp:rationale> + <p>People would send us files, and it would always fail. That would be silly.</p> + </tp:rationale> + </tp:docstring> + + <property name="State" type="u" tp:type="File_Transfer_State" + access="read" tp:name-for-bindings="State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The state of the file transfer as described by the + File_Transfer_State enum.</p> + </tp:docstring> + </property> + + <property name="ContentType" type="s" access="read" + tp:name-for-bindings="Content_Type"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The file's MIME type. This cannot change once the channel has + been created.</p> + + <p>This property is mandatory when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. Protocols which do not have a content-type property with file + transfers should set this value to application/octet-stream.</p> + </tp:docstring> + </property> + + <property name="Filename" type="s" access="read" + tp:name-for-bindings="Filename"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the file on the sender's side. This is therefore given + as a suggested filename for the receiver. This cannot change + once the channel has been created.</p> + + <p>This property should be the basename of the file being sent. For example, + if the sender sends the file /home/user/monkey.pdf then this property should + be set to monkey.pdf.</p> + + <p>This property is mandatory when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. This property cannot be empty and MUST be set to a sensible value.</p> + </tp:docstring> + </property> + + <property name="Size" type="t" access="read" + tp:name-for-bindings="Size"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The size of the file. If this property is set, then the file + transfer is guaranteed to be this size. This cannot change once + the channel has been created.</p> + + <p>When you are creating a channel with this property, its value + MUST be accurate and in bytes. However, when receiving a file, this + property still MUST be in bytes but might not be entirely accurate + to the byte.</p> + + <p>This property is mandatory when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. If this information isn't provided in the protocol, connection managers MUST set it + to UINT64_MAX.</p> + </tp:docstring> + </property> + + <property name="ContentHashType" type="u" tp:type="File_Hash_Type" + access="read" tp:name-for-bindings="Content_Hash_Type"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p> + + <p>This property is optional when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref> + property you MUST also include this property. If you omit this property from a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method call then its value will be assumed to be File_Hash_Type_None.</p> + + <p>For each supported hash type, implementations SHOULD include an entry + in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + with this property fixed to that hash type. If the protocol supports + offering a file without a content hash, implementations SHOULD list + this property in Allowed in a requestable channel class, mapping hash + types they don't understand to None. + </p> + </tp:docstring> + </property> + + <property name="ContentHash" type="s" access="read" + tp:name-for-bindings="Content_Hash"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Hash of the contents of the file transfer, of type described + in the value of the <tp:member-ref>ContentHashType</tp:member-ref> + property.</p> + + <p>This property is optional when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. Its value MUST correspond to the appropriate type of the + <tp:member-ref>ContentHashType</tp:member-ref> property. If the + ContentHashType property is not set, or set to File_Hash_Type_None, + then this property will not even be looked at.</p> + </tp:docstring> + </property> + + <property name="Description" type="s" access="read" + tp:name-for-bindings="Description"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Description of the file transfer. This cannot change once the + channel has been created.</p> + + <p>This property is optional when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. If this property was not provided by the remote party, connection managers MUST set it to + the empty string.</p> + </tp:docstring> + </property> + + <property name="Date" type="x" access="read" + tp:type="Unix_Timestamp64" tp:name-for-bindings="Date"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The last modification time of the file being transferred. This + cannot change once the channel has been created</p> + + <p>This property is optional when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method.</p> + </tp:docstring> + </property> + + <property name="AvailableSocketTypes" type="a{uau}" + tp:type="Supported_Socket_Map" access="read" + tp:name-for-bindings="Available_Socket_Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for sockets with that + address type. For simplicity, if a CM supports offering a + particular type of file transfer, it is assumed to support accepting + it. Connection Managers MUST support at least Socket_Address_Type_IPv4.</p> + + <p>A typical value for a host without IPv6 support:</p> + + <pre> + { + Socket_Address_Type_IPv4: + [Socket_Access_Control_Localhost, Socket_Access_Control_Port, + Socket_Access_Control_Netmask], + Socket_Address_Type_Unix: + [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] + } + </pre> + </tp:docstring> + </property> + + <property name="TransferredBytes" type="t" access="read" + tp:name-for-bindings="Transferred_Bytes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The number of bytes that have been transferred at the time of + requesting the property. This will be updated as the file transfer + continues.</p> + </tp:docstring> + </property> + + <property name="InitialOffset" type="t" access="read" + tp:name-for-bindings="Initial_Offset"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The offset in bytes from where the file should be sent. This MUST + be respected by both the receiver and the sender after the state + becomes Open, but before any data is sent or received. Until the + <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal + is emitted, this property is undefined.</p> + + <p>Before setting the <tp:member-ref>State</tp:member-ref> property to + Open, the connection manager MUST set the InitialOffset property, + possibly to 0.</p> + + <p>This property MUST NOT change after the state of the transfer has + changed to Open.</p> + </tp:docstring> + </property> + + <tp:enum name="File_Transfer_State" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + An invalid state type used as a null value. This value MUST NOT + appear in the State property. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending" value="1"> + <tp:docstring> + The file transfer is waiting to be accepted/closed by the receiver. + The receiver has to call <tp:member-ref>AcceptFile</tp:member-ref>, + then wait for the state to change to Open and check the offset value. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Accepted" value="2"> + <tp:docstring> + The receiver has accepted the transfer. The sender now has to + call <tp:member-ref>ProvideFile</tp:member-ref> to actually start the transfer. + The receiver should now wait for the state to change to Open + and check the offset value. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="3"> + <tp:docstring> + The file transfer is open for traffic. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Completed" value="4"> + <tp:docstring> + The file transfer has been completed successfully. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Cancelled" value="5"> + <tp:docstring> + The file transfer has been cancelled. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="File_Transfer_State_Change_Reason" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + No reason was specified. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Requested" value="1"> + <tp:docstring> + The change in state was requested. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Local_Stopped" value="2"> + <tp:docstring> + The file transfer was cancelled by the local user. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Stopped" value="3"> + <tp:docstring> + The file transfer was cancelled by the remote user. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Local_Error" value="4"> + <tp:docstring> + The file transfer was cancelled because of a local error. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Error" value="5"> + <tp:docstring> + The file transfer was cancelled because of a remote error. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="File_Hash_Type" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + No hash. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="MD5" value="1"> + <tp:docstring> + MD5 digest as a string of 32 ASCII hex digits. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="SHA1" value="2"> + <tp:docstring> + SHA1 digest as a string of ASCII hex digits. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="SHA256" value="3"> + <tp:docstring> + SHA256 digest as a string of ASCII hex digits. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="AcceptFile" tp:name-for-bindings="Accept_File"> + <tp:docstring> + Accept a file transfer that's in the Pending state. The file + transfer's state becomes Accepted after this method is called. + At this point the client can connect to the socket. CM MUST emit + <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change + the state to Open before writing to the socket. + Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case + its value differs from the offset that was specified as an argument + to AcceptFile. + </tp:docstring> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of address the connection manager should listen on. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The type of access control the connection manager should apply to + the socket. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control_Param" type="v"> + <tp:docstring> + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + </tp:docstring> + </arg> + <arg direction="in" name="Offset" type="t"> + <tp:docstring> + The desired offset in bytes where the file transfer should start. + The offset is taken from the beginning of the file. Specifying an + offset of zero will start the transfer from the beginning of the + file. The offset that is actually given in the + <tp:member-ref>InitialOffset</tp:member-ref> property can differ + from this argument where the requested offset is not supported. + (For example, some protocols do not support offsets at all so + the InitialOffset property will always be 0.) + </tp:docstring> + </arg> + <arg direction="out" name="Address" type="v"> + <tp:docstring> + The address on which the connection manager will listen for + connections for this file transfer. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The given address type or access-control mechanism is not supported. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:docstring> + Your address type, access control, access control parameter, + offset, or a combination of all four is invalid. + </tp:docstring> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The file transfer is not in the Pending state, there isn't + or there is a local error with acquiring a socket. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ProvideFile" tp:name-for-bindings="Provide_File"> + <tp:docstring> + Provide the file for an outgoing file transfer which has been offered. + Opens a socket that the client can use to provide a file to the connection manager. + The channel MUST have been requested, and will change state + to Open when this method is called if its state was Accepted. + </tp:docstring> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of address the connection manager should listen on. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The type of access control the connection manager should apply to + the socket. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control_Param" type="v"> + <tp:docstring> + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + </tp:docstring> + </arg> + <arg direction="out" name="Address" type="v"> + <tp:docstring> + The address on which the connection manager will listen for + connections for this file transfer. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The given address type or access-control mechanism is not supported. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:docstring> + Your address type, access control, access control parameter, or + a combination of all three is invalid. + </tp:docstring> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Channel is not an outgoing transfer, ProvideFile has already been called, + or there was a local error acquiring the socket. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="FileTransferStateChanged" + tp:name-for-bindings="File_Transfer_State_Changed"> + <tp:docstring> + Emitted when the state of a file transfer changes. + </tp:docstring> + <arg name="State" type="u" tp:type="File_Transfer_State"> + <tp:docstring> + The new state of the file transfer; see the File_Transfer_State enumeration. + </tp:docstring> + </arg> + <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason"> + <tp:docstring> + The reason for the state change; see the File_Transfer_State_Change_Reason + enumeration. + The value will always be File_Transfer_State_Change_Reason_None, except + when changing state to cancelled. + </tp:docstring> + </arg> + </signal> + + <signal name="TransferredBytesChanged" + tp:name-for-bindings="Transferred_Bytes_Changed"> + <tp:docstring> + Emitted when the number of transferred bytes changes. This will not be + signalled with every single byte change. Instead, the most frequent + this signal will be emitted is once a second. This should be + sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref> + property SHOULD NOT be polled. + </tp:docstring> + <arg name="Count" type="t"> + <tp:docstring> + The number of already transferred bytes. + </tp:docstring> + </arg> + </signal> + + <signal name="InitialOffsetDefined" + tp:name-for-bindings="Initial_Offset_Defined"> + <tp:docstring> + Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref> + property has been negotiated. This signal MUST be emitted before the channel + becomes Open and clients have to use this offset when transferring the + file. + </tp:docstring> + <arg name="InitialOffset" type="t"> + <tp:docstring> + The value of the <tp:member-ref>InitialOffset</tp:member-ref> property. + </tp:docstring> + </arg> + </signal> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml new file mode 100644 index 0000000..98f7458 --- /dev/null +++ b/spec/Channel_Type_Room_List.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.RoomList"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Room_Info" array-name="Room_Info_List"> + <tp:member type="u" tp:type="Room_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/> + </tp:struct> + + <property name="Server" tp:name-for-bindings="Server" + type="s" access="read"> + <tp:docstring> + <p>For protocols with a concept of chatrooms on multiple servers + with different DNS names (like XMPP), the DNS name of the server + whose rooms are listed by this channel, e.g. "conference.jabber.org". + Otherwise, the empty string.</p> + + <p>This property cannot change during the lifetime of the channel.</p> + </tp:docstring> + </property> + + <method name="GetListingRooms" tp:name-for-bindings="Get_Listing_Rooms"> + <arg direction="out" type="b" name="In_Progress"> + <tp:docstring> + A boolean indicating if room listing is in progress + </tp:docstring> + </arg> + <tp:docstring> + Check to see if there is already a room list request in progress + on this channel. + </tp:docstring> + </method> + + <signal name="GotRooms" tp:name-for-bindings="Got_Rooms"> + <arg name="Rooms" type="a(usa{sv})" tp:type="Room_Info[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs containing: + <ul> + <li>an integer room handle</li> + <li>a string representing the D-Bus interface name of the channel type</li> + <li>a dictionary mapping string keys to variant boxed information</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when information about rooms on the server becomes available. + The array contains the room handle (as can be passed to the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> + method with HANDLE_TYPE_ROOM), the channel + type, and a dictionary containing further information about the + room as available. The following well-known keys and types are + recommended for use where appropriate:</p> + + <dl> + <dt>handle-name (s)</dt> + <dd>The identifier of the room (as would be returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd> + + <dt>name (s)</dt> + <dd>The human-readable name of the room if different from the handle</dd> + + <dt>description (s)</dt> + <dd>A description of the room's overall purpose</dd> + + <dt>subject (s)</dt> + <dd>The current subject of conversation in the room (as would + be returned by getting the string part of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property)</dd> + + <dt>members (u)</dt> + <dd>The number of members in the room</dd> + + <dt>password (b)</dt> + <dd>True if the room requires a password to enter</dd> + + <dt>invite-only (b)</dt> + <dd>True if you cannot join the room, but must be invited</dd> + + <dt>room-id (s)</dt> + <dd>The human-readable identifier of a chat room (as would be + returned by getting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >RoomID</tp:dbus-ref> property)</dd> + + <dt>server (s)</dt> + <dd>The DNS name of the server hosting these channels (as would be + returned by getting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Server</tp:dbus-ref> property)</dd> + </dl> + </tp:docstring> + </signal> + <method name="ListRooms" tp:name-for-bindings="List_Rooms"> + <tp:docstring> + Request the list of rooms from the server. The + <tp:member-ref>ListingRooms</tp:member-ref> (True) signal should be + emitted when this request is being processed, + <tp:member-ref>GotRooms</tp:member-ref> when any room information is + received, and <tp:member-ref>ListingRooms</tp:member-ref> (False) when + the request is complete. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <method name="StopListing" tp:name-for-bindings="Stop_Listing"> + <tp:docstring> + Stop the room listing if it's in progress, but don't close the channel. + The <tp:member-ref>ListingRooms</tp:member-ref> (False) signal should + be emitted when the listing stops. + </tp:docstring> + </method> + <signal name="ListingRooms" tp:name-for-bindings="Listing_Rooms"> + <arg name="Listing" type="b"> + <tp:docstring>A boolean indicating if room listing is in progress</tp:docstring> + </arg> + <tp:docstring> + Emitted to indicate whether or not room listing request is currently + in progress. + </tp:docstring> + </signal> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for listing named channels available on the server. Once the + <tp:member-ref>ListRooms</tp:member-ref> method is called, it emits signals for rooms present on the + server, until you <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> this + channel. In some cases, it may not be possible + to stop the deluge of information from the server. This channel should be + closed when the room information is no longer being displayed, so that the + room handles can be freed.</p> + + <p>This channel type may be implemented as a singleton on some protocols, so + clients should be prepared for the eventuality that they are given a + channel that is already in the middle of listing channels. The + <tp:member-ref>ListingRooms</tp:member-ref> signal, or + <tp:member-ref>GetListingRooms</tp:member-ref> method, can be used to check + this.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Server_Authentication.xml b/spec/Channel_Type_Server_Authentication.xml new file mode 100644 index 0000000..76599aa --- /dev/null +++ b/spec/Channel_Type_Server_Authentication.xml @@ -0,0 +1,121 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Server_Authentication" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.ServerAuthentication"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type for a channel representing an authentication step with the + server. The actual authentication functionality is implemented by + the additional interface named in + <tp:member-ref>AuthenticationMethod</tp:member-ref>, + such as <tp:dbus-ref namespace="ofdT" + >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> + + <p>Future authentication steps also supported by this channel type might + include solving a captcha and/or agreeing to an EULA or terms-of-use + document; each of these would be represented by a channel with this + type, but a different + <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p> + + <p>Channels of this type will normally be be signalled and dispatched + while the <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref> + owning them is in the CONNECTING state. They MAY also appear on a + Connection in the CONNECTED state, for instance if periodic + re-authentication is required.</p> + + <p>Normally, only one channel of this type will + exist on a given Connection; if there is more than one, the handler + must complete authentication with each of them in turn.</p> + + <p>Channels of this type cannot be requested with methods such as + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + They always have <tp:dbus-ref + namespace="ofdT.Channel">Requested</tp:dbus-ref> = False, + <tp:dbus-ref + namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> = None + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + = 0.</p> + + <p>While it is CONNECTING, the Connection MUST NOT proceed with + connection, or signal + <tp:dbus-ref namespace="ofdT.Connection">StatusChanged</tp:dbus-ref> + to the CONNECTED state, until each channel of this type has either + been accepted as having a positive result (for instance, on SASL + channels this is done with the <tp:dbus-ref + namespace="ofdT.Channel.Interface.SASLAuthentication" + >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref + namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p> + + <tp:rationale> + <p>ServerAuthentication channels normally represent the client + authenticating itself to the server, but can also be used for the + server to authenticate itself to the client (i.e. prove that it is + in fact the desired server and not an imposter). Until the + authentication handler has confirmed this, connection should not + continue.</p> + </tp:rationale> + + <p>If a channel of this type is closed with the <tp:dbus-ref + namespace="ofdT.Channel">Close</tp:dbus-ref> method before + authentication has succeeded, this indicates that the Handler has + given up its attempts to authenticate or that no Handler is + available.</p> + + <p>If this occurs, the connection manager MAY attempt to continue + connection (for instance, performing SASL authentication by using any + credentials passed to <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>, + for instance from the <tp:dbus-ref + namespace="ofdT">Account.Parameters</tp:dbus-ref>). If this fails + or has already been tried, the <tp:dbus-ref + namespace="ofdT">Connection</tp:dbus-ref> will + disconnect.</p> + + <tp:rationale> + <p>In particular, the <tp:dbus-ref + namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will close the + channel if it cannot find a handler.</p> + </tp:rationale> + + <p>When the connection is done with the channel and it is no + longer needed, it is left open until either the connection state + turns to DISCONNECTED or the handler closes the channel. The + channel SHOULD NOT close itself once finished with.</p> + </tp:docstring> + + <property name="AuthenticationMethod" + tp:name-for-bindings="Authentication_Method" + type="s" tp:type="DBus_Interface" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This property defines the method used for the authentication step + represented by this channel, which MUST be one of this channel's + <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref>.</p> + + <p>The initially-defined interface that can be used here is + <tp:dbus-ref namespace="ofdT" + >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml new file mode 100644 index 0000000..1f3348e --- /dev/null +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -0,0 +1,69 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Server_TLS_Connection" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection"> + <tp:added version="0.19.13">(as stable API)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type that carries a TLS certificate between a server + and a client connecting to it.</p> + <p>Channels of this kind always have <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + = 0, and cannot be requested with methods such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + Also, they SHOULD be dispatched while the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + owning them is in the CONNECTING state.</p> + <p>In this case, handlers SHOULD accept or reject the certificate, using + the relevant methods on the provided object, or MAY just <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall + back to a non-interactive verification process done inside the CM.</p> + <p>For example, channels of this kind can pop up while a client is + connecting to an XMPP server.</p> + </tp:docstring> + + <property name="ServerCertificate" type="o" access="read" + tp:name-for-bindings="Server_Certificate"> + <tp:docstring> + <p>A <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref> + containing the certificate chain as sent by the server, + and other relevant information.</p> + <p>This property is immutable.</p> + </tp:docstring> + </property> + + <property name="Hostname" type="s" access="read" + tp:name-for-bindings="Hostname"> + <tp:added version="0.19.12"/> + <tp:docstring> + The hostname of the server we expect <tp:member-ref>ServerCertificate</tp:member-ref> + to certify; clients SHOULD verify <tp:member-ref>ServerCertificate</tp:member-ref> against + this hostname when checking its validity. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml new file mode 100644 index 0000000..63e7b2f --- /dev/null +++ b/spec/Channel_Type_Stream_Tube.xml @@ -0,0 +1,292 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A stream tube is a transport for ordered, reliable data transfer, + similar to SOCK_STREAM sockets.</p> + + <p>When offering a stream tube, the initiating client creates a local + listening socket and offers it to the recipient client using the + <tp:member-ref>Offer</tp:member-ref> method. When a + recipient accepts a stream tube using the + <tp:member-ref>Accept</tp:member-ref> method, the + recipient's connection manager creates a new local listening socket. + Each time the recipient's client connects to this socket, the + initiator's connection manager proxies this connection to the + originally offered socket.</p> + + </tp:docstring> + + <method name="Offer" tp:name-for-bindings="Offer"> + <tp:docstring> + Offer a stream tube exporting the local socket specified. + </tp:docstring> + <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of the listening address of the local service, as a member of + Socket_Address_Type. + </tp:docstring> + </arg> + <arg direction="in" name="address" type="v"> + <tp:docstring> + The listening address of the local service, as indicated by the + address_type. + </tp:docstring> + </arg> + <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the local service applies to the local socket, + specified so the connection manager can behave appropriately + when it connects. + </tp:docstring> + </arg> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact associated with this channel doesn't have tube + capabilities. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The connection manager doesn't support the given address type + or access-control type. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Accept" tp:name-for-bindings="Accept"> + <tp:docstring> + Accept a stream tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref> + signal is emitted. + </tp:docstring> + <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of address the connection manager should listen on. + </tp:docstring> + </arg> + <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of access control the connection manager should apply to + the socket.</p> + + <p>Note that if you plan to establish more than one connection + through the tube, the Socket_Access_Control_Port access control + can't be used as you can't connect more than once from the same + port.</p> + </tp:docstring> + </arg> + <arg direction="in" name="access_control_param" type="v"> + <tp:docstring> + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + </tp:docstring> + </arg> + <arg direction="out" name="address" type="v"> + <tp:docstring> + The address on which the connection manager will listen for + connections to this tube. The client should not attempt to connect + to the address until the tube is open. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The access_control_param is invalid with the given access_control. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The given address type or access-control mechanism is not supported. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="NewRemoteConnection" + tp:name-for-bindings="New_Remote_Connection"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted each time a participant opens a new connection to its + socket.</p> + + <p>This signal is only fired on the offering side.</p> + </tp:docstring> + <arg name="Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the participant who opened the new connection + </tp:docstring> + </arg> + <arg name="Connection_Param" type="v"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A parameter which can be used by the listening process to identify + the connection. Note that this parameter has a meaningful value + only in the Socket_Access_Control_Port and + Socket_Access_Control_Credentials cases. If a different + Socket_Access_Control has been chosen when offering the tube, this + parameter should be ignored.</p> + + <p>In the Socket_Access_Control_Port case, the variant + contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the address from which the CM is connected to the client + application.</p> + + <p>In the Socket_Access_Control_Credentials case, the variant + contains the byte (D-Bus signature 'y') that has been sent with + the credentials.</p> + </tp:docstring> + </arg> + <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> + <tp:docstring> + The unique ID associated with this connection. This ID will be used + to identifiy the connection when reporting errors with + <tp:member-ref>ConnectionClosed</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="NewLocalConnection" + tp:name-for-bindings="New_Local_Connection"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the tube application connects to the CM's socket.</p> + + <p>This signal is only fired on the accepting side.</p> + </tp:docstring> + <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> + <tp:docstring> + The unique ID associated with this connection. This ID will be used + to identifiy the connection when reporting errors with + <tp:member-ref>ConnectionClosed</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="ConnectionClosed" + tp:name-for-bindings="Connection_Closed" + tp:type="Stream_Tube_Connection_Closed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a connection has been closed.</p> + </tp:docstring> + <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID"> + <tp:docstring> + The ID of the connection. + </tp:docstring> + </arg> + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error describing the error that occurred.</p> + + <p>The following errors can be used:</p> + <ul> + <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>: + user closed the socket or the tube.</li> + <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>: + the bytestream relaying connection's data has been broken.</li> + <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>: + the tube offer refused the connection.</li> + </ul> + </tp:docstring> + </arg> + <arg name="Message" type="s"> + <tp:docstring> + A debug message. + </tp:docstring> + </arg> + </signal> + + <property name="Service" type="s" access="read" + tp:name-for-bindings="Service"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> A string representing the service name that will be used over the + tube. It should be a well-known TCP service name as defined by + <a href="http://www.iana.org/assignments/port-numbers"> + http://www.iana.org/assignments/port-numbers</a> or + <a href="http://www.dns-sd.org/ServiceTypes.html"> + http://www.dns-sd.org/ServiceTypes.html</a>, for instance + "rsync" or "daap".</p> + <p>When the tube is offered, the service name is transmitted to the + other end.</p> + <p>When requesting a channel with + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, + this property MUST be included in the request.</p> + </tp:docstring> + </property> + + <property name="SupportedSocketTypes" type="a{uau}" + tp:type="Supported_Socket_Map" access="read" + tp:name-for-bindings="Supported_Socket_Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for stream tubes with that + address type. For simplicity, if a CM supports offering a + particular type of tube, it is assumed to support accepting it.</p> + + <p>A typical value for a host without IPv6 support:</p> + + <pre> + { + Socket_Address_Type_IPv4: + [Socket_Access_Control_Localhost, Socket_Access_Control_Port, + Socket_Access_Control_Netmask], + Socket_Address_Type_Unix: + [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] + } + </pre> + + <p>Connection Managers MUST support at least IPv4 with the localhost + access control.</p> + + <p>When requesting a channel with + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, + this property MUST NOT be included in the request.</p> + + </tp:docstring> + </property> + + <tp:simple-type name="Stream_Tube_Connection_ID" type="u"> + <tp:docstring>An identifier for a stream tube connection. + These are defined with the + <tp:member-ref>NewLocalConnection</tp:member-ref> or + <tp:member-ref>NewRemoteConnection</tp:member-ref> signals + and are used by <tp:member-ref>ConnectionClosed</tp:member-ref> + to identify the closed connection. + </tp:docstring> + </tp:simple-type> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml new file mode 100644 index 0000000..aa2b903 --- /dev/null +++ b/spec/Channel_Type_Streamed_Media.xml @@ -0,0 +1,853 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:enum name="Media_Stream_Type" type="u" + array-name="Media_Stream_Type_List"> + <tp:enumvalue suffix="Audio" value="0"> + <tp:docstring>An audio stream</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Video" value="1"> + <tp:docstring>A video stream</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Media_Stream_State" type="u"> + <tp:enumvalue suffix="Disconnected" value="0"> + <tp:docstring>The stream is disconnected.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connecting" value="1"> + <tp:docstring>The stream is trying to connect.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connected" value="2"> + <tp:docstring>The stream is connected.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Media_Stream_Direction" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring>Media are not being sent or received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Send" value="1"> + <tp:docstring>Media are being sent, but not received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Receive" value="2"> + <tp:docstring>Media are being received, but not sent</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Bidirectional" value="3"> + <tp:docstring>Media are being sent and received</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Media_Stream_Pending_Send" value-prefix="Media_Stream_Pending" type="u"> + <tp:flag suffix="Local_Send" value="1"> + <tp:docstring> + The local user has been asked to send media by the remote user. + Call <tp:member-ref>RequestStreamDirection</tp:member-ref> to + indicate whether or not this is acceptable. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Remote_Send" value="2"> + <tp:docstring> + The remote user has been asked to send media by the local user. + The <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal + will be emitted when the remote user accepts or rejects this + change. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> + <tp:member type="u" tp:type="Stream_ID" name="Identifier"/> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> + <tp:member type="u" tp:type="Media_Stream_State" name="State"/> + <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> + <tp:member type="u" tp:type="Media_Stream_Pending_Send" + name="Pending_Send_Flags"/> + </tp:struct> + + <tp:simple-type name="Stream_ID" type="u" + array-name="Stream_ID_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An unsigned integer identifying a stream within a channel.</p> + </tp:docstring> + </tp:simple-type> + + <method name="ListStreams" tp:name-for-bindings="List_Streams"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs containing: + <ul> + <li>the stream identifier</li> + <li>the contact handle who the stream is with (or 0 if the stream + represents more than a single member)</li> + <li>the type of the stream</li> + <li>the current stream state</li> + <li>the current direction of the stream</li> + <li>the current pending send flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of structs representing the streams currently active + within this channel. Each stream is identified by an unsigned integer + which is unique for each stream within the channel. + </tp:docstring> + </method> + + <method name="RemoveStreams" tp:name-for-bindings="Remove_Streams"> + <arg direction="in" name="Streams" type="au" tp:type="Stream_ID[]"> + <tp:docstring> + An array of stream identifiers (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given streams are removed. If all streams are + removed, the channel MAY close.</p> + + <p>Clients SHOULD NOT attempt to terminate calls by removing all the + streams; instead, clients SHOULD terminate calls by removing the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group.SelfHandle</tp:dbus-ref> + from the channel, using either + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>. + </p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream identifier is unknown + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreamDirection" + tp:name-for-bindings="Request_Stream_Direction"> + <arg direction="in" name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg direction="in" name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + The desired stream direction (a value of MediaStreamDirection) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request a change in the direction of an existing stream. In particular, + this might be useful to stop sending media of a particular type, + or inform the peer that you are no longer using media that is being + sent to you.</p> + + <p>Depending on the protocol, streams which are no longer sending in + either direction should be removed and a + <tp:member-ref>StreamRemoved</tp:member-ref> signal emitted. + Some direction changes can be enforced locally (for example, + BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending), + others may not be possible on some protocols, and some need agreement + from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND + flag will be set in the + <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal, and the + signal + emitted again without the flag to indicate the resulting direction when + the remote end has accepted or rejected the change.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream identifier is unknown + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested direction is not available on this stream + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreams" tp:name-for-bindings="Request_Streams"> + <arg direction="in" name="Contact_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle with whom to establish the streams + </tp:docstring> + </arg> + <arg direction="in" name="Types" type="au" tp:type="Media_Stream_Type[]"> + <tp:docstring> + An array of stream types (values of MediaStreamType) + </tp:docstring> + </arg> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs (in the same order as the given stream types) + containing: + <ul> + <li>the stream identifier</li> + <li>the contact handle who the stream is with (or 0 if the stream + represents more than a single member)</li> + <li>the type of the stream</li> + <li>the current stream state</li> + <li>the current direction of the stream</li> + <li>the current pending send flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that streams be established to exchange the given types of + media with the given member. In general this will try and establish a + bidirectional stream, but on some protocols it may not be possible to + indicate to the peer that you would like to receive media, so a + send-only stream will be created initially. In the cases where the + stream requires remote agreement (eg you wish to receive media from + them), the <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal + will be emitted with the + MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again + with the flag cleared when the remote end has replied.</p> + + <p>If streams of the requested types already exist, calling this + method results in the creation of additional streams. Accordingly, + clients wishing to have exactly one audio stream or exactly one + video stream SHOULD check for the current streams using + <tp:member-ref>ListStreams</tp:member-ref> before calling this + method.</p> + </tp:docstring> + <tp:changed version="0.17.2"> + <p>It is valid to use a handle which is neither + a current nor pending member in this channel's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + interface. If + so, that handle will be added to the remote-pending set only when + an attempt has actually been made to contact them. For further + call-state notification, use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref> + interface, if + supported. This usage was not allowed in spec versions below + 0.17.2.</p> + </tp:changed> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream type given is invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + A stream type given is not implemented by the connection manager. + Since 0.17.23, connection managers SHOULD raise this error + in preference to InvalidArgument. + <tp:rationale> + Connection managers can't know whether an unknown number + is a valid stream type that was introduced in a later spec + version. + </tp:rationale> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + That contact's client does not implement one of the given stream + types. For this method, clients SHOULD consider this error and + NotCapable to be equivalent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + That contact's client does not implement one of the given stream + types. Since 0.17.23, connection managers SHOULD raise + this in preference to NotAvailable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Contact_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact handle who the stream is with (or 0 if it + represents more than a single member) + </tp:docstring> + </arg> + <arg name="Stream_Type" type="u" tp:type="Media_Stream_Type"> + <tp:docstring> + The stream type (a value from MediaStreamType) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new stream has been added to this channel. + Clients SHOULD assume that the stream's + <tp:type>Media_Stream_State</tp:type> is initially Disconnected.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose state is already Connecting or Connected, it MUST do this + by emitting StreamAdded, closely followed by + <tp:member-ref>StreamStateChanged</tp:member-ref> indicating a + change to the appropriate state.</p> + + <tp:rationale> + <p>Historically, it was not clear from the StreamAdded signal what + the state of the stream was. telepathy-spec 0.17.22 + clarified this.</p> + </tp:rationale> + + <p>Similarly, clients SHOULD assume that the initial + <tp:type>Media_Stream_Direction</tp:type> of a newly added stream + is Receive, and that the initial + <tp:type>Media_Stream_Pending_Send</tp:type> is + Pending_Local_Send.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose direction or pending-send differs from those initial values, + it MUST do so by emitting StreamAdded, closely followed by + <tp:member-ref>StreamDirectionChanged</tp:member-ref> indicating a + change to the appropriate direction and pending-send state.</p> + + <tp:rationale> + <p>StreamAdded doesn't itself indicate the stream's direction; this + is unfortunate, but is preserved for compatibility.</p> + + <p>This is the appropriate direction for streams added by a remote + contact on existing connection managers, and does not violate + user privacy by automatically sending audio or video (audio streams + start off muted, video streams start off not sending). For + streams added by the local user using the client receiving the + signal, the true direction can also be determined from the return + value of the <tp:member-ref>RequestStreams</tp:member-ref> + method.</p> + + <p>Existing clients typically operate by maintaining a separate + idea of the directions that they would like the streams to have, + and enforcing these intended directions by calling + <tp:member-ref>RequestStreamDirection</tp:member-ref> whenever + needed.</p> + </tp:rationale> + </tp:docstring> + </signal> + + <signal name="StreamDirectionChanged" + tp:name-for-bindings="Stream_Direction_Changed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + The new stream direction (as defined in ListStreams) + </tp:docstring> + </arg> + <arg name="Pending_Flags" type="u" tp:type="Media_Stream_Pending_Send"> + <tp:docstring> + The new pending send flags (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the direction or pending flags of a stream are + changed.</p> + + <p>If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user + has requested that we begin sending on this stream. + <tp:member-ref>RequestStreamDirection</tp:member-ref> + should be called to indicate whether or not this change is + acceptable.</p> + + <tp:rationale> + <p>This allows for a MSN-style user interface, "Fred has asked you + to enable your webcam. (Accept | Reject)", if desired.</p> + </tp:rationale> + </tp:docstring> + </signal> + + <signal name="StreamError" tp:name-for-bindings="Stream_Error"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Error_Code" type="u" tp:type="Media_Stream_Error"> + <tp:docstring> + A stream error number, one of the values of MediaStreamError + </tp:docstring> + </arg> + <arg name="Message" type="s"> + <tp:docstring> + A string describing the error (for debugging purposes only) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a stream encounters an error. + </tp:docstring> + </signal> + + <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + stream_id - the stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a stream has been removed from this channel. + </tp:docstring> + </signal> + + <signal name="StreamStateChanged" + tp:name-for-bindings="Stream_State_Changed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Stream_State" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The new stream state (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a member's stream's state changes. + </tp:docstring> + </signal> + + <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If set to true in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p> + + <p>If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.</p> + + <p>If true on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.</p> + + <p>If true on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p> + + <p>This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signals.</p> + + <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale> + + <p>Connection managers capable of signalling audio calls to contacts + SHOULD include a channel class in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref> + = <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact in the fixed properties dictionary, and InitialAudio + (and also InitialVideo, if applicable) in the allowed properties + list. Clients wishing to discover whether a connection manager + can signal audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all protocols support signalling video calls, and it would be + possible (although unlikely) to have a protocol where only video, + and not audio, could be signalled.</p> + </tp:rationale> + + <p>Connection managers that support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = StreamedMedia + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.</p> + </tp:rationale> + + <p>Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> + (clients of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + properties):</p> + + <ul> + <li>{ ChannelType = StreamedMedia }</li> + <li>{ ChannelType = StreamedMedia, InitialAudio = true } + if receiving calls with audio is supported</li> + <li>{ ChannelType = StreamedMedia, InitialVideo = true } + if receiving calls with video is supported</li> + </ul> + + <tp:rationale> + <p>Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialVideo" tp:name-for-bindings="Initial_Video" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for + a video stream. This property is immutable (cannot change).</p> + + <p>In particular, note that if this property is false, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.</p> + + <p>This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.</p> + </tp:docstring> + </property> + + <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tt>True</tt>, once streams have been requested for this channel + (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or + <tp:member-ref>InitialVideo</tp:member-ref> when the channel is + requested, or by calling + <tp:member-ref>RequestStreams</tp:member-ref> on a channel with no + streams), a stream of a different content type cannot be added; + subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref> + that attempt to do so will fail.</p> + + <p>If this property is missing, clients SHOULD assume that it is false, + and thus that the channel's streams can be changed once the call has + started.</p> + + <p>If this property is present in the "allowed" set in all of the + StreamedMedia entries in a contact's capabilities, then user + interfaces MAY choose to show a separate "call" option for each + class of call.</p> + + <tp:rationale> + <p>For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + must be requested at the start of the call if video is desired. + User interfaces may use this pseudo-capability as a hint to + display separate "Audio call" and "Video call" buttons, rather + than a single "Call" button with the option to add and remove + video once the call has started for contacts without this flag. + </p> + </tp:rationale> + + <p>This property is immutable, and therefore SHOULD be announced + in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>, + etc.</p> + </tp:docstring> + </property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel that can send and receive streamed media such as audio or + video. Provides a number of methods for listing and requesting new + streams, and signals to indicate when streams have been added, removed + and changed status. The state of the call (ringing remotely, ringing + locally, answered, missed, etc.) are represented using the properties + and signals of the Group interface.</p> + + <p>In general this should be used in conjunction with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface to exchange connection candidates and codec choices with + whichever component is responsible for the streams. However, in certain + applications where no candidate exchange is necessary (eg the streams + are handled by specialised hardware which is controlled directly by the + connection manager), the signalling interface can be omitted and this + channel type used simply to control the streams.</p> + + <h4>Outgoing calls</h4> + + <p>To make an audio-only call to a contact <tt>foo@example.com</tt>, + clients should call:</p> + + <blockquote> + <pre> +<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Contact, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + <tp:member-ref>InitialAudio</tp:member-ref>: True, +)</pre></blockquote> + + <p>As always, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + may be used in place of TargetID if the contact's handle is already + known. To make an audio-and-video call, the client should also specify + <tp:member-ref>InitialVideo</tp:member-ref>. The connection manager + SHOULD return a channel whose immutable properties contain the local + user as the <tp:dbus-ref namespace='ofdT.Channel'>InitiatorHandle</tp:dbus-ref>, + the remote contact as the <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>True</code> + (indicating that the call is outgoing); the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Group</tp:dbus-ref> interface should + initially have the local user in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>Members</tp:dbus-ref> and the remote + contact in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>RemotePendingMembers</tp:dbus-ref>, to + indicate that we are awaiting their response.</p> + + <p>The contact answering the call is represented by the CM signalling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + moving the remote contact to Members, with the remote contact as the + <var>Actor</var> and <var>Reason</var> <code>None</code>. The contact + rejecting the call is represented by both contacts being removed from + the group, with the remote contact as the <var>Actor</var> and + <var>Reason</var> set appropriately. The local user may hang up at any + time by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove themself, with an appropriate reason; the CM SHOULD relay the + reason to the remote contact, and emit MembersChanged removing both + contacts from the group with the self handle as the <var>Actor</var>.</p> + + <p>(In the past, several other patterns have been used to place outgoing + calls; see + <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> + for the details.)</p> + + <h4>Incoming calls</h4> + + <p>Incoming calls' immutable properties should contain <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact, both <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">InitiatorHandle</tp:dbus-ref> + set to the remote contact, <tp:dbus-ref + namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>False</code> + (indicating that this is an incoming call), and appropriate values of + <tp:member-ref>InitialAudio</tp:member-ref> and + <tp:member-ref>InitialVideo</tp:member-ref>; the Group interface should + initially have the local user in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref> + and the remote contact in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">Members</tp:dbus-ref>, + indicating that the contact is awaiting our response.</p> + + <p>To accept the call, use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> + to move the local user to the group's members. To reject the call, use + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove the local member from the group, with an appropriate reason. + If the remote user ends the call before it is answered, this is + represented by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> + removing both parties from the group with the remote contact as the + <var>Actor</var>, and <var>Reason</var> set appropriately.</p> + + <p>Note that the call may end with the self handle as the + <var>Actor</var> without the user having chosen to reject the call, as + indicated by the nature of the <var>Reason</var>. Specifically, some + local component may time out the call (indicating this with reason + <code>No_Answer</code>; for example, the CM may have forwarded the call + to another number, as configured using <tp:dbus-ref + namespace='ofdT.Connection.Interface'>Forwarding.DRAFT</tp:dbus-ref>), + or something may have gone wrong with the call + (indicated by reason <code>Error</code>). Such calls SHOULD be + considered missed, just as if the remote contact had hung up before the + local user answered the call.</p> + + <tp:rationale> + <p>This is a bit awkward, but these are the best ways we can represent + these situations. It's important to document which calls should be + considered missed, to ensure that the user can be notified.</p> + </tp:rationale> + + <p>When the local user accepts an incoming call, the connection manager + SHOULD change the direction of any streams with pending local send + to be sending, without altering whether those streams are + receiving.</p> + + <tp:rationale> + <p>This matches existing practice, and means that a client + can answer incoming calls and get an unmuted microphone/activated + webcam without having to take additional action to accept the + stream directions.</p> + + <p>It does, however, introduce a race condition: a client believing + that it is accepting an audio-only call by calling AddMembers + can inadvertantly accept an audio + video call (and hence activate + sending from a webcam without the user's permission) if a video + stream is added just before AddMembers is processed. This race + should be removed when this specification is revised.</p> + </tp:rationale> + + <h4>During a call</h4> + + <p>If <tp:member-ref>ImmutableStreams</tp:member-ref> is + <code>False</code>, new streams may be requested using + <tp:member-ref>RequestStreams</tp:member-ref> (to add video to an + audio-only call, for instance), and existing streams may be removed using + <tp:member-ref>RemoveStreams</tp:member-ref> (for example, to downgrade + an audio-video call to audio-only). The call may be ended by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>; the call ending is signalled by the CM emitting <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + removing both parties from the group.</p> + + <h4>Handler filters</h4> + + <p>For historical reasons, handlers must specify more than one filter if + they want to correctly advertise support for audio and/or video calls. If + they can handle channels using the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface, they should also advertise various + <tp:type>Handler_Capability_Token</tp:type>s to indicate which codecs and + transports they support. See <tp:member-ref>InitialAudio</tp:member-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling/video/h264</tp:dbus-ref> + for the gory details. In summary:</p> + + <dl> + <dt>To advertise support for streamed media in general, include the + following filter in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, +}</pre></dd> + + <dt>To advertise support for audio calls, also include the following + filter:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, + '...Channel.Type.StreamedMedia.InitialAudio': True, +}</pre></dd> + + <dt>To advertise support for video calls, also include the following + filter:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, + '...Channel.Type.StreamedMedia.InitialVideo': True, +}</pre></dd> + + <dt>If you use telepathy-farsight, and have H.264 support, you probably + want these <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>:</dt> + <dd><pre> +[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp", + "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p", + "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264", +]</pre></dd> + </dl> + </tp:docstring> + + <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u"> + <tp:docstring> + The channel-type-specific capability flags used for + Channel.Type.StreamedMedia in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref> + interface. See the <tp:member-ref>InitialAudio</tp:member-ref> + property for details of the mechanisms that will replace this. + </tp:docstring> + <tp:flag suffix="Audio" value="1"> + <tp:docstring> + The handle is capable of using audio streams within a media channel. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Video" value="2"> + <tp:docstring> + The handle is capable of using video streams within a media channel. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_STUN" value="4"> + <tp:docstring> + The handle is capable of performing STUN to traverse NATs. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_GTalk_P2P" value="8"> + <tp:docstring> + The handle is capable of establishing Google Talk peer-to-peer + connections (as implemented in libjingle 0.3) to traverse NATs. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16"> + <tp:docstring> + The handle is capable of establishing ICE UDP peer-to-peer + connections (as defined by the IETF MMUSIC working group) to traverse + NATs. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Immutable_Streams" value="32"> + <tp:docstring> + Channels whose target handle is this contact will have + <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>. + </tp:docstring> + </tp:flag> + + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml new file mode 100644 index 0000000..0cd4d5b --- /dev/null +++ b/spec/Channel_Type_Text.xml @@ -0,0 +1,669 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> + <tp:changed version="0.21.5">The Messages interface is now + mandatory</tp:changed> + + <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List"> + <tp:docstring> + A unique-per-channel identifier for an incoming message. These + SHOULD be allocated in a way that minimizes collisions (in particular, + message IDs SHOULD NOT be re-used until all of the 32-bit integer + space has already been used). + </tp:docstring> + </tp:simple-type> + + <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> + <tp:deprecated version="0.21.5">New APIs should use + an array of <tp:type>Message_Part</tp:type> instead.</tp:deprecated> + <tp:docstring>A struct (message ID, timestamp in seconds since + 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) + representing a pending text message, as returned by + <tp:member-ref>ListPendingMessages</tp:member-ref>. The arguments of + the <tp:member-ref>Received</tp:member-ref> signal also match this + struct's signature.</tp:docstring> + <tp:member type="u" tp:type="Message_ID" name="Identifier"/> + <tp:member type="u" tp:type="Unix_Timestamp" name="Unix_Timestamp"/> + <tp:member type="u" tp:type="Contact_Handle" name="Sender"/> + <tp:member type="u" tp:type="Channel_Text_Message_Type" + name="Message_Type"/> + <tp:member type="u" tp:type="Channel_Text_Message_Flags" name="Flags"/> + <tp:member type="s" name="Text"/> + </tp:struct> + + <method name="AcknowledgePendingMessages" + tp:name-for-bindings="Acknowledge_Pending_Messages"> + <arg direction="in" name="IDs" type="au" tp:type="Message_ID[]"> + <tp:docstring> + The IDs of the messages to acknowledge + </tp:docstring> + </arg> + <tp:docstring> + Inform the channel that you have handled messages by displaying them to + the user (or equivalent), so they can be removed from the pending queue. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A given message ID was not found, so no action was taken + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetMessageTypes" tp:name-for-bindings="Get_Message_Types"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageTypes</tp:dbus-ref> is preferred. + </tp:deprecated> + <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]" + name="Available_Types"> + <tp:docstring> + An array of integer message types (ChannelTextMessageType) + </tp:docstring> + </arg> + <tp:docstring> + Return an array indicating which types of message may be sent on this + channel. + </tp:docstring> + </method> + + <method name="ListPendingMessages" + tp:name-for-bindings="List_Pending_Messages"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> is preferred. + </tp:deprecated> + <arg direction="in" name="Clear" type="b"> + <tp:docstring> + If true, behave as if + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also + been called. + </tp:docstring> + <tp:deprecated version="0.17.3"> + Setting this to true is NOT RECOMMENDED for clients that + have some sort of persistent message storage - clients SHOULD only + acknowledge messages after they have actually stored them, which is + impossible if this flag is true.</tp:deprecated> + </arg> + <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]" + name="Pending_Messages"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs representing the pending queue. Each contains: + <ul> + <li>a numeric identifier</li> + <li>a Unix timestamp indicating when the message was received</li> + <li>the contact handle for the contact who sent the message</li> + <li>the message type, taken from ChannelTextMessageType</li> + <li>the bitwise-OR of the message flags from ChannelTextMessageFlags</li> + <li>the text of the message</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + List the messages currently in the pending queue, and optionally + remove then all. + </tp:docstring> + </method> + + <signal name="LostMessage" tp:name-for-bindings="Lost_Message"> + <tp:deprecated version="0.21.5">In practice, this signal + was not emitted, and does not have useful semantics.</tp:deprecated> + <tp:docstring> + This signal is emitted to indicate that an incoming message was + not able to be stored and forwarded by the connection manager + due to lack of memory. + </tp:docstring> + </signal> + + <signal name="Received" tp:name-for-bindings="Received"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal is more informative. + </tp:deprecated> + <arg name="ID" type="u"> + <tp:docstring> + A numeric identifier for acknowledging the message + </tp:docstring> + </arg> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A Unix timestamp indicating when the message was received + </tp:docstring> + </arg> + <arg name="Sender" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the contact who sent the message + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The type of the message (normal, action, notice, etc.) + </tp:docstring> + </arg> + <arg name="Flags" type="u" tp:type="Channel_Text_Message_Flags"> + <tp:docstring> + A bitwise OR of the message flags + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + The text of the message + </tp:docstring> + </arg> + <tp:docstring> + Signals that a message with the given id, timestamp, sender, type + and text has been received on this channel. Applications that catch + this signal and reliably inform the user of the message should + acknowledge that they have dealt with the message with the + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method. + </tp:docstring> + </signal> + + <method name="Send" tp:name-for-bindings="Send"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> method is more flexible. + </tp:deprecated> + <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + An integer indicating the type of the message + </tp:docstring> + </arg> + <arg direction="in" name="Text" type="s"> + <tp:docstring> + The message to send + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that a message be sent on this channel. When the message has + been submitted for delivery, this method will return and the + <tp:member-ref>Sent</tp:member-ref> signal will be emitted. If the + message cannot be submitted for delivery, the method returns an error + and no signal is emitted.</p> + + <p>This method SHOULD return before the Sent signal is + emitted.</p> + + <tp:rationale> + <p>When a Text channel implements the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface, that "SHOULD" becomes a "MUST".</p> + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:enum name="Channel_Text_Send_Error" type="u"> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + An unknown error occurred + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring> + The requested contact was offline + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invalid_Contact" value="2"> + <tp:docstring> + The requested contact is not valid + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Permission_Denied" value="3"> + <tp:docstring> + The user does not have permission to speak on this channel + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Too_Long" value="4"> + <tp:docstring> + The outgoing message was too long and was rejected by the server + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Implemented" value="5"> + <tp:docstring> + The channel doesn't support sending text messages to the requested + contact + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="SendError" tp:name-for-bindings="Send_Error"> + <tp:deprecated version="0.21.5">Delivery reporting is now + provided by the <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface. + </tp:deprecated> + <arg name="Error" type="u" tp:type="Channel_Text_Send_Error"> + <tp:docstring> + The error that occurred + </tp:docstring> + </arg> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + The Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The message type + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + The text of the message + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that an outgoing message has failed to send. The error + will be one of the values from ChannelTextSendError.</p> + + <p>This signal should only be emitted for messages for which + <tp:member-ref>Sent</tp:member-ref> has already been emitted and + <tp:member-ref>Send</tp:member-ref> has already returned success.</p> + </tp:docstring> + <tp:changed version="0.17.3">older spec versions claimed that SendError + was emitted <em>instead of</em> Sent, rather than <em>in addition + to</em> Sent. However, the 0.17.3+ semantics were what we'd always + actually implemented.</tp:changed> + </signal> + + <signal name="Sent" tp:name-for-bindings="Sent"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageSent</tp:dbus-ref> signal is more informative. + </tp:deprecated> + <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + Unix timestamp indicating when the message was sent + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Channel_Text_Message_Type"> + <tp:docstring> + The message type (normal, action, notice, etc) from + ChannelTextMessageType + </tp:docstring> + </arg> + <arg name="Text" type="s"> + <tp:docstring> + The text of the message. If the message was, or will be, altered + during transmission, this argument SHOULD reflect what other + contacts will receive rather than being a copy of the argument + to <tp:member-ref>Send</tp:member-ref>. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that a message has been submitted for sending.</p> + </tp:docstring> + </signal> + + <tp:enum name="Channel_Text_Message_Type" type="u" + array-name="Channel_Text_Message_Type_List"> + <tp:docstring> + The type of message. + </tp:docstring> + + <tp:enumvalue suffix="Normal" value="0"> + <tp:docstring> + An ordinary chat message. Unknown types SHOULD be treated like this. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Action" value="1"> + <tp:docstring> + An action which might be presented to the user as + "* <sender> <action>", such as an IRC CTCP + ACTION (typically selected by the "/me" command). For example, the + text of the message might be "drinks more coffee". + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Notice" value="2"> + <tp:docstring> + A one-off or automated message not necessarily expecting a reply + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Auto_Reply" value="3"> + <tp:docstring> + An automatically-generated reply message. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Delivery_Report" value="4"> + <tp:docstring> + A delivery report. This message type MUST NOT appear unless the + channel supports the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface; see <tp:type>Message_Part</tp:type> for the format that + delivery reports must take. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface has an extensible data structure + including separate booleans for most of these flags. + </tp:deprecated> + <tp:flag suffix="Truncated" value="1"> + <tp:docstring> + The incoming message was truncated to a shorter length by the + server or the connection manager. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Non_Text_Content" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message contained non-text content which cannot be + represented by this interface, but has been signalled + in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface.</p> + + <p>Connection managers SHOULD only set this flag if the non-text + content appears to be relatively significant (exactly how + significant is up to the implementor). The intention is that + if this flag is set, clients using this interface SHOULD inform + the user that part of the message was not understood.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Scrollback" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message was part of a replay of message history.</p> + + <tp:rationale> + <p>In XMPP multi-user chat, a few past messages are replayed + when you join a chatroom. A sufficiently capable IRC connection + manager could also set this flag on historical messages when + connected to a proxy like bip or irssi-proxy. The existence + of this flag allows loggers and UIs to use better heuristics + when eliminating duplicates (a simple implementation made + possible by this flag would be to avoid logging scrollback + at all).</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Rescued" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message has been seen in a previous channel during + the lifetime of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, but + had not been acknowledged + when that channel closed, causing an identical channel (the + channel in which the message now appears) to open.</p> + + <tp:rationale> + <p>This means that a logger (which should already have seen the + message in the previous channel) is able to recognise and ignore + these replayed messages.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:property name="anonymous" type="b"> + <tp:docstring> + True if people may join the channel without other members being made + aware of their identity. + </tp:docstring> + </tp:property> + <tp:property name="invite-only" type="b"> + <tp:docstring> + True if people may not join the channel until they have been invited. + </tp:docstring> + </tp:property> + <tp:property name="limit" type="u"> + <tp:docstring> + The limit to the number of members, if limited is true. + </tp:docstring> + </tp:property> + <tp:property name="limited" type="b"> + <tp:docstring> + True if there is a limit to the number of channel members. + </tp:docstring> + </tp:property> + <tp:property name="moderated" type="b"> + <tp:docstring> + True if channel membership is not sufficient to allow participation. + </tp:docstring> + </tp:property> + <tp:property name="name" type="s"> + <tp:docstring> + A human-visible name for the channel, if it differs from the channel's + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>. + </tp:docstring> + </tp:property> + <tp:property name="description" type="s"> + <tp:docstring> + A human-readable description of the channel's overall purpose. + </tp:docstring> + </tp:property> + <tp:property name="password" type="s"> + <tp:docstring> + The password required to enter the channel if password-required is true. + </tp:docstring> + </tp:property> + <tp:property name="password-required" type="b"> + <tp:docstring> + True if a password must be provided to enter the channel. + </tp:docstring> + </tp:property> + <tp:property name="persistent" type="b"> + <tp:docstring> + True if the channel will remain in existence on the server after all + members have left it. + </tp:docstring> + </tp:property> + <tp:property name="private" type="b"> + <tp:docstring> + True if the channel is not visible to non-members. + </tp:docstring> + </tp:property> + <tp:property name="subject" type="s"> + <tp:docstring> + A human-readable description of the current subject of conversation in + the channel, similar to /topic in IRC. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + <tp:property name="subject-contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle representing who last modified the subject, or 0 + if it isn't known. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A unix timestamp indicating when the subject was last modified. + This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. + </tp:docstring> + </tp:property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for sending and receiving messages. This channel type + is primarily used for textual messages, but can also be used for + formatted text, text with "attachments", or binary messages on some + protocols.</p> + + <p>Most of the methods and signals on this interface are deprecated, + since they only support plain-text messages with limited metadata. + See the mandatory <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages</tp:dbus-ref> + interface for the modern equivalents.</p> + + <p>When a message is received, an identifier is assigned and a + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal emitted, and the message + is placed in a pending queue represented by the + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> property. + When the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + for a channel has handled the message by showing it to the user + (or equivalent), it should acknowledge the receipt of that message + using the <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> + method, and the message will then be removed from the pending queue. + Numeric identifiers for received messages may be reused over the + lifetime of the channel.</p> + + <p>Sending messages can be requested using the + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> method, which will return + successfully when the message has been submitted for sending, or + return an error with no signal emission if there is an immediate + failure. If a message is submitted for sending but delivery of the + message later fails, this is indicated by a delivery report, which + is received in the same way as an incoming message.</p> + + <p>Simple one-to-one chats (such as streams of private messages in + XMPP or IRC) should be represented by a Text channel whose + <tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> + is <tp:type>Handle_Type</tp:type>_Contact. The expected way to + request such a channel is to set the ChannelType, TargetHandleType, + and either TargetHandle or TargetID in a call to EnsureChannel.</p> + + <p>Named chat rooms whose identity can be saved and used again later + (IRC channels, Jabber MUCs) are expected to be represented by Text + channels with <tp:type>Handle_Type</tp:type>_Room and the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface. In protocols where a chatroom can be used as a continuation + of one or more one-to-one chats, these channels should also have the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>Unnamed, transient chat rooms which cannot be rejoined by their + unique identifier (e.g. a conversation on MSN which has, or once had, + three or more participants) are expected to be represented by Text + channels with Handle_Type_None (and hence TargetHandle 0), the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface, and optionally the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>On protocols like MSN where a conversation with a user is actually + just a nameless chat room starting with exactly two members, to which + more members can be invited, the initial one-to-one conversation + SHOULD be represented with Handle_Type_Contact. If a third participant + joins or is invited, this SHOULD be represented by signalling + a new <tp:dbus-ref + namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> channel + with the one-to-one channel in its <tp:dbus-ref + namespace="ofdT.Channel.Interface.Conference" + >InitialChannels</tp:dbus-ref>, migrating the underlying protocol + object from the one-to-one channel to the Conference channel, + and creating a new protocol-level conversation if the one-to-one + channel is re-used. See the Conference interface for more details.</p> + + <tp:rationale> + <p>This keeps the presentation of all one-to-one conversations + uniform, and makes it easier to hand over a conversation from a + 1-1-specific UI to a more elaborate multi-user UI; while it does + require UIs to understand Conference to follow the + upgrade, UIs that will deal with XMPP need to understand Conference + anyway.</p> + </tp:rationale> + + <p>If a channel of type Text is closed while it has pending messages, + the connection manager MUST allow this, but SHOULD open a new channel + to deliver those messages, signalling it as a new channel with the + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal. The new channel should resemble the old channel, but have + Requested = FALSE regardless of its previous value; the InitiatorHandle + and InitiatorID should correspond to the sender of one of the pending + messages.</p> + + <tp:rationale> + <p>In effect, this turns this situation, in which a client + is likely to lose messages:</p> + + <ul> + <li>UI window is closed</li> + <li>message arrives</li> + <li>text channel emits Received</li> + <li>UI calls Close on text channel before it has seen the + Received signal</li> + <li>text channel emits Closed and closes</li> + </ul> + + <p>into something nearly equivalent to this situation, which is + fine:</p> + + <ul> + <li>UI window is closed</li> + <li>UI calls Close on text channel</li> + <li>text channel emits Closed and closes</li> + <li>message arrives</li> + <li>new text channel is created, connection emits NewChannels</li> + <li>(the same or a different) UI handles it</li> + </ul> + + <p>Requested must be set to FALSE so the replacement channel + will be handled by something.</p> + + <p>In practice, connection managers usually implement this by keeping + the same internal object that represented the old channel, adjusting + its properties, signalling that it was closed, then immediately + re-signalling it as a new channel.</p> + </tp:rationale> + + <p>As a result, Text channels SHOULD implement <tp:dbus-ref + namespace="ofdT">Channel.Interface.Destroyable</tp:dbus-ref>.</p> + + <tp:rationale> + <p>This "respawning" behaviour becomes problematic if there is no + suitable handler for Text channels, or if a particular message + repeatedly crashes the Text channel handler; a channel dispatcher + can't just Close() the channel in these situations, because + it will come back.</p> + + <p>In these situations, the channel dispatcher needs a last-resort + way to destroy the channel and stop it respawning. It could either + acknowledge the messages itself, or use the Destroyable interface; + the Destroyable interface has the advantage that it's not + channel-type-dependent, so the channel dispatcher only has to + understand one extra interface, however many channel types + eventually need a distinction between Close and Destroy.</p> + </tp:rationale> + + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml new file mode 100644 index 0000000..c0a973f --- /dev/null +++ b/spec/Channel_Type_Tubes.xml @@ -0,0 +1,615 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright © 2007-2009 Collabora Limited + </tp:copyright> + <tp:license> + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes"> + + <tp:deprecated version="0.17.25">Client implementations + SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref> + instead.</tp:deprecated> + + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A "tube" is a mechanism for arbitrary data transfer. Two types of + data transfer are currently specified: D-Bus messages, and streams of + bytes. Each tube has a service name, which is a string specifying the + kind of communication that takes place over it, and a dictionary of + arbitrary parameters. Tube parameters are commonly used for bootstrap + information such as usernames and passwords. Each tube is identified + by a locally unique identifier.</p> + + <p>The Tubes channel type may be requested for handles of type + HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p> + + <p>Stream tubes specify listening addresses using pairs of parameters + with signature 'u', 'v', where the integer 'u' is a member of + Socket_Address_Type and the v is dependent on the type of address.</p> + </tp:docstring> + + <tp:simple-type name="Tube_ID" type="u"> + <tp:docstring>An identifier for a tube. These are local to a Tubes + channel, and may not be assumed to be the same as the other + participants' idea of the tube identifier.</tp:docstring> + </tp:simple-type> + + <tp:struct name="Tube_Info" array-name="Tube_Info_List"> + <tp:docstring>A struct (tube ID, initiator handle, tube type, + service name, parameters, state) representing a tube, as returned + by ListTubes on the Tubes channel type.</tp:docstring> + <tp:member type="u" tp:type="Tube_ID" name="Identifier"/> + <tp:member type="u" tp:type="Contact_Handle" name="Initiator"/> + <tp:member type="u" tp:type="Tube_Type" name="Type"/> + <tp:member type="s" name="Service"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> + <tp:member type="u" tp:type="Tube_State" name="State"/> + </tp:struct> + + <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List"> + <tp:docstring>Represents a participant in a multi-user D-Bus tube, as + returned by <tp:member-ref>GetDBusNames</tp:member-ref> and seen in the + <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The handle of a participant in this D-Bus tube. + </tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> + <tp:docstring> + That participant's unique name. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum name="Tube_Type" type="u" array-name="Tube_Type_List"> + <tp:enumvalue suffix="DBus" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The tube is D-Bus tube as described by the + org.freedesktop.Telepathy.Channel.Type.DBusTube interface.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Stream" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The tube is stream tube as described by the + org.freedesktop.Telepathy.Channel.Type.StreamTube interface.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Tube_State" type="u"> + <tp:enumvalue suffix="Local_Pending" value="0"> + <tp:docstring> + The tube is waiting to be accepted/closed locally. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:docstring> + The tube is waiting to be accepted/closed remotely. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="2"> + <tp:docstring> + The tube is open for traffic. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Supported_Socket_Map"> + <tp:docstring>The supported socket address and access-control types + for tubes. See GetAvailableStreamTubeTypes.</tp:docstring> + <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/> + <tp:member name="Access_Control" type="au" + tp:type="Socket_Access_Control[]"/> + </tp:mapping> + + <method name="GetAvailableStreamTubeTypes" + tp:name-for-bindings="Get_Available_Stream_Tube_Types"> + <tp:docstring>List the available address types and access-control types + for stream tubes.</tp:docstring> + <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map" + name="Available_Stream_Tube_Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for stream tubes with that + address type. For simplicity, if a CM supports offering a + particular type of tube, it is assumed to support accepting it.</p> + + <p>A typical value for a host without IPv6 support:</p> + + <pre> + { + Socket_Address_Type_IPv4: + [Socket_Access_Control_Localhost, Socket_Access_Control_Port, + Socket_Access_Control_Netmask], + Socket_Address_Type_Unix: + [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] + } + </pre> + + <p>If stream tubes are not supported, this will be an empty + dictionary.</p> + </tp:docstring> + </arg> + </method> + + <method name="GetAvailableTubeTypes" + tp:name-for-bindings="Get_Available_Tube_Types"> + <arg direction="out" type="au" tp:type="Tube_Type[]" + name="Available_Tube_Types"> + <tp:docstring> + An array of the available tube types, as defined by the Tube_Type + enum. + </tp:docstring> + </arg> + </method> + + <method name="ListTubes" tp:name-for-bindings="List_Tubes"> + <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]" + name="Tubes"> + <tp:docstring> + Return an array of tuples, each representing a tube, with the + following members: + + <ul> + <li>the tube's ID</li> + <li>the tube's initiator</li> + <li>the tube's type</li> + <li>the tube's service</li> + <li>the tube's parameters</li> + <li>the tube's state</li> + </ul> + </tp:docstring> + </arg> + </method> + + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="OfferDBusTube" tp:name-for-bindings="Offer_D_Bus_Tube"> + <tp:docstring> + Offers a D-Bus tube providing the service specified. + </tp:docstring> + <arg direction="in" name="Service" type="s"> + <tp:docstring> + A string representing the service name that will be used over the + tube. + It should be a well-known D-Bus service name, of the form + com.example.ServiceName. + </tp:docstring> + </arg> + <arg direction="in" name="Parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + A dictionary of properties for the new tube; the allowable keys, + types and values are defined by the service. Connection managers + must support the value being any primitive (non-container) + D-Bus type, or a byte array 'ay'. + </tp:docstring> + </arg> + <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> + <tp:docstring> + The ID of the new tube. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact associated with this channel doesn't have tubes + capabilities. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The connection manager doesn't support D-Bus tubes. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube"> + <tp:docstring> + Offer a stream tube exporting the local socket specified. + </tp:docstring> + <arg direction="in" name="Service" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A string representing the service name that will be used over the + tube. + It should be a well-known TCP service name as defined by + <a href="http://www.iana.org/assignments/port-numbers"> + http://www.iana.org/assignments/port-numbers</a> or + <a href="http://www.dns-sd.org/ServiceTypes.html"> + http://www.dns-sd.org/ServiceTypes.html</a>, for instance + "rsync" or "daap". + </tp:docstring> + </arg> + <arg direction="in" name="Parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary of properties for the new tube; the allowable keys, + types and values are defined by the service. Connection managers + must support the value being any primitive (non-container) + D-Bus type, or a byte array 'ay'.</p> + <p>These should usually be the same key-value pairs specified for + use in the DNS-SD TXT record for that service.</p> + </tp:docstring> + </arg> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of the listening address of the local service, as a member of + Socket_Address_Type. + </tp:docstring> + </arg> + <arg direction="in" name="Address" type="v"> + <tp:docstring> + The listening address of the local service, as indicated by the + address_type. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the local service applies to the local socket, + specified so the connection manager can behave appropriately + when it connects. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control_Param" type="v"> + <tp:docstring> + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + </tp:docstring> + </arg> + <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> + <tp:docstring> + The ID of the new tube. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact associated with this channel doesn't have tube + capabilities. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The connection manager doesn't support stream tubes, or + does not support the given address type or access-control type. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="NewTube" tp:name-for-bindings="New_Tube"> + <tp:docstring> + Emitted when a tube is created. + </tp:docstring> + <arg name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the new tube. + </tp:docstring> + </arg> + <arg name="Initiator" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the contact who initiated the tube. + </tp:docstring> + </arg> + <arg name="Type" type="u" tp:type="Tube_Type"> + <tp:docstring> + The tube type, as defined by the Tube_Type enum. + </tp:docstring> + </arg> + <arg name="Service" type="s"> + <tp:docstring> + A string representing the service that will be used over the tube. + </tp:docstring> + </arg> + <arg name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + The new tube's properties. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Tube_State"> + <tp:docstring> + The new tube's state. + </tp:docstring> + </arg> + </signal> + + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="AcceptDBusTube" tp:name-for-bindings="Accept_D_Bus_Tube"> + <tp:docstring> + Accept a D-Bus tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeStateChanged signal is + emitted. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube to accept. + </tp:docstring> + </arg> + <arg direction="out" name="Address" type="s"> + <tp:docstring> + The string describing the address of the private bus. The client + should not attempt to connect to the address until the tube is open. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given tube ID is invalid or does not refer to a D-Bus + tube. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube"> + <tp:docstring> + Accept a stream tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeStateChanged signal is + emitted. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube to accept. + </tp:docstring> + </arg> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of address the connection manager should listen on. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The type of access control the connection manager should apply to + the socket. + </tp:docstring> + </arg> + <arg direction="in" name="Access_Control_Param" type="v"> + <tp:docstring> + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + </tp:docstring> + </arg> + <arg direction="out" name="Address" type="v"> + <tp:docstring> + The address on which the connection manager will listen for + connections to this tube. The client should not attempt to connect + to the address until the tube is open. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given tube ID is invalid or does not refer to a stream + tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The given address type or access-control mechanism is not supported. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="TubeStateChanged" tp:name-for-bindings="Tube_State_Changed"> + <tp:docstring> + Emitted when the state of a tube changes. + </tp:docstring> + <arg name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube that changed state. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Tube_State"> + <tp:docstring> + The new state of the tube; see the Tube_State enumeration. + </tp:docstring> + </arg> + </signal> + + <method name="CloseTube" tp:name-for-bindings="Close_Tube"> + <tp:docstring> + Close a tube. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube to close. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" /> + </tp:possible-errors> + </method> + + <signal name="TubeClosed" tp:name-for-bindings="Tube_Closed"> + <tp:docstring> + Emitted when a tube has been closed. The ID of a closed tube is no + longer valid. The ID may later be reused for a new tube. + </tp:docstring> + <arg name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube that was closed. + </tp:docstring> + </arg> + </signal> + + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="GetDBusTubeAddress" + tp:name-for-bindings="Get_D_Bus_Tube_Address"> + <tp:docstring> + For a D-Bus tube, return a string describing the address of the + private bus. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube to get an address for. + </tp:docstring> + </arg> + <arg direction="out" type="s" name="Address"> + <tp:docstring> + The bus address. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The tube is not a D-Bus tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This tube is not in the "open" state. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="GetDBusNames" tp:name-for-bindings="Get_D_Bus_Names"> + <tp:docstring> + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping + between contact handles and their unique bus names on this tube. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube to get names for. + </tp:docstring> + </arg> + <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]" + name="DBus_Names"> + <tp:docstring> + An array of structures, each containing a contact handle and a D-Bus + bus name. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The tube is not a multi-user D-Bus tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This tube is not in the "open" state. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <signal name="DBusNamesChanged" tp:name-for-bindings="D_Bus_Names_Changed"> + <tp:docstring> + Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a + participant opens or closes the tube. + </tp:docstring> + <arg name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube whose names have changed. + </tp:docstring> + </arg> + <arg name="Added" type="a(us)" tp:type="DBus_Tube_Member[]"> + <tp:docstring> + Array of handles and D-Bus names of new participants. + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + Array of handles of former participants. + </tp:docstring> + </arg> + </signal> + + <method name="GetStreamTubeSocketAddress" + tp:name-for-bindings="Get_Stream_Tube_Socket_Address"> + <tp:docstring> + For a stream tube, obtain the address of the socket used to + communicate over this tube. + </tp:docstring> + <arg direction="in" name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the stream tube to get the socket for. + </tp:docstring> + </arg> + <arg direction="out" name="Address_Type" type="u" tp:type="Socket_Address_Type"> + <tp:docstring> + The type of the listening address of the socket, as a member of + Socket_Address_Type. + </tp:docstring> + </arg> + <arg direction="out" name="Address" type="v"> + <tp:docstring> + The listening address of the socket, as indicated by the + address_type. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The tube is not a stream tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This tube is not in the "open" state. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="StreamTubeNewConnection" + tp:name-for-bindings="Stream_Tube_New_Connection"> + <tp:docstring> + Emitted on a stream tube when a participant opens a new connection + to its socket. + </tp:docstring> + <arg name="ID" type="u" tp:type="Tube_ID"> + <tp:docstring> + The ID of the tube + </tp:docstring> + </arg> + <arg name="Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the participant who opened the new connection + </tp:docstring> + </arg> + </signal> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client.xml b/spec/Client.xml new file mode 100644 index 0000000..19f6914 --- /dev/null +++ b/spec/Client.xml @@ -0,0 +1,122 @@ +<?xml version="1.0" ?> +<node name="/Client" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Telepathy clients use connection managers, the channel dispatcher + and optionally the account manager to provide useful + functionality.</p> + + <p>User interface processes are the obvious example of Telepathy + clients, but they can provide other functionality, such as + address-book synchronization.</p> + + <p>Every running or activatable process with a well-known + name of the form org.freedesktop.Telepathy.Client.<em>clientname</em> + should be probed by the channel dispatcher to discover its + capabilities. Each client is either an <em>observer</em>, an + <em>approver</em>, a <em>channel handler</em>, or some combination + of these.</p> + + <tp:rationale> + <p>Activatable services (those with a D-Bus <code>.service</code> + file) must be supported so that we can run clients + in response to channel creation.</p> + + <p>Non-activatable services (those that do not register a D-Bus + <code>.service</code> file for their well-known name, but do + request it at runtime) must be supported so that we can have + programs that process channels, but only if they are already + running - for instance, a full-screen media centre + application might do this.</p> + </tp:rationale> + + <p>The client name, <em>clientname</em>, MUST be a non-empty string of + ASCII digits, letters, dots and/or underscores, starting with a + letter, and without sets of two consecutive dots or a dot + followed by a digit. For non-activatable services, it MAY contain a + part that is generated per instance at runtime.</p> + + <tp:rationale> + <p>If each of a client Foo's instances should be able to manipulate + channels separately, the instance with unique name + <code>:1.25</code> might request a well-known name like + <code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p> + + <p>(Note that well-known bus-name components may not start with a + digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p> + </tp:rationale> + + <p>Each Client MUST export an object whose object path may be + determined by replacing '.' with '/' in the well-known name and + prepending '/'. This object represents its API as a Telepathy + client; the channel dispatcher will call its methods and read + its properties when appropriate.</p> + + <p>As an optimization, activatable clients SHOULD install a file + <code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code> + containing a cached version of its immutable properties, + so that for most clients, the channel dispatcher can + just read a file to discover capabilities, instead of + having to service-activate the client immediately in order to fetch + its read-only properties. However, the D-Bus API is canonical, and + the channel dispatcher MUST support clients without such a file.</p> + + <p>Non-activatable clients MAY install a <code>.client</code> file, + but there's not much point in them doing so.</p> + + <p>The .client files MUST contain UTF-8 text with the same syntax + as + <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop + Entry files</a> (although the allowed groups, keys and values differ). + Every <code>.client</code> file MUST contain a group whose name is + the name of this interface.</p> + + <p>The groups, keys and values in the <code>.client</code> file are + defined by individual interfaces. Each interface that can usefully + cache information in the <code>.client</code> file SHOULD correspond + to a group with the same name.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the extra interfaces provided by this client. + This SHOULD include at least one of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p> + + <p>In the <code>.client</code> file, this is represented by key + "<code>Interfaces</code>" in the group named after this interface. + The value of the key is a list of interface names each followed by + a semicolon (so it always ends with a semicolon unless it is empty), + i.e. a key of type "strings" as described in the Desktop Entry + specification.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml new file mode 100644 index 0000000..dd26303 --- /dev/null +++ b/spec/Client_Approver.xml @@ -0,0 +1,197 @@ +<?xml version="1.0" ?> +<node name="/Client_Approver" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Approver"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Approvers are clients that notify the user that new channels have + been created by a contact, and allow the user to accept or reject + those channels. The new channels are represented by a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + object, which is passed to the + <tp:member-ref>AddDispatchOperation</tp:member-ref> method.</p> + + <tp:rationale> + <p>For instance, Empathy's tray icon, or the answer/reject window + seen when a Maemo device receives a VoIP call, should be + Approvers.</p> + </tp:rationale> + + <p>Approvers can also select which channel handler will be used for the + channel, for instance by offering the user a list of possible + handlers rather than just an accept/reject choice. + However, the Channel Dispatcher must be able to prioritize + possible handlers on its own using some reasonable heuristic, + probably based on user configuration.</p> + + <p>It is possible (and useful) to have an approver and + a channel handler in the same process; this is particularly useful + if a channel handler wants to claim responsibility for particular + channels itself.</p> + + <p>All approvers are notified simultaneously. For instance, in a + desktop system, there might be one approver that displays a + notification-area icon, one that is part of a contact list + window and highlights contacts there, and one that is part + of a full-screen media player.</p> + + <p>Any approver can approve the handling of a channel dispatch operation + with a particular channel handler by calling the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> + method. Approvers can also attempt to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + channels; if this succeeds, the approver may handle the channels + itself (if it is also a Handler), or close the channels in order to + reject them.</p> + + <p>At the D-Bus level, there is no "reject" operation: approvers wishing + to reject channels SHOULD call the Claim method, then (if it succeeds) + close the channels in any way they see fit.</p> + + <p>The first approver to reply gets its decision acted on; any other + approvers that reply at approximately the same time will get a D-Bus + error, indicating that the channel has already been dealt with.</p> + + <p>Approvers should usually prompt the user and ask for + confirmation, rather than dispatching the channel to a handler + straight away.</p> + </tp:docstring> + + <property name="ApproverChannelFilter" + tp:name-for-bindings="Approver_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this approver is + interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> + method should be called by the channel dispatcher whenever at least + one of the channels in a channel dispatch operation matches this + description.</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> + property. In particular, it cannot change while the approver process + continues to own the corresponding Client bus name.</p> + + <p>In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + ApproverChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <method name="AddDispatchOperation" + tp:name-for-bindings="Add_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when a ChannelDispatchOperation + in which the approver has registered an interest is created, + or when the approver starts up while such channel dispatch + operations already exist.</p> + + <p>The channel dispatcher SHOULD call this method on all approvers + at the same time. If an approver returns an error from this method, + the approver is assumed to be faulty.</p> + + <p>If no approvers return from this method + successfully (including situations where there are no matching + approvers at all), the channel dispatcher SHOULD consider this + to be an error, and recover by dispatching the channel to the + most preferred handler.</p> + + <tp:rationale> + Processes that aren't approvers (or don't at least ensure that there + is some approver) probably shouldn't be making connections + anyway, so there should always be at least one approver running. + </tp:rationale> + </tp:docstring> + + <arg name="Channels" direction="in" + type="a(oa{sv})" tp:type="Channel_Details[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The initial value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Channels</tp:dbus-ref> + property, containing the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + to be dispatched and their properties.</p> + + <tp:rationale> + <p>This can't be signalled to the approver through the Properties + parameter of this method, because Channels is not an immutable + property.</p> + </tp:rationale> + + <p>This argument always contains all of the channels in the channel + dispatch operation, even if not all of them actually match + the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p> + + <tp:rationale> + <p>This seems the least bad way to handle such a situation; + see the discussion on + <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug + #21090</a>.</p> + </tp:rationale> + + <p>The actual channels to be dispatched may reduce as channels are + closed: this is signalled by <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>. + </p> + + <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>. + (if desired) before returning from AddDispatchOperation, since + those signals are guaranteed not to be emitted until after all + AddDispatchOperation calls have returned (with success or failure) + or timed out.</p> + </tp:docstring> + </arg> + + <arg name="DispatchOperation" type="o" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + to be processed.</p> + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + <p>Properties of the channel dispatch operation. The keys MUST be + fully qualified D-Bus property names. This MUST NOT include + properties that could change, SHOULD include as many properties as + possible given that constraint, and MUST include at least the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref> + properties.</p> + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml new file mode 100644 index 0000000..3a922e8 --- /dev/null +++ b/spec/Client_Handler.xml @@ -0,0 +1,337 @@ +<?xml version="1.0" ?> +<node name="/Client_Handler" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Handler"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Handlers are the user interface for a channel. They turn an abstract + Telepathy channel into something the user wants to see, like a text + message stream or an audio and/or video call.</p> + + <p>For its entire lifetime, each channel on a connection known to the + channel dispatcher is either being processed by the channel dispatcher, + or being handled by precisely one Handler.</p> + + <p>Because each channel is only handled by one Handler, handlers may + perform actions that only make sense to do once, such as acknowledging + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages, doing the actual streaming for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + channels with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface, or transferring the file in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">FileTransfer</tp:dbus-ref> + channels.</p> + + <p>When a new incoming channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + = FALSE) is offered to + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s + by the channel dispatcher, it also offers the Approvers a list of all + the running or activatable handlers whose + <tp:member-ref>HandlerChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they + are able to handle the channel. The Approvers can choose one of + those channel handlers to handle the channel.</p> + + <p>When a new outgoing channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + = TRUE) appears, the channel dispatcher passes it to an appropriate + channel handler automatically. + </p> + + </tp:docstring> + + <property name="HandlerChannelFilter" + tp:name-for-bindings="Handler_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels that this channel handler can + deal with. It will be offered to approvers as a potential + channel handler for bundles that contain only suitable channels, + or for suitable channels that must be handled separately.</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> + property. In particular, it cannot change while the handler process + continues to own the corresponding Client bus name.</p> + + <p>In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + HandlerChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler are automatically + handled, without invoking approvers.</p> + + <tp:rationale> + <p>The intended usage is to allow a client handling one channel to + pick up closely related channels. Suppose a client capable of + handling both Text and StreamedMedia, + <code>org.freedesktop.Telepathy.Client.Empathy</code>, is + handling a StreamedMedia channel. That client can take a second + well-known bus name, say + <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>, + and configure an object at + <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code> + with BypassApproval = TRUE, + whose <tp:member-ref>HandlerChannelFilter</tp:member-ref> + matches closely related Text channels by their Bundle property.</p> + </tp:rationale> + + <p>For service-activatable handlers, this property should be specified + in the handler's <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Handler] +BypassApproval=true +</pre> + </tp:docstring> + </property> + + <tp:simple-type name="Handler_Capability_Token" type="s" + array-name="Handler_Capability_Token_List"> + <tp:docstring> + A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character + and an identifier for a capability defined by that interface. The + capability identifier SHOULD be in lower case. If an interface + references an external specification which is case-insensitive (such + as MIME), then names from that specification MUST be normalized to + lower-case before providing them to this Telepathy API, so that + implementations can safely rely on simple byte-by-byte comparison. + + <tp:rationale> + These aren't D-Bus core Properties, and we want them to look visibly + different. + </tp:rationale> + + <p>So far, all client capabilities are defined by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface.</p> + </tp:docstring> + </tp:simple-type> + + <property name="Capabilities" tp:name-for-bindings="Capabilities" + type="as" tp:type="Handler_Capability_Token[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The set of additional capabilities supported by this handler. + This describes things like support for streamed media codecs and + NAT traversal mechanisms: see the Contact Capabilities + interface for more details.</p> + + <p>For handlers that have a <code>.client</code> file, the + channel dispatcher may discover this property from the + <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code> + group; for each capability, that group contains a key + whose name is the capability, with value <code>true</code>. + Keys with other values SHOULD NOT appear in this group.</p> + + <p>For instance, the <code>.client</code> file for a streamed media + handler that supports ICE-UDP NAT traversal, Speex audio, + and Theora and H264 video might contain this group:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Handler.Capabilities] +org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true +org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true +org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true +org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true +</pre> + + <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref> + property, this property cannot change while the Handler owns its + Client bus name. However, the <code>.client</code> file, if any, + can change (due to upgrades or installation of pluggable codecs), + and the capabilities really supported by the handler might not + exactly match what is cached in the <code>.client</code> file.</p> + + <tp:rationale> + <p>The client file is installed statically and is intended to list + codecs etc. that the handler guarantees it can support (e.g. by + having a hard dependency on them), whereas the running handler + process might be able to find additional codecs.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when this client should handle these + channels, or when this client should present channels that it is already + handling to the user (e.g. bring them into the foreground).</p> + + <tp:rationale> + <p>Clients are expected to know what channels they're already handling, + and which channel object path corresponds to which window or tab. + This can easily be done using a hash table keyed by channels' object + paths.</p> + </tp:rationale> + + <p>This method can raise any D-Bus error. If it does, the + handler is assumed to have failed or crashed, and the channel + dispatcher MUST recover in an implementation-specific way; it MAY + attempt to dispatch the channels to another handler, or close the + channels.</p> + + <p>If closing the channels, it is RECOMMENDED that the channel + dispatcher attempts to close the channels using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, + but resorts to calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + (if available) or ignoring the channel (if not) if the same handler + repeatedly fails to handle channels.</p> + + <p>After HandleChannels returns successfully, the client process is + considered to be responsible for the channel until it its unique + name disappears from the bus.</p> + + <tp:rationale> + <p>If a process has multiple Client bus names - some temporary and + some long-lived - and drops one of the temporary bus names in order + to reduce the set of channels that it will handle, any channels + that it is already handling should remain unaffected.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The Connection with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" direction="in" + tp:type="Channel_Details[]"> + <tp:docstring> + The channels and their immutable properties. Their well-known + bus name is the same as that of the Connection. + </tp:docstring> + </arg> + + <arg name="Requests_Satisfied" type="ao" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requests satisfied by these channels.</p> + + <tp:rationale> + <p>If the handler implements Requests, this tells it + that these channels match previous <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> + calls that it may have received.</p> + + <p>There can be more than one, if they were EnsureChannel + requests.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="User_Action_Time" type="t" direction="in"> + <tp:docstring> + The time at which user action occurred, or 0 if this channel + is to be handled for some reason not involving user action. + Handlers SHOULD use this for focus-stealing prevention, + if applicable. + This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> + but is unsigned for historical reasons. + </tp:docstring> + </arg> + + <arg name="Handler_Info" type="a{sv}" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about these channels. Currently defined + keys are:</p> + + <dl> + <dt><code>request-properties</code> - a{oa{sv}}</dt> + <dd>A map from <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + paths listed in <var>Requests_Satisfied</var> to + <tp:type>Qualified_Property_Value_Map</tp:type>s containing + namespaced immutable properties of each request.</dd> + </dl> + + <p>When more keys are defined for this dictionary, all will be + optional; handlers MAY safely ignore any entry in this + dictionary.</p> + </tp:docstring> + </arg> + + <!-- FIXME: invent a way to say "any error is possible" in spec markup --> + </method> + + <property name="HandledChannels" tp:name-for-bindings="Handled_Channels" + type="ao" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the channels that this process is currently handling.</p> + + <p>There is no change notification.</p> + + <tp:rationale> + <p>This property exists for state recovery - it makes it possible + for channel handling to survive a ChannelDispatcher crash.</p> + + <p>If the channel dispatcher is automatically replaced, the + replacement can discover all Handlers by looking for the Client + well-known bus names, and discover which channels they are + currently handling. Once this has been done, all unhandled + channels can be re-dispatched, and the only issue visible to + the user is that unhandled channels that they have already + approved might be sent back to Approvers.</p> + </tp:rationale> + + <p>The value of this property SHOULD be the same for all Client + instances that share a unique bus name, and SHOULD include all + channels that are being handled, even if they were conceptually + handled by a different Client instance.</p> + + <tp:rationale> + <p>Otherwise, when a process released a temporary Client name, + channels that it handled because of that Client name would no + longer be state-recoverable.</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml new file mode 100644 index 0000000..4c1a8b7 --- /dev/null +++ b/spec/Client_Handler_Future.xml @@ -0,0 +1,88 @@ +<?xml version="1.0" ?> +<node name="/Client_Handler_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Handler.FUTURE" + tp:causes-havoc="a staging area for future Handler functionality"> + <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + interface in future. It should be considered to + be conceptually part of the core Handler interface, but without + API or ABI guarantees.</p> + </tp:docstring> + + <property name="BypassObservers" tp:name-for-bindings="Bypass_Observers" + type="b" access="read"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler are not passed to + observers for observing.</p> + + <tp:rationale> + <p>This is useful in use-cases where the handler doesn't want anyone + observing the channel - for example, because channels it handles + shouldn't be logged.</p> + </tp:rationale> + + <p>For service-activatable handlers, this property should be specified + in the handler's <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Handler] +BypassObservers=true +</pre> + </tp:docstring> + </property> + + <property name="RelatedConferencesBypassApproval" + tp:name-for-bindings="Related_Conferences_Bypass_Approval" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler that have the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Conference</tp:dbus-ref> interface, with a channel that + was previously handled by the same client process in their + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Conference" + >InitialChannels</tp:dbus-ref> property, should bypass the + approval stage. In effect, this is a weaker form of + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler" + >BypassApproval</tp:dbus-ref>.</p> + + <tp:rationale> + <p>It would be reasonable for a user interface to accept + invitations to continuations of an existing channel automatically, + or not; this is a matter of UI policy.</p> + + <p>It's somewhat complex for an Approver to keep track of which + channels are being handled by a particular Handler, but + the Channel Dispatcher already has to track this, so it's + useful for the channel dispatcher to assist here.</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml new file mode 100644 index 0000000..3cecfce --- /dev/null +++ b/spec/Client_Interface_Requests.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" ?> +<node name="/Client_Interface_Requests" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Interface.Requests"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client"/> + <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface can be implemented by a Handler to be notified about + requests for channels that it is likely to be asked to handle.</p> + </tp:docstring> + + <method name="AddRequest" tp:name-for-bindings="Add_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that channels have been + requested, and that if the request is successful, they will probably + be handled by this Handler. The ChannelDispatcher SHOULD only + call this method on one handler per request.</p> + + <tp:rationale> + <p>This allows the UI to start preparing to handle the channels + in advance (e.g. render a window with an "in progress" message), + improving perceived responsiveness.</p> + + <p>The use of "probably" is because you can't necessarily tell from + a channel request which handler will handle particular channels. + A reasonable heuristic would be to match the request against the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>, + and respect the preferred handler (if any).</p> + </tp:rationale> + + <p>If the request succeeds and is given to the expected Handler, + the Requests_Satisfied parameter to + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + can be used to match the channel to a previous AddRequest call.</p> + + <tp:rationale> + <p>This lets the UI direct the channels to the window that it + already opened.</p> + </tp:rationale> + + <p>If the request fails, the expected handler is notified by the + channel dispatcher calling its + <tp:member-ref>RemoveRequest</tp:member-ref> method.</p> + + <tp:rationale> + <p>This lets the UI close the window or display the error.</p> + </tp:rationale> + + <p>The channel dispatcher SHOULD remember which handler was notified, + and if the channel request succeeds, it SHOULD dispatch the channels + to the expected handler, unless the channels do not match that + handler's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>. + If the channels are not dispatched to the expected handler, the + handler that was expected is notified by the channel dispatcher + calling its <tp:member-ref>RemoveRequest</tp:member-ref> method + with the NotYours error.</p> + + <tp:rationale> + <p>Expected handling is for the UI to close the window it + previously opened.</p> + </tp:rationale> + + <p>Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.</p> + + <tp:rationale> + <p>Calls to this method are merely a notification.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which MUST have been returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> + before this method is called. + + <tp:rationale> + See those methods for the rationale of this ordering. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + <p>Some of the properties of the ChannelRequest. To avoid race + conditions, this dictionary MUST NOT include properties whose + values could subsequently change. It SHOULD include as many + properties as possible, given that constraint.</p> + + <p>In particular, the properties <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref> + MUST be included, and <tp:dbus-ref + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + MUST be included if implemented.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveRequest" + tp:name-for-bindings="Remove_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that a request + previously passed to <tp:member-ref>AddRequest</tp:member-ref> + has failed and should be disregarded.</p> + + <p>Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.</p> + + <tp:rationale> + <p>Calls to this method are merely a notification.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The request that failed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the D-Bus error with which the request failed.</p> + + <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>, + this indicates that the request succeeded, but all the resulting + channels were given to some other handler.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring> + Any message supplied with the D-Bus error. + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml new file mode 100644 index 0000000..01fee8b --- /dev/null +++ b/spec/Client_Observer.xml @@ -0,0 +1,379 @@ +<?xml version="1.0" ?> +<node name="/Client_Observer" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Observer"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p> + + <p>Observers SHOULD NOT modify the state of a channel except + via user interaction.</p> + + <tp:rationale> + <p>We want Observer UIs for file transfer channels (a progress + bar for the transfer) to be able to have a Cancel button.</p> + </tp:rationale> + + <p>Observers MUST NOT carry out actions that exactly one process + must take responsibility for (e.g. acknowledging Text + messages, or carrying out the actual transfer in a file transfer + channel).</p> + + <tp:rationale> + <p>Since arbitrarily many observers can be activated for + each channel, it would not make sense for observers to do things + that can only be done by one process (acknowledging + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages, carrying out streaming for + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + channels, doing the actual data transfer for file transfers, + setting up the out-of-band connection for Tubes). The + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + is responsible for such tasks.</p> + + <p>Handlers MAY, of course, delegate responsibility for these + tasks to other processes (including those run as observers), + but this MUST be done explicitly via a request from the Handler + to the Observer.</p> + </tp:rationale> + + <p>Whenever a collection of new channels is signalled, the channel + dispatcher will notify all running or activatable observers whose + <tp:member-ref>ObserverChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they are + interested in some of the channels.</p> + + <p>Observers are activated for all channels in which they have + registered an interest - incoming, outgoing or automatically created - + although of course the ObserverChannelFilter property can be set + to filter on the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + property.</p> + + <p>Because it might take time for an observer to become ready (for + instance, a Text logger needs to wait until pending messages have been + downloaded), the channel dispatcher must wait (up to some timeout) for + all observers to return from + <tp:member-ref>ObserveChannels</tp:member-ref> before letting anything + destructive happen. Destructive things (e.g. acknowledging messages) + are defined to be done by handlers, therefore HandleWith and Claim + aren't allowed to succeed until all observers are ready.</p> + </tp:docstring> + + <property name="ObserverChannelFilter" + tp:name-for-bindings="Observer_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this observer is + interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method + should be called by the channel dispatcher whenever any of the new + channels in a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal match this description.</p> + + <p>Only certain D-Bus types have useful semantics for matching like this, + so only certain types are allowed:</p> + + <dl> + <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt> + <dd>Matched by numeric value, regardless of type (e.g. 42 as a + 16-bit signed integer 'n' is considered equal to 42 as a 32-bit + unsigned integer 'u')</dd> + + <dt>Booleans (b)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Strings (s)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Object paths (o)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + </dl> + + <p>This property never changes while the observer process owns its + Client bus name. For activatable processes, the filter can change + due to an upgrade - the channel dispatcher SHOULD observe changes to + .client files using a mechanism like inotify.</p> + + <tp:rationale> + <p>Not allowing this property to change is a simplification, + particularly for activatable processes (we reject the possibility + that a process with a .client file, when activated, has a filter + that differs from what its .client file said).</p> + + <p>If an Observer wants to add extra channels to its list of + interests at runtime, it can register an additional Client bus name + (for instance, the org.freedesktop.Telepathy.Client.Empathy process + with unique name :1.42 could additionally register + org.freedesktop.Telepathy.Client.Empathy._1_42) with additional + filters. To remove those filters, it can release the bus name; + it could even re-claim the bus name immediately, with different + filters.</p> + + <p>The same principle is applied to Approvers and Handlers.</p> + </tp:rationale> + + <p>For observers that have a .client file, the channel dispatcher + may discover this property from keys of the form + "<code><em>propertyname</em> <em>type</em></code>", + in groups in the .client file whose name is the name of this + interface followed by <code>.ObserverChannelFilter</code>, + a space and an ASCII decimal number starting from 0.</p> + + <p>Values in the .client file are encoded in exactly the same way as + the <code>default-<em>p</em></code> keys in .manager files, as + described in the <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface (but note that not all + types supported in .manager files can appear in .client files).</p> + + <p>For instance, a .client file for an observer that is only interested + in Text channels, with CONTACT or ROOM handles, that were requested by + a local client:</p> + +<pre> +[org.freedesktop.Telepathy.Client] +Interfaces=org.freedesktop.Telepathy.Client.Observer; + +[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +org.freedesktop.Telepathy.Channel.Requested b=true + +[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=2 +org.freedesktop.Telepathy.Channel.Requested b=true +</pre> + + </tp:docstring> + </property> + + <property name="Recover" tp:name-for-bindings="Recover" type="b" + access="read"> + <tp:added version="0.19.4"> + When using telepathy-mission-control, version 5.4.0 or later is + needed for this property to be useful. + </tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, upon the startup of this observer, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref> + will be called for every already existing channel matching + its <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p> + + <p>When an activatable client having this property disappears from the + bus and there are channels matching its ObserverChannelFilter, + ObserveChannels will be called immediately to reactivate it + again. Such clients should specify this property in their + <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Observer] +Recover=true +</pre> + + <tp:rationale> + <p>This means that if an activatable Observer crashes, it will + be restarted as soon as possible; while there is an unavoidable + possibility that it will miss some events during this process + (particularly <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages), this window of event loss is kept to a minimum.</p> + + <p>Non-activatable observers can't take advantage of this + mechanism, but setting this property on a non-activatable + observer does allow it to "catch up" on channels that are + currently active at the time that it starts up.</p> + </tp:rationale> + + <p>When the ObserveChannels method is called due to observer recovery, + the <var>Observer_Info</var> dictionary will contain one extra item + mapping the key <code>"recovering"</code> to <code>True</code>.</p> + </tp:docstring> + </property> + + <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when channels in which the + observer has registered an interest are announced in a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal.</p> + + <p>If the same NewChannels signal announces some channels that match + the filter, and some that do not, then only a subset of the channels + (those that do match the filter) are passed to this method.</p> + + <p>If the channel dispatcher will split up the channels from a single + NewChannels signal and dispatch them separately (for instance + because no installed Handler can handle all of them), it will call + ObserveChannels several times.</p> + + <p>The observer MUST NOT return from this method call until it is ready + for a handler for the channel to run (which may change the channel's + state).</p> + + <tp:rationale> + <p>The channel dispatcher must wait for observers to start up, + to avoid the following race: text channel logger (observer) gets + ObserveChannels, text channel handler gets + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + channel handler starts up faster and acknowledges messages, + logger never sees those messages.</p> + </tp:rationale> + + <p>The channel dispatcher SHOULD NOT change its behaviour based on + whether this method succeeds or fails: there are no defined D-Bus + errors for this method, and if it fails, this only indicates that + an Observer is somehow broken.</p> + + <tp:rationale> + <p>The expected error response in the channel dispatcher is to + log a warning, and otherwise continue as though this method + had succeeded.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" + direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + and their properties. Their well-known bus names are all the same as + that of the Connection. + </tp:docstring> + </arg> + + <arg name="Dispatch_Operation" type="o" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The path to the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + for these channels, or the special value '/' if there is no + ChannelDispatchOperation (because the channels were requested, not + incoming).</p> + + <p>If the Observer calls <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> + on the dispatch operation, it MUST be careful to avoid deadlock, + since these methods cannot return until the Observer has returned + from <tp:member-ref>ObserveChannels</tp:member-ref>.</p> + + <tp:rationale> + <p>This allows an Observer to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> + a set of channels without having to match up calls to this method + with calls to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Requests_Satisfied" type="ao" direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>s + satisfied by these channels. + + <tp:rationale> + If the same process is an Observer and a Handler, it can be useful + to be given this information as soon as possible (it will also + be passed to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler.HandleChannels</tp:dbus-ref>). + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Observer_Info" type="a{sv}" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about these channels. Currently defined + keys are:</p> + + <dl> + <dt><code>recovering</code> - b</dt> + <dd><code>True</code> if ObserveChannels was called for an existing + channel (due to the <tp:member-ref>Recover</tp:member-ref> + property being <code>True</code>); <code>False</code> or omitted + otherwise. + + <tp:rationale> + This allows observers to distinguish between new channels (the normal + case), and existing channels that were given to the observer in order + to catch up on previous events (perhaps after a previous instance of + the same observer crashed). + </tp:rationale> + </dd> + + <dt><code>request-properties</code> - a{oa{sv}}</dt> + <dd>A map from <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + paths listed in <var>Requests_Satisfied</var> to + <tp:type>Qualified_Property_Value_Map</tp:type>s containing + namespaced immutable properties of each request.</dd> + </dl> + + <p>All defined keys for this dictionary are optional; + observers MAY safely ignore any entry in this dictionary.</p> + </tp:docstring> + </arg> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection.xml b/spec/Connection.xml new file mode 100644 index 0000000..51ec1ab --- /dev/null +++ b/spec/Connection.xml @@ -0,0 +1,1293 @@ +<?xml version="1.0" ?> +<node name="/Connection" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection"> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Requests"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> + + <tp:struct name="Channel_Info" array-name="Channel_Info_List"> + <tp:deprecated version="0.17.23"/> + <tp:docstring>A struct representing a channel, as returned by + ListChannels on the Connection interface.</tp:docstring> + <tp:member type="o" name="Channel"> + <tp:docstring>The object path of the channel, which is on the + same bus name as the connection</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"> + <tp:docstring>The channel's type</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Handle_Type" name="Handle_Type"> + <tp:docstring>The type of the handle that the channel communicates + with, or Handle_Type_None if there is no associated + handle</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Handle" name="Handle"> + <tp:docstring>The handle that the channel communicates with, + or 0 if there is no associated handle</tp:docstring> + </tp:member> + </tp:struct> + + <method name="Connect" tp:name-for-bindings="Connect"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the connection be established. This will be done + asynchronously and errors will be returned by emitting + <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> + + <p>Calling this method on a Connection that is already connecting + or connected is allowed, and has no effect.</p> + </tp:docstring> + </method> + + <method name="Disconnect" tp:name-for-bindings="Disconnect"> + <tp:docstring> + Request that the connection be closed. This closes the connection if + it's not already in DISCONNECTED state, and destroys the connection + object. + </tp:docstring> + </method> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + access="read" type="as" tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The set of optional interfaces supported by this connection. + Before the connection status changes to CONNECTED, + this property may change at any time, but it is guaranteed that + interfaces will only be added, not removed. After the connection + status changes to CONNECTED, this property cannot + change further.</p> + + <p>There is no explicit change notification; reasonable behaviour + for a client would be to retrieve the interfaces list once + initially, and once more when it becomes CONNECTED.</p> + + <tp:rationale> + <p>In some connection managers, certain capabilities of a connection + are known to be implemented for all connections (e.g. support + for SimplePresence), and some interfaces (like SimplePresence) can + even be used before connecting. Other capabilities may + or may not exist, depending on server functionality; by the time + the connection goes CONNECTED, the connection manager is expected + to have evaluated the server's functionality and enabled any extra + interfaces for the remainder of the Connection's lifetime.</p> + </tp:rationale> + </tp:docstring> + <tp:added version="0.19.2">Clients SHOULD fall back + to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this + property is not supported.</tp:added> + </property> + + <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> + <arg direction="out" type="as" tp:type="DBus_Interface[]" + name="Interfaces"> + <tp:docstring> + The value of the <tp:member-ref>Interfaces</tp:member-ref> property + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Returns the set of optional interfaces supported by this + connection. See <tp:member-ref>Interfaces</tp:member-ref> for more + details.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"> + <tp:docstring> + Before version 0.17.8 calling GetInterfaces while + on a connection that is not yet CONNECTED wasn't allowed. If a + CM returns this error, its list of interfaces should be regarded + as empty until it becomes CONNECTED. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetProtocol" tp:name-for-bindings="Get_Protocol"> + <arg direction="out" type="s" tp:type="Protocol" name="Protocol"> + <tp:docstring> + A string identifier for the protocol + </tp:docstring> + </arg> + + <tp:docstring> + Get the protocol this connection is using. + </tp:docstring> + </method> + + <signal name="SelfHandleChanged" + tp:name-for-bindings="Self_Handle_Changed"> + <tp:docstring> + Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property + changes. If the connection + is not yet in the CONNECTED state, this signal is not guaranteed + to be emitted. + </tp:docstring> + <tp:added version="0.17.10">Clients MAY assume that if the + SelfHandle property exists, this signal will be emitted when + necessary.</tp:added> + + <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> + <tp:docstring> + The new value of the SelfHandle property. + </tp:docstring> + </arg> + </signal> + + <property name="SelfHandle" tp:name-for-bindings="Self_Handle" + type="u" tp:type="Contact_Handle" access="read"> + <tp:docstring> + The handle which represents the user on this connection, which will + remain valid for the lifetime of this connection, or until a change + in the user's identifier is signalled by the + <tp:member-ref>SelfHandleChanged</tp:member-ref> signal. + If the connection is not yet in the CONNECTED state, the value of + this property MAY be zero. + </tp:docstring> + <tp:added version="0.17.10">For compatibility with older + versions, clients should fall back to calling the + <tp:member-ref>GetSelfHandle</tp:member-ref> + method.</tp:added> + </property> + + <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> + <arg direction="out" type="u" tp:type="Contact_Handle" + name="Self_Handle"> + <tp:docstring> + The value of the <tp:member-ref>SelfHandle</tp:member-ref> property + </tp:docstring> + </arg> + + <tp:docstring> + Returns the value of the SelfHandle property. Change notification + is via the SelfHandleChanged signal. + </tp:docstring> + <tp:deprecated version="0.17.10">Use GetAll to get the + SelfHandle property (and all other Connection properties) + instead.</tp:deprecated> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <property name="Status" tp:name-for-bindings="Status" + access="read" type="u" tp:type="Connection_Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The current status of the connection. Change notification is via + the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p> + + <p>If retrieval of property succeeds and yields the value Disconnected, + this indicates that the connection has not yet been established. + If connection has been attempted and failed, the Connection object + SHOULD be removed from the bus entirely, meaning that retrieval of + this property SHOULD fail.</p> + </tp:docstring> + <tp:added version="0.19.2">Clients SHOULD fall back + to calling <tp:member-ref>GetStatus</tp:member-ref> if this + property is not supported.</tp:added> + </property> + + <method name="GetStatus" tp:name-for-bindings="Get_Status"> + <arg direction="out" type="u" tp:type="Connection_Status" + name="Status"> + <tp:docstring> + The value of the <tp:member-ref>Status</tp:member-ref> property + </tp:docstring> + </arg> + + <tp:docstring> + Get the current status as defined in the + <tp:member-ref>StatusChanged</tp:member-ref> signal. + </tp:docstring> + </method> + + <method name="HoldHandles" tp:name-for-bindings="Hold_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer does anything.</tp:changed> + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + The type of handle to be held + </tp:docstring> + </arg> + + <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> + <tp:docstring> + A array of integer handles to hold + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.</p> + + <p>In older connection managers, this method + notifies the connection manger that your client is holding a copy + of handles which may not be in use in any existing channel or + list, and were not obtained by using the + <tp:member-ref>RequestHandles</tp:member-ref> method. For + example, a handle observed in an emitted signal, or displayed + somewhere in the UI that is not associated with a channel. The + connection manager must not deallocate a handle where any clients + have used this method to indicate it is in use until the + <tp:member-ref>ReleaseHandles</tp:member-ref> + method is called, or the clients disappear from the bus.</p> + + <p>Note that HoldHandles is idempotent - calling it multiple times + is equivalent to calling it once. If a handle is "referenced" by + several components which share a D-Bus unique name, the client + should perform reference counting internally, and only call + ReleaseHandles when none of the cooperating components need the + handle any longer.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The handle type is invalid + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + One of the given handles is not valid + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="InspectHandles" tp:name-for-bindings="Inspect_Handles"> + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + The type of handle to be inspected + </tp:docstring> + </arg> + + <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> + <tp:docstring> + An array of integer handles of this type + </tp:docstring> + </arg> + + <arg direction="out" type="as" name="Identifiers"> + <tp:docstring> + An array of identifiers corresponding to the given handles, in the same order. + </tp:docstring> + </arg> + + <tp:docstring> + Return a string representation for a number of handles of a given + type. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The handle type is invalid + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + One of the given handles is not valid + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ListChannels" tp:name-for-bindings="List_Channels"> + <tp:deprecated version="0.17.23">Use the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.Channels</tp:dbus-ref> + property instead. + </tp:deprecated> + + <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]" + name="Channel_Info"> + <tp:docstring> + An array of structs representing channels. + </tp:docstring> + </arg> + + <tp:docstring> + List all the channels which currently exist on this connection. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <signal name="NewChannel" tp:name-for-bindings="New_Channel"> + <tp:deprecated version="0.17.23">Connection managers MUST still + emit this signal, but clients SHOULD listen for the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.NewChannels</tp:dbus-ref> + signal instead. + </tp:deprecated> + + <arg name="Object_Path" type="o"> + <tp:docstring> + A D-Bus object path for the channel object on this service + </tp:docstring> + </arg> + + <arg name="Channel_Type" type="s" tp:type="DBus_Interface"> + <tp:docstring> + A D-Bus interface name representing the channel type + </tp:docstring> + </arg> + + <arg name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + An integer representing the type of handle this channel + communicates with, or Handle_Type_None if no handle is specified + </tp:docstring> + </arg> + + <arg name="Handle" type="u" tp:type="Handle"> + <tp:docstring> + A handle indicating the specific contact, room or list this + channel communicates with, or zero if no handle is specified + </tp:docstring> + </arg> + + <arg name="Suppress_Handler" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the channel was requested by a client that intends to + present it to the user itself (i.e. it passed suppress_handler=TRUE + to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no + other handler should be + launched. Clients MAY assume that channels where this is true + were created by a user request.</p> + + <p>If false, either the channel was created due to incoming + information from the service, or the channel was requested by + a local client that does not intend to handle the channel itself + (this usage is deprecated).</p> + + <p>Clients MUST NOT assume that only incoming channels will have + this flag set to false.</p> + </tp:docstring> + </arg> + + <tp:docstring> + Emitted when a new Channel object is created, either through user + request or incoming information from the service. + </tp:docstring> + </signal> + + <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer does anything.</tp:changed> + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + An integer handle type (as defined in RequestHandle) + </tp:docstring> + </arg> + + <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> + <tp:docstring> + An array of integer handles being held by the client + </tp:docstring> + </arg> + + <tp:docstring> + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.</p> + + <p>In older connection managers, this method + explicitly notifies the connection manager that your client is no + longer holding any references to the given handles, and that they + may be deallocated if they are not held by any other clients or + referenced by any existing channels. See + <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The handle type is invalid + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + One of the given handles is not valid + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestChannel" tp:name-for-bindings="Request_Channel"> + <tp:deprecated version="0.17.23">Use + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.CreateChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> + instead. Connection managers MAY implement RequestChannel by + raising NotImplemented, or implement fewer types of channel via + this API.</tp:deprecated> + + <arg direction="in" name="Type" type="s" tp:type="DBus_Interface"> + <tp:docstring> + A D-Bus interface name representing base channel type + </tp:docstring> + </arg> + + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + An integer representing the handle type, or Handle_Type_None if + no handle is specified + </tp:docstring> + </arg> + + <arg direction="in" name="Handle" type="u" tp:type="Handle"> + <tp:docstring> + A nonzero integer handle representing a contact, room, list etc. + according to handle_type, or zero if the handle_type is + Handle_Type_None + </tp:docstring> + </arg> + + <arg direction="in" name="Suppress_Handler" type="b"> + <tp:docstring> + <p>Clients SHOULD always set this to true.</p> + + <tp:rationale> + <p>The historical meaning was that clients that did not + intend to take responsibility for displaying the channel to + the user could set this to FALSE, in which case the channel + dispatcher would launch an appropriate channel handler.</p> + + <p>However, clients whose functionality relies on having a + working channel dispatcher should obtain that functionality by + calling methods on the channel dispatcher, so that they will + get an appropriate error if the channel dispatcher is missing + or not working.</p> + + <p>The channel dispatcher itself should set this to true too, + so that it will ignore the + <tp:member-ref>NewChannel</tp:member-ref> signal that results + from the creation of the channel. It can then dispatch the + channel returned from this method to an + appropriate handler.</p> + + <p>So, there is no sensible use-case for setting this to false, + and setting it to false can result in unhandled channels (in + the case where clients assume that a channel dispatcher is + present, but it isn't).</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" type="o" name="Object_Path"> + <tp:docstring> + The D-Bus object path for the channel created or retrieved + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request a channel satisfying the specified type and communicating + with the contact, room, list etc. indicated by the given + handle_type and handle. The handle_type and handle may both be + zero to request the creation of a new, empty channel, which may + or may not be possible, depending on the protocol and channel + type.</p> + + <p>On success, the returned channel will always be of the requested + type (i.e. implement the requested channel-type interface).</p> + + <p>If a new, empty channel is requested, on success the returned + channel will always be an "anonymous" channel for which the type + and handle are both zero.</p> + + <p>If a channel to a contact, room etc. is requested, on success, the + returned channel may either be a new or existing channel to + the requested entity (i.e. its + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + properties are the + requested handle type and handle), or a newly created "anonymous" + channel associated with the requested handle in some + implementation-specific way.</p> + + <p>For example, for a contact handle, the returned channel + might be "anonymous", but implement the groups interface and have + the requested contact already present among the members.</p> + + <p>If the request cannot be satisfied, an error is raised and no + channel is created.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Unknown channel type + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The given handle does not exist or cannot be created + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel type cannot be created with the given handle + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because contact doesn't + have the required capabilities. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + </tp:possible-errors> + </method> + + <tp:enum name="Handle_Type" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + A "null" handle type used to indicate the absence of a handle. + When a handle type and a handle appear as a pair, if the handle + type is zero, the handle must also be zero. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Contact" value="1"> + <tp:docstring> + A contact + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Room" value="2"> + <tp:docstring> + A chat room + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="List" value="3"> + <tp:docstring> + A server-generated contact list (see Channel.Interface.Group) + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Group" value="4"> + <tp:docstring> + A user-defined contact list (see Channel.Interface.Group) + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:simple-type name="Handle" type="u" array-name="Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a + handle</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Contact_Handle" type="u" + array-name="Contact_Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Contact</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Room_Handle" type="u" + array-name="Room_Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Room</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="List_Handle" type="u" + array-name="List_Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_List</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Group_Handle" type="u" + array-name="Group_Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Group</tp:docstring> + </tp:simple-type> + + <method name="RequestHandles" tp:name-for-bindings="Request_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer has its reference-counting effect.</tp:changed> + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + The type of handle required + </tp:docstring> + </arg> + + <arg direction="in" name="Identifiers" type="as"> + <tp:docstring> + An array of identifiers of entities to request handles for + </tp:docstring> + </arg> + + <arg direction="out" type="au" tp:type="Handle[]" + name="Handles"> + <tp:docstring> + An array of integer handle numbers in the same order as the given identifiers. + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request several handles from the connection manager which represent a + number of contacts, rooms or server-stored lists on the service.</p> + + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + the handles remain valid until the connection disconnects.</p> + + <p>The implementation of this method in older connection managers + must record that these handles are in use by the + client who invokes this method, and must not deallocate the handles + until the client disconnects from the bus or calls the + <tp:member-ref>ReleaseHandles</tp:member-ref> + method. Where the identifier refers to an entity that already has a + handle in this connection manager, this handle should be returned + instead. The handle number 0 must not be returned by the connection + manager.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The given identifier does not identify a valid entity of the given + type. + + <tp:rationale> + For instance, an XMPP connection would raise this error for + identifiers with type Handle_Type_Room that do not contain + exactly one '@' character, that contain spaces, and so on. + </tp:rationale> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The given handle type is not valid, or is not implemented on this + connection. + + <tp:rationale> + For instance, a connection to a protocol that doesn't have + chat rooms would raise this error for room handles, and all CMs + would raise this error for Handle_Type_None. + </tp:rationale> + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u"> + <tp:enumvalue suffix="Connected" value="0"> + <tp:docstring> + The connection is fully connected and all methods are available. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connecting" value="1"> + <tp:docstring> + <tp:member-ref>Connect</tp:member-ref> has been called but the + connection has not yet been established. Some methods may fail + until the connection has been established. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Disconnected" value="2"> + <tp:docstring> + If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or + <tp:member-ref>Status</tp:member-ref>, it indicates that connection + has not yet been attempted. If seen in a + <tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates + that the connection has failed; the Connection object SHOULD be + removed from D-Bus immediately, and all subsequent method calls + SHOULD fail. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Connection_Status_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why the status of the connection changed. Apart from + Requested, the values of this enumeration only make sense as + reasons why the status changed to Disconnected.</p> + </tp:docstring> + + <tp:enumvalue suffix="None_Specified" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There is no reason set for this state change. Unknown status + reasons SHOULD be treated like this reason.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Requested" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is in response to a user request. Changes to the + Connecting or Connected status SHOULD always indicate this reason; + changes to the Disconnected status SHOULD indicate this reason + if and only if the disconnection was requested by the user.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Network_Error" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was an error sending or receiving on the network socket.</p> + + <p>When the status changes from Connecting to Disconnected for this + reason, the equivalent D-Bus error is either + <code>org.freedesktop.Telepathy.Error.NetworkError</code>, + <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>, + <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code> + or some more specific error.</p> + + <p>When the status changes from Connected to Disconnected for this + reason, the equivalent D-Bus error is either + <code>org.freedesktop.Telepathy.Error.NetworkError</code>, + <code>org.freedesktop.Telepathy.Error.ConnectionLost</code> + or some more specific error.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Authentication_Failed" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The username or password was invalid.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Encryption_Error" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was an error negotiating SSL on this connection, or + encryption was unavailable and require-encryption was set when the + connection was created.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code> + if encryption was not available at all, or + <code>org.freedesktop.Telepathy.Error.EncryptionError</code> + if encryption failed.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Name_In_Use" value="5"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>In general, this reason indicates that the requested account + name or other identification could not be used due to conflict + with another connection. It can be divided into three cases:</p> + + <ul> + <li>If the status change is from Connecting to Disconnected + and the 'register' parameter to RequestConnection was present + and true, the requested account could not be created on the + server because it already exists. + The equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>. + </li> + + <li>If the status change is from Connecting to Disconnected + but the 'register' parameter is absent or false, the connection + manager could not connect to the specified account because + a connection to that account already exists. + The equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>. + + <tp:rationale> + In some protocols, like XMPP (when connecting with the same + JID and resource as an existing connection), the existing + connection "wins" and the new one fails to connect. + </tp:rationale> + </li> + + <li>If the status change is from Connected to Disconnected, + the existing connection was automatically disconnected because + a new connection to the same account (perhaps from a different + client or location) was established. + The equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>. + + <tp:rationale> + In some protocols, like MSNP (when connecting twice with the + same Passport), the new connection "wins" and the + existing one is automatically disconnected. + </tp:rationale> + </li> + </ul> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Not_Provided" value="6"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server did not provide a SSL certificate.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Untrusted" value="7"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is signed by an untrusted certifying + authority. This error SHOULD NOT be used to represent a self-signed + certificate: use the more specific Cert_Self_Signed reason for + that.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Expired" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate has expired.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Not_Activated" value="9"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is not yet valid.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate did not match its hostname.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate does not have the expected + fingerprint.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Self_Signed" value="12"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is self-signed.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Other_Error" value="13"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was some other error validating the server's SSL + certificate.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Revoked" value="14"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate has been revoked.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Insecure" value="15"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate uses an insecure algorithm, + or is cryptographically weak.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code> + </p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="ConnectionError" tp:name-for-bindings="Connection_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when an error occurs that renders this connection unusable. + </p> + + <p>Whenever this signal is emitted, it MUST immediately be followed by + a <tp:member-ref>StatusChanged</tp:member-ref> signal with status + Connection_Status_Disconnected and an appropriate reason + code.</p> + + <p>Connection managers SHOULD emit this signal on disconnection, but + need not do so. Clients MUST support connection managers that emit + StatusChanged(Disconnected, ...) without first emitting + ConnectionError.</p> + + <tp:rationale> + <p>This signal provides additional information about the reason + for disconnection. The reason for connection is always + straightforward - it was requested - so it does not need further + explanation. However, on errors, it can be useful to provide + additional information.</p> + + <p>The <tp:type>Connection_Status_Reason</tp:type> is not given + here, since it will be signalled in + <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client + implementation would be to store the information given by this + signal until StatusChanged is received, at which point the + information given by this signal can be used to supplement the + StatusChanged signal.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring> + The name of a D-Bus error describing the error that occurred, + which may correspond to a + <tp:type>Connection_Status_Reason</tp:type>, or may be a more + specific Telepathy error + (such as + <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code> + for Connection_Status_Reason_Network_Error) + or a protocol-specific or connection-manager-specific error in a + suitable namespace. + + <tp:rationale> + For instance, a SIP connection manager could signal + "402 Payment Required" as an error in a + connection-manager-specific namespace, or a link-local + XMPP implementation that used Avahi could provide the error + given to it by the avahi-daemon. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about the error, which may include + the following well-known keys:</p> + + <dl> + <dt>debug-message (s)</dt> + <dd>Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt> + <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd> + </dl> + + </tp:docstring> + </arg> + + </signal> + + <signal name="StatusChanged" tp:name-for-bindings="Status_Changed"> + <arg name="Status" type="u" tp:type="Connection_Status"> + <tp:docstring> + An integer indicating the new status, as defined by ConnectionStatus + </tp:docstring> + </arg> + + <arg name="Reason" type="u" tp:type="Connection_Status_Reason"> + <tp:docstring> + An integer indicating the reason for the status change, as defined + by ConnectionStatusReason + </tp:docstring> + </arg> + + <tp:docstring> + Emitted when the status of the connection changes. All states and + reasons have numerical values, as defined in ConnectionStatus + and ConnectionStatusReason. + </tp:docstring> + </signal> + + <tp:contact-attribute name="contact-id" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same string that would be returned by + <tp:member-ref>InspectHandles</tp:member-ref>. As a special case, + this is always present in the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>, + whether it was explicitly requested or not.</p> + </tp:docstring> + </tp:contact-attribute> + + <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest"> + <tp:added version="0.21.3"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Register a client's interest in notifications related to one or + more interfaces.</p> + + <p>Groups of notifications are identified by a token which is either + a D-Bus interface name, or a string that starts with a D-Bus + interface name. The meaning of each token is given by that D-Bus + interface, which MUST define it in its documentation.</p> + + <tp:rationale> + <p>Initially, all interests are in entire interface, but allowing + other strings allows subscription to part of an interface; for + instance, an interest in ...MailNotification/count could track + the number of messages without caring about their detailed + content.</p> + </tp:rationale> + + <p>For each token with which this method interacts, the + Connection tracks an "interest count" (like a reference count) for + each unique bus name that has called this method. When a client + calls this method, for each token, the interest count for its + unique bus name is incremented; when + <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, + all interest counts for that unique bus name are decremented. + If the unique bus name leaves the bus (for instance, if the + client crashes or exits), all interest counts for that unique bus + name are set to zero.</p> + + <p>The Connection can then use these reference counts to + avoid subscribing to protocol-level notifications unless at least + one client has a non-zero interest count for the relevant + token.</p> + + <tp:rationale> + <p>This method exists to reduce memory and network overhead when + there is no active subscription.</p> + + <p>One situation where this is useful is <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >Location</tp:dbus-ref>: on XMPP, location updates are received + over PEP. If the Connection advertises the + <code>geoloc+notify</code> capability, it will be sent location + updates for all contacts. To avoid consuming resources for this, + the connection should avoid advertising that capability until + a client has expressed an interest in contacts' locations.</p> + + <p>Another example of a protocol that benefits from this method is + the Google XMPP Mail Notification extension, which can be used + to implement <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >MailNotification</tp:dbus-ref>. In this protocol, the CM + receives a notification that something has changed, but to get + more information, the CM must request this information. Knowing + that nobody is currently interested in this information, the CM + can avoid generating useless network traffic. Similarly, the CM + may free the list of unread messages to reduce memory overhead.</p> + </tp:rationale> + + <p>If this method is called for an interface that might require + protocol-level subscription, but the connection cannot set up + that subscription yet (for instance because the + <tp:member-ref>Status</tp:member-ref> is not Connected yet), the + Connection MUST remember the client's interest, and attempt to + subscribe to the appropriate protocol feature when this becomes + possible.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reason it could fail is if it's unimplemented, in which + case the only thing the client can usefully do is to proceed as if + it had succeeded.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces in which to register an + interest, represented by either a + <tp:type>DBus_Interface</tp:type>, or a string prefixed with a + <tp:type>DBus_Interface</tp:type>.</p> + + <p>If the Connection does not support one of these tokens, this + is not considered to be an error; the unsupported token is + simply ignored.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveClientInterest" + tp:name-for-bindings="Remove_Client_Interest"> + <tp:added version="0.21.3"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Release an interest registered using + <tp:member-ref>AddClientInterest</tp:member-ref>. See that + method's documentation for details.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reasons it could fail are if it's unimplemented, or if + the client's reference-counting is wrong and it has tried to + remove a client interest that it did not add. In both cases, + there's nothing the client could do about it.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces that were previously passed to + <tp:member-ref>AddClientInterest</tp:member-ref>.</p> + </tp:docstring> + </arg> + </method> + + <property name="HasImmortalHandles" + tp:name-for-bindings="Has_Immortal_Handles" + access="read" type="b"> + <tp:added version="0.21.6"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if handles last for the whole lifetime of the Connection. + This SHOULD be the case in all connection managers, but clients + MUST interoperate with older connection managers + (which reference-count handles).</p> + </tp:docstring> + </property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This models a connection to a single user account on a communication + service. Its basic capability is to provide the facility to request and + receive channels of differing types (such as text channels or streaming + media channels) which are used to carry out further communication.</p> + + <p>In order to allow Connection objects to be discovered by new clients, + the object path and well-known bus name MUST be of the form + <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code> + and + <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code> + where:</p> + + <ul> + <li><em>cmname</em> is the same + <tp:type>Connection_Manager_Name</tp:type> that appears + in the connection manager's object path and well-known bus name</li> + <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>, + but with "-" replaced with "_" to get a valid + object path/bus name</li> + <li><em>account</em> is some non-empty sequence of ASCII letters, + digits and underscores not starting with a digit</li> + </ul> + + <p><em>account</em> SHOULD be formed such that any valid distinct + connection instance on this protocol has a distinct name. This + might be formed by including the server name followed by the user + name (escaped via some suitable mechanism like telepathy-glib's + tp_escape_as_identifier() function to preserve uniqueness); on + protocols where connecting multiple times is permissable, a + per-connection identifier might be necessary to ensure + uniqueness.</p> + + <p>Clients MAY parse the object path to determine the connection + manager name and the protocol, but MUST NOT attempt to parse the + <em>account</em> part. Connection managers MAY use any unique string + for this part.</p> + + <p>As well as the methods and signatures below, arbitrary interfaces may be + provided by the Connection object to represent extra connection-wide + functionality, such as the Connection.Interface.SimplePresence for + receiving and + reporting presence information, and Connection.Interface.Aliasing for + connections where contacts may set and change an alias for themselves. + These interfaces can be discovered using the + <tp:member-ref>GetInterfaces</tp:member-ref> method.</p> + + <p>Contacts, rooms, and server-stored lists (such as subscribed contacts, + block lists, or allow lists) on a service are all represented by + immutable <em>handles</em>, which are unsigned non-zero integers which are + valid only for the lifetime of the connection object, and are used + throughout the protocol where these entities are represented, allowing + simple testing of equality within clients.</p> + + <p>Zero as a handle value is sometimes used as a "null" value to mean + the absence of a contact, room, etc.</p> + + <p>Handles have per-type uniqueness, meaning that + every (handle type, handle number) tuple is guaranteed to be unique within + a connection and that a handle alone (without its type) is meaningless or + ambiguous. Connection manager implementations should reference count these + handles to determine if they are in use either by any active clients or any + open channels, and may deallocate them when this ceases to be true. Clients + may request handles of a given type and identifier with the + <tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity + identifier with the <tp:member-ref>InspectHandles</tp:member-ref> + method, keep handles from being released with + <tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no + longer storing handles with + <tp:member-ref>ReleaseHandles</tp:member-ref>.</p> + </tp:docstring> + + <tp:changed version="0.17.10">Previously, the account part of + Connection bus names/object paths was allowed to have more than one + component (i.e. contain dots or slashes), resulting in Connection + bus names and object paths with more than 7 components. We now restrict + Connection bus names/object paths to have exactly 7 + components.</tp:changed> + + <tp:changed version="0.17.23">The Requests and Contacts interfaces + are now mandatory. Their functionality will be merged into the main + Connection interface at some point in future.</tp:changed> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Future.xml b/spec/Connection_Future.xml new file mode 100644 index 0000000..6b5291e --- /dev/null +++ b/spec/Connection_Future.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<node name="/Connection_FUTURE" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.FUTURE" + tp:causes-havoc='experimental'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar"> + <tp:added version="0.19.0">(as a draft)</tp:added> + + <arg direction="in" name="Main_Interface" type="s" + tp:type="DBus_Interface"> + <tp:docstring> + The "primary" interface implemented by an object attached + to a connection. For example, a Gabble plugin implementing + fine-grained control of XEP-0016 privacy lists might expose an object + implementing <tt>com.example.PrivacyLists</tt>. + </tp:docstring> + </arg> + + <arg direction="out" name="Path" type="o"> + <tp:docstring>The object path of the sidecar, exported by the same bus + name as the Connection to which it is attached.</tp:docstring> + </arg> + <arg direction="out" name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring>Immutable properties of the sidecar.</tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request an object with a particular interface providing additional + connection-specific functionality, together with its immutable + properties. These will often be implemented by plug-ins to the + connection managers; for example, support for an XMPP XEP for which + no generic Telepathy interface exists might be implemented by a + Gabble plugin exposing a sidecar with a particular interface.</p> + + <p>This method may be called at any point during the lifetime of a + connection, even before its <tp:type>Connection_Status</tp:type> + changes to Connected. It MAY take a long time to + return—perhaps it needs to wait for a connection to be established + and for all the services supported by the server to be discovered + before determining whether necessary server-side support is + available—so callers SHOULD override the default method timeout (25 + seconds) with a much higher value (perhaps even MAX_INT32, meaning + “no timeout” in recent versions of libdbus).</p> + + <tp:rationale> + <p>There is an implicit assumption that any connection + manager plugin will only want to export one “primary” object per + feature it implements, since there is a one-to-one mapping between + interface and object. This is reasonable since Sidecars are + (intended to be) analogous to extra interfaces on the connection, + providing once-per-connection shared functionality; it also makes + client code straightforward (look up the interface you care about + in a dictionary, build a proxy object from the value). More + “plural” plugins are likely to want to implement new types of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> + instead.</p> + </tp:rationale> + </tp:docstring> + + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested sidecar is not implemented by this connection manager, + or a necessary server-side component does not exist. (FIXME: split + these two errors out? Then again, once we list the guaranteed and + possible sidecars on a Protocol object, clients can tell the + difference themselves, because they shouldn't be calling this in the + first case.) + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + A server-side component needed by the requested sidecar reported it + is currently too busy, or did not respond for some + implementation-defined time. The caller may wish to try again later. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.Cancelled"> + <tp:docstring> + The connection was disconnected while the sidecar was being set up. + </tp:docstring> + </tp:error> + </method> + + </interface> +</node> diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml new file mode 100644 index 0000000..497c6d0 --- /dev/null +++ b/spec/Connection_Interface_Addressing.xml @@ -0,0 +1,258 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser + General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public License + along with this library; if not, write to the Free Software Foundation, + Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> + <tp:added version="0.19.12">(as draft)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface deals with the multiple address types that can + refer to the same contact, such as vCard fields and URIs.</p> + + <p>It can be used to retrieve contacts with a specific addresses + through <tp:member-ref>GetContactsByVCardField</tp:member-ref> and + <tp:member-ref>GetContactsByURI</tp:member-ref>, as well as + defining the various addressing methods for a given contact + through this interface's contact attributes.</p> + </tp:docstring> + + <method name="GetContactsByVCardField" + tp:name-for-bindings="Get_Contacts_By_VCard_Field"> + <arg direction="in" name="Field" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard field of the addresses we are requesting. The + field name SHOULD be in lower case. Supported + fields can be found in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p> + + <p>The <code>url</code> vCard field MUST NOT appear here; see + <tp:member-ref>GetContactsByURI</tp:member-ref> instead.</p> + + <tp:rationale> + <p>In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.</p> + </tp:rationale> + + </tp:docstring> + </arg> + <arg direction="in" name="Addresses" type="as"> + <tp:docstring> + The addresses to get contact handles for. The address types + should match the given vCard field. + </tp:docstring> + </arg> + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.</p> + + <p>Attributes from this interface and from + <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> + are always returned, and need not be requested + explicitly.</p> + + <p>The behavior of this parameter is similar to the same + parameter in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>Requested addresses that cannot be satisfied MUST be ommitted + from the mapping.</p> + + <p>Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>), + and the vCard field used for requesting the contact in + <code>org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info</code>. + </p> + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request contacts and retrieve their attributes using a given field + in their vCards.</p> + + <p>The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> + method.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <method name="GetContactsByURI" + tp:name-for-bindings="Get_Contacts_By_URI"> + <arg direction="in" name="URIs" type="as"> + <tp:docstring> + The URI addresses to get contact handles for. Supported + schemes can be found in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableURISchemes</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.</p> + + <p>Attributes from this interface and from + <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> + are always returned, and need not be requested + explicitly.</p> + + <p>The behavior of this parameter is similar to the same + parameter in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>Requested URIs that cannot be satisfied MUST be ommitted + from the mapping.</p> + + <p>Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>). + </p> + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request contacts and retrieve their attributes using URI addresses.</p> + + <p>The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> + method.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <tp:mapping name="VCard_Field_Address_Map" array-name=""> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping of vCard fields and addresses that repreent + the given contact.</p> + </tp:docstring> + <tp:member type="s" name="VCard_Field"/> + <tp:member type="s" name="Address"/> + </tp:mapping> + + <tp:contact-attribute name="addresses" type="a{ss}" + tp:type="VCard_Field_Address_Map"> + <tp:docstring> + The various vCard addresses that identify this contact. + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="uris" type="as"> + <tp:docstring> + The various URI addresses that identify this contact. + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="requested-address" type="(ss)" + tp:type="Requested_Address"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact's address, as it was requested + through <tp:member-ref>GetContactsByVCardField</tp:member-ref>. This + attribute MUST be ommitted if the contact was not retrieved + through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p> + <tp:rationale> + <p>When retrieving more than one contact + through <tp:member-ref>GetContactsByVCardField</tp:member-ref>, + there needs to be a way to map the given contact back o the + original request.</p> + </tp:rationale> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="requested-uri" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact's URI, as it was requested through + <tp:member-ref>GetContactsByURI</tp:member-ref>. This + attribute MUST be ommitted if the contact was not retrieved + through <tp:member-ref>GetContactsByURI</tp:member-ref>.</p> + <tp:rationale> + <p>When retrieving more than one contact + through <tp:member-ref>GetContactsByURI</tp:member-ref>, + there needs to be a way to map the given contact back o the + original request.</p> + </tp:rationale> + </tp:docstring> + </tp:contact-attribute> + + <tp:struct name="Requested_Address" array-name=""> + <tp:docstring> + The address that has been requested by + <tp:member-ref>GetContactsByVCardField</tp:member-ref> or + <tp:member-ref>GetContactsByURI</tp:member-ref>. + </tp:docstring> + + <tp:member name="Field" type="s"> + <tp:docstring> + The vCard field used in <tp:member-ref>GetContactsByVCardField</tp:member-ref>. + </tp:docstring> + </tp:member> + + <tp:member name="Address" type="s"> + <tp:docstring> + The address that was requested. + </tp:docstring> + </tp:member> + + </tp:struct> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml new file mode 100644 index 0000000..9675771 --- /dev/null +++ b/spec/Connection_Interface_Aliasing.xml @@ -0,0 +1,185 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Aliasing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Aliasing"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:mapping name="Alias_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are aliases.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:mapping> + + <tp:struct name="Alias_Pair" array-name="Alias_Pair_List"> + <tp:docstring> + A pair (contact handle, alias) as seen in the + <tp:member-ref>AliasesChanged</tp:member-ref> signal. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:struct> + + <signal name="AliasesChanged" tp:name-for-bindings="Aliases_Changed"> + <arg name="Aliases" type="a(us)" tp:type="Alias_Pair[]"> + <!-- FIXME: if we break API, this could be an Alias_Map, a{us} --> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array containing structs of: + <ul> + <li>the handle representing the contact</li> + <li>the new alias</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when a contact's alias (or that of the user) is changed. + </tp:docstring> + </signal> + <tp:flags name="Connection_Alias_Flags" value-prefix="Connection_Alias_Flag" type="u"> + <tp:flag suffix="User_Set" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The aliases of contacts on this connection may be changed by the + user of the service, not just by the contacts themselves. This is + the case on Jabber, for instance.</p> + <p>It is possible that aliases can be changed by the contacts too - + which alias takes precedence is not defined by this + specification, and depends on the server and/or connection manager + implementation.</p> + <p>This flag only applies to the aliases of "globally valid" contact + handles. At this time, clients should not expect to be able to + change the aliases corresponding to any channel-specific + handles. If this becomes possible in future, a new flag will + be defined.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + <method name="GetAliasFlags" tp:name-for-bindings="Get_Alias_Flags"> + <arg direction="out" type="u" tp:type="Connection_Alias_Flags" + name="Alias_Flags"> + <tp:docstring> + An integer with a bitwise OR of flags from ConnectionAliasFlags + </tp:docstring> + </arg> + <tp:docstring> + Return a bitwise OR of flags detailing the behaviour of aliases on this + connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + <method name="RequestAliases" tp:name-for-bindings="Request_Aliases"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as" name="Aliases"> + <tp:docstring> + A list of aliases in the same order as the contact handles + </tp:docstring> + </arg> + <tp:docstring> + Request the value of several contacts' aliases at once. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + <method name="GetAliases" tp:name-for-bindings="Get_Aliases"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="a{us}" tp:type="Alias_Map" name="Aliases"> + <tp:docstring> + A dictionary mapping contact handles to aliases + </tp:docstring> + </arg> + <tp:docstring> + Request the value of several contacts' aliases at once. This SHOULD + only return cached aliases, falling back on the contact identifier + (i.e. the string corresponding to the handle) if none is present. Also + if there was no cached alias, a request SHOULD be started of which the + result is later signalled by + <tp:member-ref>AliasesChanged</tp:member-ref>. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + <method name="SetAliases" tp:name-for-bindings="Set_Aliases"> + <arg direction="in" name="Aliases" type="a{us}" tp:type="Alias_Map"> + <tp:docstring> + A dictionary mapping integer handles of contacts + to strings of the new alias to set. + </tp:docstring> + </arg> + <tp:docstring> + Request that the alias of the given contact be changed. Success will be + indicated by emitting an <tp:member-ref>AliasesChanged</tp:member-ref> + signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is + not set, this method will only ever succeed if the contact is the + user's own handle (as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:contact-attribute name="alias" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same string that would be returned by + <tp:member-ref>GetAliases</tp:member-ref> + (always present with some value, possibly the + same as Connection/contact-id, if information from the + Aliasing interface was requested) + </p> + </tp:docstring> + </tp:contact-attribute> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols where contacts have an + alias which they can change at will. Provides a method for the user to set + their own alias, and a signal which should be emitted when a contact's + alias is changed or first discovered.</p> + + <p>On connections where the user is allowed to set aliases for contacts and + store them on the server, the <tp:member-ref>GetAliasFlags</tp:member-ref> + method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the + <tp:member-ref>SetAliases</tp:member-ref> method may be called on contact + handles other than the user themselves.</p> + + <p>Aliases are intended to be used as the main displayed name for the + contact, where available.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml new file mode 100644 index 0000000..704263c --- /dev/null +++ b/spec/Connection_Interface_Anonymity.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Anonymity" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity"> + <tp:added version="0.19.7">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface to support anonymity settings on a per-connection basis. + This defines what personal identifying information a remote contact + may or may not see. For example, GSM might use this for CLIR, while + SIP might use this for privacy service requests.</p> + </tp:docstring> + + <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u"> + <tp:docstring> + <p>Flags for the various types of anonymity modes. These modes are solely to + inform the CM of the desired anonymous settings. It is up to the + CM to determine whether the anonymity modes should be handled within + the CM itself, or whether the network that a CM might be talking to + should be enforcing anonymity.</p> + + <p>CMs MAY support only a subset of these modes, and specific + connections MAY support none at all.</p> + </tp:docstring> + + <tp:flag value="1" suffix="Client_Info"> + <tp:docstring> + <p>Obscure any information that provides user identification, + user-agent identification or personal details. Examples of this + information might be GSM CallerID, SIP from address, various + informational email headers, etc.</p> + + <p>The CM should scrub/replace any of this information before + passing messages or data onto the network. Note that a CM which + has the option of obscuring the information at the CM or privacy + service level would choose both (anonymity services are opaque + to clients of this interface).</p> + + <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. + If they are set, the CM MUST respect Client_Info and ignore + Show_Client_Info.</p> + </tp:docstring> + </tp:flag> + + <tp:flag value="2" suffix="Show_Client_Info"> + <tp:docstring> + <p>Explicitly request showing of client information. In connection + context, this can be used to override service default. In channel + context, this overrides connection anonymity modes.</p> + + <tp:rationale> + <p>In GSM, it's possible to have CLIR enabled by default, and + explicitly suppress CLIR for a single phone call.</p> + </tp:rationale> + + <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. + If they are set, the CM MUST respect Client_Info and ignore + Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info + in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate + its support for explicitly hiding and publicising client information. + </p> + </tp:docstring> + </tp:flag> + + <tp:flag value="4" suffix="Network_Info"> + <tp:docstring> + <p>Obscure any originating IP address information, contact URIs, + and anonymize all traffic involved with sending/receiving any + media streams or call content. + Examples of this include the "headers" portions of + <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as + well as the History-Info (described in + <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>) + for a SIP CM.</p> + + <p>This SHOULD have the effect of hiding address information from + the remote contact (ie, the contact cannot know what IP address + the session is originated from). Obviously the network still needs + to be able to route information between contacts, so this provides + no guarantees of what can be seen by intermediaries.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + + <property name="SupportedAnonymityModes" type="u" access="read" + tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes"> + <tp:docstring> + The anonymity modes supported by the CM for this connection. Once + Connection.Status has moved to Connected, this property MUST NOT change. + </tp:docstring> + </property> + + <property name="AnonymityMandatory" type="b" access="readwrite" + tp:name-for-bindings="Anonymity_Mandatory" + tp:is-connection-parameter='yeah'> + <tp:docstring> + <p>This specifies whether or not the anonymity settings MUST be respected + by the CM and any intermediaries between the local and remote contacts. + If this is set to true but anonymity settings cannot be followed, then + the session MUST be denied with a + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>WouldBreakAnonymity</tp:error-ref></code> + error. + Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref> + SHOULD also set this property first (rather than accepting the CM's + default value).</p> + </tp:docstring> + </property> + + <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" + access="readwrite" tp:name-for-bindings="Anonymity_Modes" + tp:is-connection-parameter='yeah'> + <tp:docstring> + <p>The currently enabled anonymity modes for the connection. Setting + has the effect of requesting new modes for the connection, and may + raise an error if the unsupported modes are set. Successfully changing + the modes will result in emission of + <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + An unsupported mode was supplied. Supported modes are specified + in the SupportedAnonymityModes property, and this should be + checked prior to setting AnonymityModes. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </property> + + <signal name="AnonymityModesChanged" + tp:name-for-bindings="Anonymity_Modes_Changed"> + <tp:docstring> + Emitted when the anonymity mode has changed. + </tp:docstring> + + <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags"> + <tp:docstring> + The new anonymity modes for this connection. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml new file mode 100644 index 0000000..3b9290e --- /dev/null +++ b/spec/Connection_Interface_Avatars.xml @@ -0,0 +1,516 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Avatars" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:simple-type name="Avatar_Token" type="s" + array-name="Avatar_Token_List"> + <tp:changed version="0.17.16">strengthened uniqueness requirements + so (CM name, protocol, token) is unique; previously only + (our Account, remote contact identifier, token) was required to be + unique</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An opaque token chosen by the connection manager, representing + a particular avatar.</p> + + <tp:rationale> + <p>Because avatars can be relatively large images, most protocols + provide a way to detect whether an old avatar is still valid, + or whether an avatar has changed, without pushing the actual + avatar data to all clients.</p> + </tp:rationale> + + <p>The connection manager MUST choose these tokens in a way that + makes it highly unlikely that two different avatars with the same + connection manager and protocol will have the same token.</p> + + <tp:rationale> + <p>This means that clients MAY use the triple + (<tp:type>Connection_Manager_Name</tp:type>, + <tp:type>Protocol</tp:type>, avatar token) as a key for + their avatar cache. For instance, an avatar for a + telepathy-gabble Jabber contact might be stored in a file + .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.</p> + </tp:rationale> + + <p>For instance, some protocols (like XMPP) identify avatars by a + hash of the avatar data; in this case, the hash can be used as the + avatar token.</p> + + <p>Some protocols identify avatars by the timestamp of the last + change to the avatar; in these protocols it would be necessary for + the connection manager to encode both the timestamp and the + contact's identifier into the avatar token in order to ensure + uniqueness.</p> + + <p>This token SHOULD be kept short and reasonably suitable for use + in a filename, but MAY contain any UTF-8 character (so clients using + avatar tokens in filenames MUST be prepared to escape characters + that are not valid in filenames). Connection managers for protocols + where tokens would otherwise become inconveniently large or contain + many unsuitable characters SHOULD hash the identifying data to + generate the token.</p> + </tp:docstring> + </tp:simple-type> + + <tp:mapping name="Avatar_Token_Map"> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are avatar tokens.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="Avatar_Token" name="Token"/> + </tp:mapping> + + <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact whose avatar has changed + </tp:docstring> + </arg> + <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s"> + <tp:docstring> + Unique token for their new avatar + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the avatar for a contact has been updated, or first + discovered on this connection. If the token differs from the token + associated with the client's cached avatar for this contact, the new + avatar should be requested with + <tp:member-ref>RequestAvatars</tp:member-ref>. + </tp:docstring> + </signal> + + <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose avatar has been retrieved + </tp:docstring> + </arg> + <arg name="Token" tp:type="Avatar_Token" type="s"> + <tp:docstring> + The token corresponding to the avatar + </tp:docstring> + </arg> + <arg name="Avatar" type="ay"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg name="Type" type="s"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the avatar for a contact has been retrieved. + </tp:docstring> + </signal> + + <property name="SupportedAvatarMIMETypes" + tp:name-for-bindings="Supported_Avatar_MIME_Types" + type="as" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + An array of supported MIME types (e.g. "image/jpeg"). + Clients MAY assume that the first type in this array is preferred. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarHeight" + tp:name-for-bindings="Minimum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum height in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarWidth" + tp:name-for-bindings="Minimum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum width in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="RecommendedAvatarHeight" + tp:name-for-bindings="Recommended_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended height in pixels of an avatar on this protocol, or 0 if + there is no preferred height. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + In XMPP a recommended width is given by the protocol specification; + in proprietary protocols, using the same avatar size as the + proprietary client is likely to lead to the best display to other + users. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RecommendedAvatarWidth" + tp:name-for-bindings="Recommended_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended width in pixels of an avatar on this protocol, or 0 if + there is no preferred width. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + The rationale is the same as for + <tp:member-ref>RecommendedAvatarHeight</tp:member-ref>. + </tp:rationale> + </tp:docstring> + </property> + + <property name="MaximumAvatarHeight" + tp:name-for-bindings="Maximum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum height in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarWidth" + tp:name-for-bindings="Maximum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum width in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarBytes" + tp:name-for-bindings="Maximum_Avatar_Bytes" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum size in bytes of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <method name="GetAvatarRequirements" + tp:name-for-bindings="Get_Avatar_Requirements"> + <tp:deprecated version="0.17.22">Use GetAll to retrieve the + D-Bus properties on this interface, falling back to this method + on failure.</tp:deprecated> + <arg direction="out" type="as" name="MIME_Types"> + <tp:docstring> + An array of supported MIME types (eg image/jpeg) + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Min_Width"> + <tp:docstring> + The minimum image width in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Min_Height"> + <tp:docstring> + The minimum image height in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Max_Width"> + <tp:docstring> + The maximum image width in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Max_Height"> + <tp:docstring> + The maximum image height in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="u" name="Max_Bytes"> + <tp:docstring> + The maximum image size in bytes, or 0 if there is no limit + </tp:docstring> + </arg> + <tp:docstring> + Get the required format of avatars on this connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="GetAvatarTokens" tp:name-for-bindings="Get_Avatar_Tokens"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as" name="Tokens" tp:type="Avatar_Token[]"> + <tp:docstring> + An array of avatar tokens or empty strings (if no avatar is set) in the + same order as the given array of contact handles + </tp:docstring> + </arg> + <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens + instead.</tp:deprecated> + <tp:docstring> + Get the unique tokens for all of the given contacts' avatars. + + Using this method in new Telepathy clients is deprecated; use + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="GetKnownAvatarTokens" + tp:name-for-bindings="Get_Known_Avatar_Tokens"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="a{us}" name="Tokens" tp:type="Avatar_Token_Map"> + <tp:docstring> + A dictionary of handles mapped to avatar tokens, containing only + the known avatar tokens. + </tp:docstring> + </arg> + <tp:docstring> + Get the unique tokens for the given contacts' avatars. These tokens + can be persisted across connections, and should be used by the client + to check whether the avatars have been updated. For handles other than + the self handle, only tokens that are already known are returned; an + empty token means the given contact has no avatar. However, a CM must + always have the tokens for the self handle if one is set (even if it is + set to no avatar). On protocols where the avatar does not persist + between connections, a CM should omit the self handle from the returned + map until an avatar is explicitly set or cleared. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="RequestAvatar" tp:name-for-bindings="Request_Avatar"> + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact to request the avatar for + </tp:docstring> + </arg> + <arg direction="out" type="ay" name="Data"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg direction="out" type="s" name="MIME_Type"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> + <tp:deprecated version="0.15.5">Use RequestAvatars + instead.</tp:deprecated> + <tp:docstring> + Request the avatar for a given contact. Using this method in new + Telepathy clients is deprecated; use RequestAvatars instead. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact does not currently have an avatar. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestAvatars" tp:name-for-bindings="Request_Avatars"> + <arg direction="in" name="Contacts" type="au" + tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts to retrieve avatars for + </tp:docstring> + </arg> + <tp:docstring> + Request avatars for a number of contacts. The + <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for + each avatar retrieved. If the handles are valid but retrieving an + avatar fails (for any reason, including the contact not having an + avatar) the AvatarRetrieved signal is not emitted for that contact. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="SetAvatar" tp:name-for-bindings="Set_Avatar"> + <arg direction="in" name="Avatar" type="ay"> + <tp:docstring> + An array of bytes representing the avatar image data + </tp:docstring> + </arg> + <arg direction="in" name="MIME_Type" type="s"> + <tp:docstring> + A string representing the image MIME type + </tp:docstring> + </arg> + <arg direction="out" type="s" name="Token" tp:type="Avatar_Token"> + <tp:docstring> + The string token of the new avatar + </tp:docstring> + </arg> + <tp:docstring> + Set a new avatar image for this connection. The avatar image must + respect the requirements obtained by + <tp:member-ref>GetAvatarRequirements</tp:member-ref>. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="ClearAvatar" tp:name-for-bindings="Clear_Avatar"> + <tp:added version="0.15.0" /> + <tp:docstring> + Remove the avatar image for this connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same string that would be returned by + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + (omitted from the result if the contact's avatar token is not known, + present as an empty string if the contact is known not to have + an avatar). Unlike in the + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + method, the avatar tokens for the self handle aren't required to be + present. This attribute should not be used to determine whether or + not the Avatar needs to be set. + </p> + </tp:docstring> + </tp:contact-attribute> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for requesting avatars for contacts on a given connection, + receiving notification when avatars are changed, and publishing your own + avatar.</p> + + <p>Avatars are identified by a string, the <tp:type>Avatar_Token</tp:type>, + which represents a particular avatar. Tokens MUST be chosen by the + connection manager in such a way that the triple + (<tp:type>Connection_Manager_Name</tp:type>, <tp:type>Protocol</tp:type>, + <tp:type>Avatar_Token</tp:type>) uniquely identifies an avatar. + An empty token means that an avatar has not been set for this contact, and + a changed token implies the contact's avatar has changed, but the strings + should otherwise be considered opaque by clients.</p> + + <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + to request the tokens for the + avatars of all the contacts it is interested in when it connects. The + avatars can then be requested using + <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts. Clients + should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and + request a new copy of + the avatar when a contacts' avatar token changes. Clients should cache the + token and data of each contact's avatar between connections, to avoid + repeatedly retrieving the same avatar.</p> + + <p>To publish an avatar, a client should use + <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets + the requirements returned by the + <tp:member-ref>GetAvatarRequirements</tp:member-ref> + function. On some protocols the avatar is stored on the server, so setting + the avatar is persistent, but on others it is transferred via a peer to + peer mechanism, so needs to be set every connection. Hence, on every + connection, clients should inspect the avatar token of the connection's + self handle using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; if + the self handle is not in the + returned map, the client should re-set the avatar. If the self handle's + avatar token is known, but the avatar has been changed locally since the + last connection, the client should upload the new avatar; if the avatar has + not changed locally, then the client should download the avatar from the + server if its token differs from the that of the local avatar.</p> + + <p>To remove the published avatar on protocols which have persistent avatars, + a client should use the <tp:member-ref>ClearAvatar</tp:member-ref> method. + This method can safely be used even if there is no avatar for this + connection.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Balance.xml b/spec/Connection_Interface_Balance.xml new file mode 100644 index 0000000..76f9040 --- /dev/null +++ b/spec/Connection_Interface_Balance.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Balance" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Balance"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.19.0">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>In many real-time communication services the user can pay for certain + services, typically calls to the + <abbr title="Public Switched Telephone Network">PSTN</abbr>, + in advance. In (at least) Skype, it's possible to query the current + balance in a machine-readable way.</p> + </tp:docstring> + + <tp:struct name="Currency_Amount"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An amount of money in a specified currency. For example, + 3.21 British pounds would conventionally be represented by + (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>, + <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by + (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>, + <var>Currency</var> = <tt>"GBP"</tt>) in a service that records + balance in units of 0.001 pounds.</p> + + <p>As a special case, if <var>Amount</var> = <tt>0</tt>, + <var>Scale</var> = <tt>2**32 - 1</tt> (i.e. the largest possible + 32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this + indicates an unknown amount.</p> + </tp:docstring> + + <tp:member type="i" name="Amount"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The amount, expressed as a fixed-point number with decimal scale + defined by the <var>Scale</var> field; for instance, an + <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of + <tt>2</tt> represents 12.34 in the currency unit given by the + <var>Currency</var> field.</p> + </tp:docstring> + </tp:member> + <tp:member type="u" name="Scale"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The decimal scale for the fixed point value of the + <var>Amount</var> field, defining the number of rightmost decimal + digits from the integer value which form the fractional part of the + resulting currency value.</p> + + <p>As well as defining the interpretation of <var>Amount</var>, user + interfaces may use this value to determine the precision with which + to display the amount.</p> + </tp:docstring> + </tp:member> + <tp:member type="s" name="Currency"> + <tp:docstring> + The currency code represented by this amount, which SHOULD be an + international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>, + or <tt>"JPY"</tt> if possible. An empty string can be used to + indicate that the currency is not known. + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="AccountBalance" tp:name-for-bindings="Account_Balance" + access="read" type="(ius)" tp:type="Currency_Amount"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user's balance on the account corresponding to this <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. + A negative amount may be possible on some services, and indicates + that the user owes money to the service provider.</p> + + <p>On initial connection, this property may have an unknown + value, represented by <var>Amount</var> = <tt>0</tt>, + <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit + unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p> + </tp:docstring> + </property> + + <signal name="BalanceChanged" tp:name-for-bindings="Balance_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the user's balance has changed.</p> + </tp:docstring> + + <arg name="Balance" type="(ius)" tp:type="Currency_Amount"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new value of the <tp:member-ref>AccountBalance</tp:member-ref> + property.</p> + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml new file mode 100644 index 0000000..8e5eb33 --- /dev/null +++ b/spec/Connection_Interface_Capabilities.xml @@ -0,0 +1,254 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections where it is possible to know what channel + types may be requested before the request is made to the connection + object. Each capability represents a commitment by the connection + manager that it will ordinarily be able to create a channel when given + a request with the given type and handle.</p> + + <p>Capabilities pertain to particular contact handles, and represent + activities such as having a text chat or a voice call with the user. + The activities are represented by the D-Bus interface name of the + channel type for that activity.</p> + + <p>The generic capability flags are defined by + <tp:type>Connection_Capability_Flags</tp:type>.</p> + + <p>In addition, channel types may have type specific capability flags of + their own, which are described in the documentation for each channel + type.</p> + + <p>This interface also provides for user interfaces notifying the + connection manager of what capabilities to advertise for the user. This + is done by using the + <tp:member-ref>AdvertiseCapabilities</tp:member-ref> method, and deals + with the + interface names of channel types and the type specific flags pertaining + to them which are implemented by available client processes.</p> + </tp:docstring> + + <tp:changed version="0.17.8">Previously, this interface + also expressed capabilities of the connection itself, indicating what + sorts of channels could be requested (for instance, the ability to + open chatroom lists or chatrooms). However, this was never very + well-defined or consistent, and as far as we know it was never + implemented correctly. This usage is now deprecated.</tp:changed> + + <tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> + instead.</tp:deprecated> + <tp:changed version="0.19.8">Connection managers implementing + Capabilities MUST implement ContactCapabilities too.</tp:changed> + + <tp:flags name="Connection_Capability_Flags" + value-prefix="Connection_Capability_Flag" type="u"> + <tp:flag suffix="Create" value="1"> + <tp:docstring> + The given channel type and handle can be given to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> + to create a new channel of this type. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Invite" value="2"> + <tp:docstring> + The given contact can be invited to an existing channel of this type. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:struct name="Capability_Pair" array-name="Capability_Pair_List"> + <tp:docstring>A pair (channel type, type-specific flags) as passed to + <tp:member-ref>AdvertiseCapabilities</tp:member-ref> on the + Capabilities interface.</tp:docstring> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" name="Type_Specific_Flags"/> + </tp:struct> + + <tp:struct name="Contact_Capability" array-name="Contact_Capability_List"> + <tp:docstring>A struct (contact handle, channel type, generic flags, + type-specific flags) representing a capability posessed by a contact, + as returned by <tp:member-ref>GetCapabilities</tp:member-ref> on the + Capabilities interface.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="Generic_Flags"/> + <tp:member type="u" name="Type_Specific_Flags"/> + </tp:struct> + + <tp:struct name="Capability_Change" array-name="Capability_Change_List"> + <tp:docstring>A struct (contact handle, channel type, old generic flags, + new generic flags, old type-specific flags, new type-specific flags) + representing a change to one of a contact's capabilities, as seen in the + <tp:member-ref>CapabilitiesChanged</tp:member-ref> signal on the + Capabilities interface.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="Old_Generic_Flags"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="New_Generic_Flags"/> + <tp:member type="u" name="Old_Type_Specific_Flags"/> + <tp:member type="u" name="New_Type_Specific_Flags"/> + </tp:struct> + + <method name="AdvertiseCapabilities" + tp:name-for-bindings="Advertise_Capabilities"> + <arg direction="in" name="Add" type="a(su)" tp:type="Capability_Pair[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>a string channel type</li> + <li>a bitwise OR of type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <arg direction="in" name="Remove" type="as" tp:type="DBus_Interface[]"> + <tp:docstring> + An array of D-Bus interface names of channel types to remove + </tp:docstring> + </arg> + <arg direction="out" type="a(su)" tp:type="Capability_Pair[]" + name="Self_Capabilities"> + <tp:docstring> + An array of structures describing the current capabilities containing: + <ul> + <li>a string channel type</li> + <li>a bitwise OR of type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used by user interfaces to indicate which channel types they are able + to handle on this connection. Because these may be provided by + different client processes, this method accepts channel types to add + and remove from the set already advertised on this connection. The type + of advertised capabilities (create versus invite) is protocol-dependent + and hence cannot be set by the this method. In the case of a client + adding an already advertised channel type but with new channel type + specific flags, the connection manager should simply add the new flags + to the set of advertised capabilities.</p> + + <p>Upon a successful invocation of this method, the + <tp:member-ref>CapabilitiesChanged</tp:member-ref> + signal will be emitted for the user's own handle ( <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>) + by the connection manager to indicate the changes + that have been made. This signal should also be monitored to ensure + that the set is kept accurate - for example, a client may remove + capabilities or type specific capability flags when it exits + which are still provided by another client.</p> + + <p>On connections managed by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>, + this method SHOULD NOT be used by clients other than the + ChannelDispatcher itself.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <signal name="CapabilitiesChanged" + tp:name-for-bindings="Capabilities_Changed"> + <arg name="Caps" type="a(usuuuu)" tp:type="Capability_Change[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>an integer handle representing the contact</li> + <li>a string channel type</li> + <li>a bitwise OR of the contact's old generic capability flags</li> + <li>a bitwise OR of the contact's new generic capability flags</li> + <li>a bitwise OR of the contact's old type specific capability flags</li> + <li>a bitwise OR of the contact's new type specific capability flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Announce that there has been a change of capabilities on the + given handle.</p> + + <p>If the handle is zero, the capabilities refer to the connection + itself, in some poorly defined way. This usage is deprecated and + clients should ignore it.</p> + </tp:docstring> + </signal> + + <method name="GetCapabilities" tp:name-for-bindings="Get_Capabilities"> + <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of contact handles for this connection.</p> + + <p>This may include zero, which originally meant a query for + capabilities available on the connection itself. This usage + is deprecated; clients SHOULD NOT do this, and connection managers + SHOULD proceed as though zero had not been present in this + list.</p> + </tp:docstring> + </arg> + <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]" + name="Contact_Capabilities"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>an integer handle representing the contact</li> + <li>a string channel type</li> + <li>a bitwise OR of generic capability flags for the type</li> + <li>a bitwise OR of type specific capability flags for the type</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of capabilities for the given contact handles. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The handle does not represent a contact and is not zero + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:contact-attribute name="caps" + type="a(usuu)" tp:type="Contact_Capability[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same structs that would be returned by + <tp:member-ref>GetCapabilities</tp:member-ref> + (all of them will redundantly have the contact's handle as the + first member). Omitted from the result if the contact's capabilities + are not known; present in the result as an empty array if the + contact is known to have no capabilities at all.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml new file mode 100644 index 0000000..99a3602 --- /dev/null +++ b/spec/Connection_Interface_Cellular.xml @@ -0,0 +1,131 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Cellular" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular"> + <tp:added version="0.19.8">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface is for various cellular things (GSM and/or CDMA) that + aren't really applicable to other protocols.</p> + </tp:docstring> + + <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period" + type="u" access="readwrite" + tp:is-connection-parameter='yup'> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Define how long should the service centre try message delivery before + giving up, failing delivery and deleting the message. A value of 0 + means to use the service centre's default period.</p> + + <p>The value specified is in seconds. Note that various protocols or + implementations may round the value up (eg. to a minute or hour + precision). The maximum validity period may vary depending on + protocol or provider.</p> + </tp:docstring> + </property> + + <property name="OverrideMessageServiceCentre" + tp:name-for-bindings="Override_Message_Service_Centre" + type="b" access="readwrite" + tp:is-connection-parameter='can i get a hell yeah?'> + <tp:added version='0.19.12'>Previously, as an undocumented + feature, setting <tp:member-ref>MessageServiceCentre</tp:member-ref> + to the empty string caused the SIM's default SMSC to be used.</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <code>True</code>, SMSes will be sent via the service centre + specified by <tp:member-ref>MessageServiceCentre</tp:member-ref>. If + <code>False</code>, the SIM's default SMSC will be used, ignoring the + value of MessageServiceCentre.</p> + + <tp:rationale> + <p>It could be desirable for a configuration interface to remember + the user's previous choice of custom SMSC, even if it's not in use. + This boolean allows that choice to be saved as an account parameter + by Mission Control, rather than the UI needing to save it elsewhere + to be restored if the user wants to reactivate it.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre" + type="s" access="readwrite" + tp:is-connection-parameter='HELL YEAH!!!'> + <tp:changed version='0.19.12'>This property's value is now + ignored unless + <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is + <code>True</code>.</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + + <p>Address for the messaging service centre. Typically (as is the case + for GSM's SMSC), it's the ISDN / telephony address (ie. a phone + number). If + <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is + <code>False</code>, this property's value should be ignored by the CM + in favour of the SIM's default SMSC.</p> + </tp:docstring> + </property> + + <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The International Mobile Subscriber Identifier, if it exists. This + would originate from a SIM card. If the IMSI is unknown, this will + contain an empty string ("").</p> + </tp:docstring> + </property> + + <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed"> + <tp:docstring> + Emitted when the IMSI for the connection changes. This sort of thing + is rare, but could happen on cellular phones that allow hot-swapping + of SIM cards. In the case of SIM swapping, this signal would be + emitted twice; the first time while the SIM is being ejected (with an + empty string), and the second time after a new SIM has been inserted + (assuming that the IMSI can be determined from the new SIM). + </tp:docstring> + + <arg name="IMSI" type="s"> + <tp:docstring> + The new IMSI value. This may be an empty string in the case where + the IMSI is being reset or removed. + </tp:docstring> + </arg> + </signal> + + <property name="MessageReducedCharacterSet" + tp:name-for-bindings="Message_Reduced_Character_Set" + type="b" access="readwrite" + tp:is-connection-parameter='no... just kidding! yes!'> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Determines whether SMSes containing characters that do not fit into + a 7‐bit GSM character set should be sent as UCS‐2, or lossily + recoded. If <code>False</code> (which SHOULD be the default), + messages will be sent with no loss of fidelity (at the potential + financial cost of using twice as many SMSes); if <code>True</code>, + the message will be recoded in an implementation‐specific way to fit + into a country‐specific GSM reduced character set.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 0000000..9790856 --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,218 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Client_Types" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ClientTypes"> + <tp:added version="0.21.1">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols which allows users to + subscribe to the client types of their contacts.</p> + + <p>One can connect to instant messaging networks on a huge variety of + devices, from PCs, to phones to consoles. It can be useful for users + to know what kind of device a contact is using so that he or she + can decide not to send that big file or start a video chat. This + interface exposes exactly this information for clients to display.</p> + + <p>The client types are represented in strings, using the values + <a href="http://xmpp.org/registrar/disco-categories.html#client"> + documented by the XMPP registrar</a> with some additional types + added for other protocols. A contact can set one or more client types + so this interface returns a list of strings to denote client types + for a contact. The well-known client types to be used are:</p> + + <ul> + <li>bot</li> + <li>console (minimal non-GUI client used on dumb terminals or + text-only screens, <strong>not</strong> a games console)</li> + <li>handheld</li> + <li>pc</li> + <li>phone</li> + <li>web</li> +<!-- Excluding these two because there's been no conclusion regarding my mail + to standards@xmpp.org about adding these two to their list: + + <li>sms (the client is not actually an instant messaging client + but all messages sent to this contact will be delivered as SMSs)</li> + <li>game (a gaming device)</li> +--> + </ul> + + <p>If the empty list is given as the client types, this means that + details about the contact's client types are unknown. If there are + multiple resources of a contact online at one point in time, the + client types of the most available resource will be returned. In + other words, the returned client types are those for the resource whose + presence will be retreived using the + <tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref> + interface.</p> + + <p>For example, if a contact has two resources:</p> + + <ul> + <li>their phone, with presence "available"; and</li> + <li>their pc, with presence "busy";</li> + </ul> + + <p>then the methods in this interface will return an array (with + one element: "phone") as the client types because that is the more + available resource. If at some later time the contact's phone's presence + changes to "away", the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + notify that the contact's client types attribute has changed from + ["phone"] to ["pc"], + because "busy" is a more available presence than "away".</p> + + </tp:docstring> + + <tp:mapping name="Contact_Client_Types"> + <tp:docstring> + A mapping from contact handle to client types. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact. + </tp:docstring> + </tp:member> + <tp:member type="as" name="Client_Types" tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types as documented earlier in this interface. + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types"> + <tp:docstring> + Return the client types of the given contacts, if they are + already known. If any of the given contacts' client types are + not known, request their current client types, but return + immediately without waiting for a reply; if a reply with a + non-empty client type array is later received for those + contacts, the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + be emitted for them. + + <tp:rationale> + This method is appropriate for "lazy" client type finding, for instance + displaying the client types (if available) of everyone in your contact + list. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose client types should be returned or signalled. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="a{uas}" + tp:type="Contact_Client_Types"> + <tp:docstring> + The contacts' client types, if already known. Contacts whose client + types are not already known are omitted from the mapping; contacts known + to have no client type information appear in the mapping with an empty + list. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RequestClientTypes" tp:name-for-bindings="Request_Client_Types"> + <tp:docstring> + Return the current client types of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + <tp:rationale> + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose client types should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="as" + tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types. It MAY be empty, indicating that no client + type information was found. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + The requested contact does not allow the local user to see their + client type information. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated"> + <tp:docstring> + Emitted when a contact's client types change or become known. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact. + </tp:docstring> + </arg> + <arg name="Client_Types" type="as" tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types, or an empty list to indicate that nothing + is known about the contact's client types. + </tp:docstring> + </arg> + </signal> + + <tp:contact-attribute name="client-types" type="as" + tp:type="Contact_Client_Type[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetClientTypes</tp:member-ref> for this contact. + Omitted from the result if the contact's client types are not + known.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:simple-type name="Contact_Client_Type" type="s" + array-name="Contact_Client_Type_List"> + <tp:docstring>A string representing a single client type of a + contact.</tp:docstring> + </tp:simple-type> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml new file mode 100644 index 0000000..31343de --- /dev/null +++ b/spec/Connection_Interface_Communication_Policy.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Communication_Policy" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Connection.Interface.CommunicationPolicy.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.21.1">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + This interface supports controlling which contacts are allowed + to initiate text chats, incoming calls, and other forms of + communication as supported by the underlying protocol. The + policies supported for different communication methods on this + connection are listed in the + <tp:member-ref>SupportedPolicies</tp:member-ref> property. The + current configuration is held in + <tp:member-ref>ActivePolicies</tp:member-ref>; it can be modified + using <tp:member-ref>SetPolicy</tp:member-ref>, and changes + are signalled by <tp:member-ref>PolicyChanged</tp:member-ref>. + </p> + </tp:docstring> + + <tp:mapping name="Active_Policies_Map"> + <tp:docstring> + A mapping of communication methods (channel types), and their + associated policy. + </tp:docstring> + + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"> + <tp:docstring> + The channel interface with the policy. + </tp:docstring> + </tp:member> + + <tp:member type="(uv)" tp:type="Access_Control" name="Active_Policy"> + <tp:docstring> + The active policy for this channel type. + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="SupportedPolicies" + tp:name-for-bindings="Supported_Policies" access="read" + type="a(asau)" tp:type="Supported_Policy[]"> + <tp:docstring> + The communication policies supported by this connection. + </tp:docstring> + </property> + + <property name="ActivePolicies" tp:name-for-bindings="Active_Policies" + access="read" type="a{s(uv)}" tp:type="Active_Policies_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The active communication policies on this + connection. Communication methods that are not in this + mapping are considered open.</p> + + <p>For example, to allow incoming calls only from contacts + buddy list, and to allow text messages from anyone, + the policy would look like this:</p> + + <pre> +{ + 'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open, + 'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List +} + </pre> + + <p>Changes to this property are signalled by + <tp:member-ref>PolicyChanged</tp:member-ref>.</p> + </tp:docstring> + </property> + + <method name="SetPolicy" tp:name-for-bindings="Set_Policy"> + <tp:docstring> + Set a policy for a communication method (channel + type). Depending on the server or protocol, more than one + communication method could be bound to the same policy, if + calling this method on one channel type changes the policy on + another channel type, the <tp:member-ref>PolicyChanged</tp:member-ref> + signal that would follow would include all the channel types + that have an altered policy. + </tp:docstring> + <arg name="Channel_Type" direction="in" type="s" + tp:type="DBus_Interface"> + <tp:docstring> + The channel type to set the policy for. + </tp:docstring> + </arg> + <arg name="Policy" direction="in" type="(uv)" + tp:type="Access_Control"> + <tp:docstring> + The policy to set for this channel. + </tp:docstring> + </arg> + </method> + + <signal name="PolicyChanged" tp:name-for-bindings="Policy_Changed"> + <tp:docstring> + <tp:member-ref>ActivePolicies</tp:member-ref> has + changed. This occurs when the server unilaterally changed the + policy or <tp:member-ref>SetPolicy</tp:member-ref> has been + called. + </tp:docstring> + <arg name="Changed_Policies" type="a{s(uv)}" + tp:type="Active_Policies_Map"> + <tp:docstring> + A subset of the active policies that have changed. + </tp:docstring> + </arg> + </signal> + + <tp:struct name="Supported_Policy" array-name="Supported_Policy_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The communication methods (channel types), and the policies + that can be applied to them. This is server and protocol + dependant.</p> + + <p>Grouped channel types will always have the same policy applied + to them.</p> + + <tp:rationale> + Different protocols have different limitations to the + granularity of communication policies. One protocol might be + able to set a different policy for VoIP calls and text chat, + while another protocol might only be able to set one policy + to both VoIP and text chat. + </tp:rationale> + </tp:docstring> + <tp:member type="as" tp:type="DBus_Interface[]" + name="Channel_Types"> + <tp:docstring> + A list of channel interfaces that support these policies. + </tp:docstring> + </tp:member> + <tp:member type="au" tp:type="Access_Control_Type[]" + name="Supported_Policies"> + <tp:docstring> + A list of supported policies. + </tp:docstring> + </tp:member> + </tp:struct> + + </interface> +</node> diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml new file mode 100644 index 0000000..fb13c37 --- /dev/null +++ b/spec/Connection_Interface_Contact_Capabilities.xml @@ -0,0 +1,306 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006, 2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006, 2008 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.28">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Contact capabilities describe the channel classes which may be + created with a given contact in advance of attempting to create a + channel. Each capability represents a commitment by the + connection manager that it will ordinarily be able to create a channel + with a contact when given a request with the properties defined by the + channel class.</p> + + <p>Capabilities pertain to particular contact handles, and represent + activities such as having a text chat, a voice call with the user or a + stream tube of a defined type.</p> + + <p>This interface also enables user interfaces to notify the connection + manager what capabilities to advertise for the user to other contacts. + This is done by using the + <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p> + + <tp:rationale> + <p>XMPP is a major user of this interface: XMPP contacts will not, + in general, be callable using VoIP unless they advertise suitable + Jingle capabilities.</p> + + <p>Many other protocols also have some concept of capability flags, + which this interface exposes in a protocol-independent way.</p> + </tp:rationale> + </tp:docstring> + + <tp:struct name="Handler_Capabilities" + array-name="Handler_Capabilities_List"> + <tp:docstring> + A structure representing the capabilities of a single client. + </tp:docstring> + + <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name"> + <tp:docstring> + For implementations of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Client</tp:dbus-ref> + interface, the well-known bus name name of the client; for any other + process, any other reversed domain name that uniquely identifies it. + </tp:docstring> + </tp:member> + + <tp:member name="Channel_Classes" type="aa{sv}" + tp:type="String_Variant_Map[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of channel classes that can be handled by this client. + This will usually be a copy of the client's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + property. + </tp:docstring> + </tp:member> + + <tp:member name="Capabilities" + type="as" tp:type="Handler_Capability_Token[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of client capabilities supported by this client, to be + used by the connection manager to determine what capabilities to + advertise. This will usually be a copy of the client's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> + property. + </tp:docstring> + </tp:member> + </tp:struct> + + <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Alter the connection's advertised capabilities to include + the intersection of the given clients' capabilities with what the + connection manager is able to implement.</p> + + <p>On connections managed by the ChannelDispatcher, processes other + than the ChannelDispatcher SHOULD NOT call this method, and the + ChannelDispatcher SHOULD use this method to advertise the + capabilities of all the registered <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref> + implementations.On connections not managed by the ChannelDispatcher, + clients MAY use this method directly, to indicate the channels they + will handle and the extra capabilities they have.</p> + + <p>Upon a successful invocation of this method, the connection manager + will only emit the + <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal + for the user's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">SelfHandle</tp:dbus-ref> + if, in the underlying protocol, the new capabilities are distinct + from the previous state.</p> + + <tp:rationale> + <p>The connection manager will essentially intersect the provided + capabilities and the channel classes it implements. Therefore, + certain properties which are never fixed for a channel class + (such as the target handle, or the Parameters property of a tube + channel) will almost certainly not be advertised.</p> + </tp:rationale> + + <p>This method MAY be called on a newly-created connection while it + is still in the DISCONNECTED state, to request that when the + connection connects, it will do so with the appropriate + capabilities. Doing so MUST NOT fail.</p> + </tp:docstring> + + <arg direction="in" name="Handler_Capabilities" type="a(saa{sv}as)" + tp:type="Handler_Capabilities[]"> + <tp:docstring> + <p>The capabilities of one or more clients.</p> + + <p>For each client in the given list, any capabilities previously + advertised for the same client name are discarded, then replaced by + the capabilities indicated.</p> + + <p>As a result, if a client becomes unavailable, this method SHOULD + be called with a <tp:type>Handler_Capabilities</tp:type> structure + containing its name, an empty list of channel classes, and an + empty list of capabilities. When this is done, the connection + manager SHOULD free all memory associated with that client name.</p> + + <tp:rationale> + <p>This method takes a list of clients so that + when the channel dispatcher first calls it (with a list of all + the Handlers that are initially available), the changes can be + made atomically, with only one transmission of updated + capabilities to the network. Afterwards, the channel dispatcher + will call this method with a single-element list every time + a Handler becomes available or unavailable.</p> + </tp:rationale> + + <p>The connection manager MUST ignore any channel classes and client + capabilities for which there is no representation in the protocol + or no support in the connection manager.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="GetContactCapabilities" + tp:name-for-bindings="Get_Contact_Capabilities"> + <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of contact handles for this connection.</p> + + <p>The handle zero MUST NOT be included in the request.</p> + </tp:docstring> + </arg> + <arg direction="out" type="a{ua(a{sv}as)}" + tp:type="Contact_Capabilities_Map" name="Contact_Capabilities"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from contact handles to lists of requestable channel + classes, representing the channel requests that are expected + to succeed for that contact.</p> + + <p>Contacts listed among Handles whose capabilities are unknown + SHOULD be omitted from this map; contacts known to have an empty + set of capabilities SHOULD be included in the keys of this map, + with an empty array as the corresponding value.</p> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Returns an array of requestable channel classes for the given + contact handles, representing the channel requests that are + expected to succeed.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The handle does not represent a contact. Zero is always invalid. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="ContactCapabilitiesChanged" + tp:name-for-bindings="Contact_Capabilities_Changed"> + <arg name="caps" type="a{ua(a{sv}as)}" + tp:type="Contact_Capabilities_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + All the capabilities of the contacts + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Announce that there has been a change of capabilities on the + given handles. A single signal can be emitted for several + contacts.</p> + + <tp:rationale> + <p>The underlying protocol can get several contacts' capabilities at + the same time.</p> + </tp:rationale> + + </tp:docstring> + </signal> + + <tp:mapping name="Contact_Capabilities_Map" + array-name="Contact_Capabilities_Map_List"> + <tp:docstring>A mapping from contact handle to their capabilities. + </tp:docstring> + <tp:member type="u" name="Key" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle. + </tp:docstring> + </tp:member> + <tp:member type="a(a{sv}as)" name="Value" + tp:type="Requestable_Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact's capabilities. These should be represented + in the same way as in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref>, + except that they may have more fixed properties or fewer allowed + properties, to represent contacts who do not have all the + capabilities of the connection.</p> + + <p>In particular, requestable channel classes for channels with + target handle type Contact MUST list <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> among their fixed properties when + they appear here, and clients MAY assume that this will be the + case.</p> + + <tp:rationale> + <p>This matches the initial implementations - service-side in + telepathy-gabble, and client-side in telepathy-qt4 - and means + that clients can use exactly the same code to interpret + RequestableChannelClasses and contact capabilities.</p> + </tp:rationale> + + <p>Channel classes with target handle type Handle_Type_Contact + indicate that a request that matches the channel class, and also + either has the contact's handle as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref> or the contact's identifier as + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref>, can be expected to succeed. Connection + managers SHOULD NOT include the TargetHandle or TargetID as a + fixed property in contact capabilities.</p> + + <tp:rationale> + <p>This makes one channel class sufficient to describe requests via + TargetHandle or TargetID, and is necessary in order to allow + clients to interpret RequestableChannelClasses and contact + capabilities with the same code.</p> + </tp:rationale> + + <p>Channel classes with target handle type Handle_Type_Room or + Handle_Type_None indicate that if a channel matching the channel + class is created, then inviting the contact to that channel + can be expected to succeed.</p> + + <tp:rationale> + <p>To support room-based XMPP protocols like + <a href="http://telepathy.freedesktop.org/wiki/Muji">Muji</a> + and MUC Tubes, it's necessary to be able to discover who can be + invited to a given room channel; most XMPP contacts won't + support being invited into a Muji conference call, at least + in the short to medium term.</p> + </tp:rationale> + + <p>No interpretation is defined for channel classes with any other + target handle type, or for channel classes that do not fix a + target handle type, in this version of the Telepathy + specification.</p> + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:contact-attribute name="capabilities" + type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same structs that would be returned by + <tp:member-ref>GetContactCapabilities</tp:member-ref>. + Omitted from the result if the contact's capabilities + are not known; present in the result as an empty array if the + contact is known to have no capabilities at all.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml new file mode 100644 index 0000000..5282a82 --- /dev/null +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -0,0 +1,549 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/> + <tp:added version="0.21.0">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections in which contacts can be placed in + user-defined groups.</p> + + <p>The most basic functionality of this interface is to list and monitor + a contact's set of groups. To do this, use the + <tp:member-ref>GroupsChanged</tp:member-ref> signal, and the + <tp:token-ref>groups</tp:token-ref> contact attribute (this should + usually be done by connecting to the GroupsChanged signal, then + calling <tp:dbus-ref + namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref> with this interface + included in the Interfaces argument). Simple user interfaces can + limit themselves to displaying that information, and ignore the rest + of this interface: to ensure that this works, + <tp:member-ref>GroupsChanged</tp:member-ref> is emitted for every + change, even if that change could be inferred from another signal + such as <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> + + <p>Looking at contacts' lists of groups is sufficient to present a + user interface resembling XMPP's data model, in which groups behave + like tags applied to contacts, and so an empty group cannot exist + or is not interesting. However, some protocols model groups as + objects in their own right. User interfaces may either track + the set of groups via the <tp:member-ref>Groups</tp:member-ref> + property and the <tp:member-ref>GroupsCreated</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals, or ignore + this extra information.</p> + + <p>Similarly, in some protocols it is possible to rename a group as + a single atomic operation. Simpler user interfaces will + see the new name being created, the old name being removed, and the + members moving to the new name, via the signals described above. + More advanced user interfaces can optionally distinguish between an + atomic rename and a create/remove pair, and display renamed groups + differently, by monitoring the + <tp:member-ref>GroupRenamed</tp:member-ref> signal.</p> + + <p>This interface also provides various methods to manipulate + user-defined groups, which can be expected to work if + <tp:member-ref>GroupStorage</tp:member-ref> is not None.</p> + + <p>Depending on the protocol, some methods might be implemented by + more than one protocol operation; for instance, in a + "contact-centric" protocol like XMPP, + <tp:member-ref>SetContactGroups</tp:member-ref> is a single + protocol operation and <tp:member-ref>SetGroupMembers</tp:member-ref> + requires a protocol operation per contact, whereas in a more + "group-centric" protocol it might be the other way around. User + interfaces SHOULD call whichever method most closely resembles the + way in which the user's action was represented in the UI, and + let the connection manager deal with the details.</p> + </tp:docstring> + + <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups" + access="read" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if each contact can be in at most one group; false if each + contact can be in many groups.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <property name="GroupStorage" tp:name-for-bindings="Group_Storage" + type="u" tp:type="Contact_Metadata_Storage_Type" access="read"> + <tp:docstring> + <p>Indicates the extent to which contacts' groups can be set and + stored.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <tp:contact-attribute name="groups" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The names of groups of which a contact is a member.</p> + + <p>Change notification is via + <tp:member-ref>GroupsChanged</tp:member-ref>; clients can also + get extra context for group membership changes by receiving + <tp:member-ref>GroupRenamed</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> + </tp:docstring> + </tp:contact-attribute> + + <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed"> + <tp:docstring> + Emitted when contacts' groups change. + </tp:docstring> + + <arg name="Contact" type="au" tp:type="Contact_Handle"> + <tp:docstring>The relevant contacts.</tp:docstring> + </arg> + + <arg name="Added" type="as"> + <tp:docstring>The names of groups to which the contacts were + added.</tp:docstring> + </arg> + + <arg name="Removed" type="as"> + <tp:docstring>The names of groups from which the contacts were + removed.</tp:docstring> + </arg> + </signal> + + <property name="Groups" type="as" access="read" + tp:name-for-bindings="Groups"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The names of all groups that currently exist. This may be a + larger set than the union of all contacts' <code>groups</code> + contact attributes, if the connection allows groups to be + empty.</p> + + <p>Change notification is via + <tp:member-ref>GroupsCreated</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref>; clients can also + distinguish between a create/remove pair and a renamed group by + receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p> + + <p>This property's value is not meaningful until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> has become Success.</p> + </tp:docstring> + </property> + + <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created"> + <tp:docstring> + Emitted when new, empty groups are created. This will often be + followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that + add some members. + </tp:docstring> + + <arg name="Names" type="as"> + <tp:docstring>The names of the new groups.</tp:docstring> + </arg> + </signal> + + <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a group is renamed, in protocols where this can + be distinguished from group creation, removal and membership + changes.</p> + + <p>Immediately after this signal is emitted, + <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the + creation of a group with the new name, and + <tp:member-ref>GroupsRemoved</tp:member-ref> MUST signal the + removal of a group with the old name.</p> + + <tp:rationale> + <p>Emitting these extra signals, in this order, means that clients + that are interested in the set of groups that exist (but treat a + rename and a create/remove pair identically) can ignore the + GroupRenamed signal entirely.</p> + </tp:rationale> + + <p>If the group was not empty, immediately after those signals are + emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal + that the members of that group were removed from the old name + and added to the new name.</p> + + <p>On connection managers where groups behave like tags, renaming a + group MAY be signalled as a set of + <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsRemoved</tp:member-ref> and + <tp:member-ref>GroupsChanged</tp:member-ref> signals, instead of + emitting this signal.</p> + + <tp:rationale> + <p>On protocols like XMPP, another resource "renaming a group" is + indistinguishable from changing contacts' groups individually.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Old_Name" type="s"> + <tp:docstring>The old name of the group.</tp:docstring> + </arg> + + <arg name="New_Name" type="s"> + <tp:docstring>The new name of the group.</tp:docstring> + </arg> + </signal> + + <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when one or more groups are removed. If they had members at + the time that they were removed, then immediately after this signal + is emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal + that their members were removed.</p> + + <tp:rationale> + <p>Emitting the signals in this order allows for two modes of + operation. A client interested only in a contact's set of groups + can ignore <tp:member-ref>GroupsRemoved</tp:member-ref> and rely + on the <tp:member-ref>GroupsChanged</tp:member-ref> signal that + will follow; a more elaborate client wishing to distinguish between + all of a group's members being removed, and the group itself + being removed, can additionally watch for + <tp:member-ref>GroupsRemoved</tp:member-ref> and use it to + disambiguate.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Names" type="as"> + <tp:docstring>The names of the groups.</tp:docstring> + </arg> + </signal> + + <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given contact to the given groups (creating new groups + if necessary), and remove them from all other groups.</p> + + <tp:rationale> + <p>This is the easiest and most correct way to implement user + interfaces that display a single contact with a list of groups, + resulting in a user expectation that when they apply the changes, + the contact's set of groups will become exactly what was + displayed.</p> + </tp:rationale> + + <p>If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.</p> + + <tp:rationale> + <p>In protocols like XMPP where groups behave like tags, a group + with no members has no protocol representation.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> + <tp:docstring>The contact to alter.</tp:docstring> + </arg> + + <arg name="Groups" type="as" direction="in"> + <tp:docstring>The set of groups which the contact should be + in.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref> + is true and the list of groups has more than one + member.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given members to the given group (creating it if necessary), + and remove all other members.</p> + + <tp:rationale> + <p>This is the easiest and most correct way to implement user + interfaces that display a single group with a list of contacts, + resulting in a user expectation that when they apply the changes, + the groups's set of members will become exactly what was + displayed.</p> + </tp:rationale> + + <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, + this will also remove each member from their previous group.</p> + + <p>If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.</p> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members for the group. If this set is + empty, this method MAY remove the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + <method name="AddToGroup" tp:name-for-bindings="Add_To_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given members to the given group, creating it if + necessary.</p> + + <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, + this will also remove each member from their previous group.</p> + + <tp:rationale> + <p>This is good for user interfaces in which you can edit groups + via drag-and-drop.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members to include in the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove the given members from the given group.</p> + + <tp:rationale> + <p>This is good for user interfaces in which you can edit groups + via drag-and-drop.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter. If it does not exist, then it has + no members by definition, so this method SHOULD return + successfully.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members to remove from the group. It is not + an error to remove members who are already not in the group. + If there are no members left in the group afterwards, the group MAY + itself be removed.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + <method name="RemoveGroup" tp:name-for-bindings="Remove_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove all members from the given group, then remove the group + itself. If the group already does not exist, this method SHOULD + return successfully.</p> + + <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to remove.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + <method name="RenameGroup" tp:name-for-bindings="Rename_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Rename the given group.</p> + + <p>On protocols where groups behave like tags, this is an API + short-cut for adding all of the group's members to a group with + the new name, then removing the old group.</p> + + <tp:rationale> + <p>Otherwise, clients can't perform this operation atomically, even + if the connection could.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >ContactListState</tp:dbus-ref> changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList" + >GetContactListAttributes</tp:dbus-ref>.</p> + </tp:docstring> + + <arg name="Old_Name" type="s" direction="in"> + <tp:docstring>The group to rename.</tp:docstring> + </arg> + + <arg name="New_Name" type="s" direction="in"> + <tp:docstring>The new name for the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist"> + <tp:docstring>Raised if there is no group with that + name.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring>Raised if there is already a group with the new + name.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml new file mode 100644 index 0000000..527d325 --- /dev/null +++ b/spec/Connection_Interface_Contact_Info.xml @@ -0,0 +1,550 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Info" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2008 Nokia Corporation </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo"> + <tp:added version="0.19.4">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List"> + <tp:member type="s" name="Field_Name"> + <tp:docstring> + The name of the field; this is the lowercased name of a vCard field. + For example, a field representing a contact's address would be named + "adr". + </tp:docstring> + </tp:member> + <tp:member type="as" name="Parameters"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of vCard type parameters applicable to this field, with their + values. The type parameter names, and any values that are + case-insensitive in vCard, MUST be in lower case. For example, a + contact's preferred home address would have parameters + 'type=home' and 'type=pref'.</p> + + <tp:rationale> + The type parameter 'type' is likely to be the most common, but + there can be others, such as 'language=en'. + </tp:rationale> + + <p>Characters which are required to be escaped in vCard type + parameters should not be escaped in this list. For instance, + a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become + ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p> + + <tp:rationale> + This avoids Telepathy UIs having to understand the escaping and + unescaping rules for vCards. The type parameter name is not + allowed (by RFC 2425) to contain an '=' character, so no ambiguity + is introduced. + </tp:rationale> + </tp:docstring> + </tp:member> + <tp:member type="as" name="Field_Value"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For unstructured vCard fields (such as 'fn', a formatted name + field), a single-element array containing the field's value.</p> + + <p>For structured fields (such as 'adr', an address field), an array + corresponding to the semicolon-separated elements of the field (with + empty strings for empty elements).</p> + + <p>A vCard field with multiple comma-separated values, such as + 'nickname', should be represented by several + <tp:type>Contact_Info_Field</tp:type>s.</p> + + <p>Characters which are required to be escaped in vCard values, such as + semi-colons and newlines, should not be escaped in this list (e.g. if + a value contains a newline, the data passed over D-Bus should + contain a literal newline character).</p> + + <tp:rationale> + An earlier draft of this interface split structured vCard fields + into multiple Telepathy-level fields; for example, 'n' became + 'family-name', 'given-name', etc. But under this representation, + omitting empty components leads to difficulty identifying where one + name ends and another begins. Consider the fields ['given-name', + 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does + this represent two 'n' fields, or one with incorrect component + ordering? + </tp:rationale> + </tp:docstring> + </tp:member> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Represents one piece of information about a contact, as modelled by + a single vCard field. Of the fields defined in RFC 2426, common + examples include:</p> + + <dl> + <dt>fn</dt> + <dd>The contact's full name, formatted to their liking</dd> + + <dt>n</dt> + <dd>The contact's full name, divided into five parts: family name, + given name, additional names, honorific prefixes, and honorific + suffixes</dd> + + <dt>org</dt> + <dd>The contact's organisation, divided into the organization's name + possibly followed by one or more organizational unit names.</dd> + + <dt>adr</dt> + <dd>A street address for the contact, divided into seven components: + post office box, extended address, street address, locality (e.g., + city), region (e.g., state or province), the postal code, and the + country name.</dd> + + <dt>label</dt> + <dd>A free-form street address for the contact, formatted as a + single value (with embedded newlines where necessary) suitable for + printing on an address label</dd> + + <dt>tel</dt> + <dd>A telephone number for the contact.</dd> + + <dt>email</dt> + <dd>An email address for the contact.</dd> + </dl> + + <p>For example, the following vCard:</p> + + <pre> + BEGIN:vCard + VERSION:3.0 + FN:Wee Ninja + N;LANGUAGE=ja:Ninja;Wee;;;-san + ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement + ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire + ;CB2 1SJ;UK + LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ + TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753 + EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk + EMAIL;TYPE=INTERNET:wee.ninja@example.com + URL:http://www.thinkgeek.com/geektoys/plush/8823/ + NICKNAME:HR Ninja,Enforcement Ninja + END:vCard</pre> + + <p>would be represented by (in Python-like syntax):</p> + + <pre> +[ + ('fn', [], ['Wee Ninja']), + ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']), + ('org', [], ['Collabora, Ltd.', 'Management Division', + 'Human Resources; Company Policy Enforcement']), + ('adr', ['type=work','type=postal','type=parcel'], + ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']), + ('label', ['type=work','type=postal','type=parcel'], + ['''11 Kings Parade + Cambridge + Cambridgeshire + UK + CB2 1SJ''']), + ('tel', ['type=voice','type=work'], ['+44 1223 362967']), + ('tel', ['type=voice','type=work'], ['+44 7700 900753']), + ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']), + ('email', ['type=internet'], ['wee.ninja@example.com']), + ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']), + ('nickname', [], ['HR Ninja']), + ('nickname', [], ['Enforcement Ninja']) +]</pre> + </tp:docstring> + </tp:struct> + + <tp:mapping name="Contact_Info_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are contact information..</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="a(sasas)" tp:type="Contact_Info_Field[]" + name="Contact_Info"/> + </tp:mapping> + + <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact whose info has changed. + </tp:docstring> + </arg> + <arg name="ContactInfo" type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of fields representing information about this contact. + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a contact's information has changed or been received for + the first time on this connection. + </tp:docstring> + </signal> + + <method name="GetContactInfo" + tp:name-for-bindings="Get_Contact_Info"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts. + </tp:docstring> + </arg> + <arg direction="out" name="ContactInfo" type="a{ua(sasas)}" + tp:type="Contact_Info_Map"> + <tp:docstring> + A dictionary mapping contact handles to information, whose keys are + the subset of the requested list of handles for which information was + cached. + </tp:docstring> + </arg> + <tp:docstring> + Request information on several contacts at once. This SHOULD only + return cached information, omitting handles for which no information is + cached from the returned map. + </tp:docstring> + </method> + + <method name="RefreshContactInfo" + tp:name-for-bindings="Refresh_Contact_Info"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + Integer handles for contacts. + </tp:docstring> + </arg> + <tp:docstring> + Retrieve information for the given contact, requesting it from the + network if an up-to-date version is not cached locally. This method + SHOULD return immediately, emitting + <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts' + updated contact information is returned. + + <tp:rationale> + This method allows a client with cached contact information to + update its cache after a number of days. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RequestContactInfo" + tp:name-for-bindings="Request_Contact_Info"> + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for a contact. + </tp:docstring> + </arg> + <arg direction="out" name="Contact_Info" type="a(sasas)" + tp:type="Contact_Info_Field[]"> + <tp:docstring> + Information about that contact. + </tp:docstring> + </arg> + <tp:docstring> + Retrieve information for a contact, requesting it from the network if + it is not cached locally. + + <tp:rationale> + This method is appropriate for an explicit user request to show + a contact's information; it allows a UI to wait for the contact + info to be returned. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact's information could not be retrieved. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="SetContactInfo" tp:name-for-bindings="Set_Contact_Info"> + <tp:docstring> + Set new contact information for this connection, replacing existing + information. This method is only suppported if + <tp:member-ref>ContactInfoFlags</tp:member-ref> contains + <code>Can_Set</code>, and may only be passed fields conforming to + <tp:member-ref>SupportedFields</tp:member-ref>. + </tp:docstring> + <arg direction="in" name="ContactInfo" type="a(sasas)" + tp:type="Contact_Info_Field[]"> + <tp:docstring> + The new information to be set. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Setting your own information is not supported on this protocol. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The supplied fields do not match the restrictions specified by + <tp:member-ref>SupportedFields</tp:member-ref>. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:flags name="Contact_Info_Flags" value-prefix="Contact_Info_Flag" + type="u"> + <tp:docstring> + Flags defining the behaviour of contact information on this protocol. + Some protocols provide no information on contacts without an explicit + request; others always push information to the connection manager as + and when it changes. + </tp:docstring> + + <tp:flag suffix="Can_Set" value="1"> + <tp:docstring> + Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is + supported on this connection. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Push" value="2"> + <tp:docstring> + Indicates that the protocol pushes all contacts' information to the + connection manager without prompting. If set, + <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted + whenever contacts' information changes. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:simple-type name="VCard_Field" type="s"> + <tp:docstring> + A string naming a field in a vCard, such as "fn" or "adr". Although + these are case-insensitive in RFC 2425, in Telepathy they MUST be + normalized to lower case. In the terminology of RFC 2425 this is + called a "type name", and corresponds to the "name" production given + in the ABNF. + </tp:docstring> + </tp:simple-type> + + <tp:simple-type name="VCard_Type_Parameter" type="s" + array-name="VCard_Type_Parameter_List"> + <tp:docstring> + A type parameter as defined by RFC 2426, such as "type=cell" or + "language=en". + </tp:docstring> + </tp:simple-type> + + <property name="ContactInfoFlags" type="u" access="read" + tp:type="Contact_Info_Flags" tp:name-for-bindings="Contact_Info_Flags"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An integer representing the bitwise-OR of flags on this + connection.</p> + + <p>This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.</p> + + <tp:rationale> + <p>Some XMPP servers, like Facebook Chat, do not allow the vCard to + be changed (and so would not have the Can_Set flag). Whether the + user's server is one of these cannot necessarily be detected until + quite late in the connection process.</p> + </tp:rationale> + + </tp:docstring> + </property> + + <tp:struct name="Field_Spec" array-name="Field_Specs"> + <tp:docstring>A struct describing a vCard field, with parameters, that + may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this + Connection.</tp:docstring> + + <tp:member type="s" name="Name" tp:type="VCard_Field"> + <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring> + </tp:member> + + <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]"> + <tp:docstring>The set of vCard type parameters which may be set on this + field. If this list is empty and the + Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type + parameters may be used.</tp:docstring> + </tp:member> + + <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags"> + <tp:docstring>Flags describing the behaviour of this + field.</tp:docstring> + </tp:member> + + <tp:member type="u" name="Max"> + <tp:docstring>Maximum number of instances of this field which may be + set. MAXUINT32 is used to indicate that there is no + limit.</tp:docstring> + </tp:member> + </tp:struct> + + <property name="SupportedFields" type="a(sasuu)" tp:type="Field_Spec[]" + access="read" tp:name-for-bindings="Supported_Fields"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of field specifications describing the kinds of fields which may + be passed to <tp:member-ref>SetContactInfo</tp:member-ref>. The empty + list indicates that arbitrary vCard fields are permitted. This + property SHOULD be the empty list, and be ignored by clients, if + <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the + Can_Set flag.</p> + + <p>For example, a protocol in which arbitrary vCards were stored + as-is would set this property to the + empty list. A protocol whose notion of contact information is one + each of personal phone number, mobile phone number, location, email + address and date of birth, with no attributes allowed on each piece + of information, would set this property to (in Python-like + syntax):</p> + + <pre> +[ + ('tel', ['type=home'], Parameters_Exact, 1), + ('tel', ['type=cell'], Parameters_Exact, 1), + ('adr', [], Parameters_Exact, 1), + ('bday', [], Parameters_Exact, 1), + ('email', ['type=internet'], Parameters_Exact, 1), +]</pre> + + <p>A protocol which allows users to specify up to four phone numbers, + which may be labelled as personal and/or mobile, would set this + property to + <code>[ ('tel', ['type=home', 'type=cell'], 0, 4), ]</code>.</p> + + <tp:rationale> + <p>Studying existing IM protocols shows that in practice protocols + allow either a very restricted set of fields (such as MSN, which + seems to correspond roughly to the largest example above), or + something mapping 1:1 to a large subset of vCard (such as XMPP's + XEP-0054).</p> + </tp:rationale> + + <p>This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.</p> + + <tp:rationale> + <p>Some XMPP servers, like Google Talk, only allow a small subset of + the "vcard-temp" protocol. Whether the user's server is one of + these cannot be detected until quite late in the connection + process.</p> + </tp:rationale> + </tp:docstring> + </property> + + <tp:flags name="Contact_Info_Field_Flags" + value-prefix="Contact_Info_Field_Flag" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Flags describing the behaviour of a vCard field. + </tp:docstring> + <tp:flag suffix="Parameters_Exact" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If present, exactly the parameters indicated must be set on this + field; in the case of an empty list of parameters, this implies that + parameters may not be used.</p> + + <p>If absent, and the list of allowed parameters is non-empty, + any (possibly empty) subset of that list may be + used.</p> + + <p>If absent, and the list of allowed parameters is empty, + any parameters may be used.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Overwritten_By_Nickname" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Indicates that this field will be overwritten when the user's alias + is changed with <tp:dbus-ref + namespace="ofdT.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> + or when the Account's <tp:dbus-ref + namespace="ofdT.Account">Nickname</tp:dbus-ref> + is updated. Clients that allow the editing of the Alias and the + ContactInfo in the same location should hide fields with this flag.</p> + <tp:rationale> + <p>If a client allowed the user to edit both the nickname and the + ContactInfo field at the same time, the user could set them to two + different values even though they map to the same property. This + would result in surprising behavior where the second value would + win over the first.</p> + </tp:rationale> + <p>In addition to hiding this field when editing ContactInfo together + with the user's nickname, it is recommended that clients call + <tp:member-ref>SetContactInfo</tp:member-ref> before setting the + user's nickname.</p> + <tp:rationale> + <p>This ensures that if the user changes the nickname, the correct + value will get set even if the stale nickname is mistakenly sent + along with <tp:member-ref>SetContactInfo</tp:member-ref>.</p> + </tp:rationale> + <p>If used, this flag typically appears on either the 'nickname' or + 'fn' field.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for requesting information about a contact on a given + connection. Information is represented as a list of + <tp:type>Contact_Info_Field</tp:type>s forming a + structured representation of a vCard (as defined by RFC 2426), using + field names and semantics defined therein.</p> + + <p>On some protocols, information about your contacts is pushed to you, + with change notification; on others, like XMPP, the client must + explicitly request the avatar, and has no way to tell whether it has + changed without retrieving it in its entirety. This distinction is + exposed by <tp:member-ref>ContactInfoFlags</tp:member-ref> containing + the Push flag.</p> + + <p>On protocols with the Push flag set, UIs can connect to + <tp:member-ref>ContactInfoChanged</tp:member-ref>, call + <tp:member-ref>GetContactInfo</tp:member-ref> once at login for the set + of contacts they are interested in, and then be sure they will receive + the latest contact info. On protocols like XMPP, clients can do the + same, but will receive (at most) opportunistic updates if the info is + retrieved for other reasons. Clients may call + <tp:member-ref>RequestContactInfo</tp:member-ref> or + <tp:member-ref>RefreshContactInfo</tp:member-ref> to force a contact's + info to be updated, but MUST NOT do so unless this is either in + response to direct user action, or to refresh their own cache after a + number of days.</p> + + <tp:rationale> + <p>We don't want clients to accidentally cause a ridiculous amount of + network traffic.</p> + </tp:rationale> + </tp:docstring> + + <tp:contact-attribute name="info" + type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same value that would be returned by + <tp:member-ref>GetContactInfo</tp:member-ref> for this contact. + Omitted from the result if the contact's info + is not known.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml new file mode 100644 index 0000000..033c64d --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,1085 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.21.0">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections that have any concept of a list of + known contacts (roster, buddy list, friends list etc.)</p> + + <tp:rationale> + <p>On many protocols, there's a server-side roster (as in XMPP), + or a set of server-side lists that can be combined to form a + roster (as in MSN).</p> + + <p>In some protocols (like link-local XMPP), while there might not be + any server or roster, it's possible to list "nearby" contacts.</p> + + <p>In Telepathy 0.20 and older, we represented contact lists as a + collection of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >ContactList</tp:dbus-ref> channels. This is remarkably difficult to + work with in practice - every client that cares about contact lists + has to take the union of some hard-to-define set of these + channels - and conflicts with the idea that channels that cannot + be dispatched to a handler should be closed.</p> + </tp:rationale> + + <p>The list of contacts is not exposed as a D-Bus property; it can be + fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>. + </p> + + <tp:rationale> + <p>In some protocols, such as XMPP, the contact list may not be + available immediately. The + <tp:member-ref>GetContactListAttributes</tp:member-ref> method + will fail until the contact list is available. + Using a method also allows extra attributes to be retrieved at + the same time.</p> + </tp:rationale> + </tp:docstring> + + <tp:enum name="Contact_List_State" type="u"> + <tp:docstring> + The progress made in retrieving the contact list. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring>The connection has not started to retrieve the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is + called in this state, it will raise NotYet.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Waiting" value="1"> + <tp:docstring>The connection has started to retrieve the contact + list, but has not yet succeeded or failed. + If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called + in this state, it will raise NotYet.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Failure" value="2"> + <tp:docstring> + <p>The connection has tried and failed to retrieve the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> + is called in this state, it will immediately raise an error + indicating the reason for failure.</p> + + <p>The connection manager SHOULD try again to obtain the contact + list, if appropriate for the protocol. If it succeeds later, + the <tp:member-ref>ContactListState</tp:member-ref> MUST advance + to Success.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Success" value="3"> + <tp:docstring>The connection has successfully retrieved the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> + is called in this state, it will return successfully.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="ContactListState" tp:name-for-bindings="Contact_List_State" + type="u" tp:type="Contact_List_State" access="read"> + <tp:docstring> + The progress made in retrieving the contact list. + Change notification is via + <tp:member-ref>ContactListStateChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="ContactListStateChanged" + tp:name-for-bindings="Contact_List_State_Changed"> + <tp:docstring> + Emitted when <tp:member-ref>ContactListState</tp:member-ref> + changes. + </tp:docstring> + + <arg name="Contact_List_State" type="u" tp:type="Contact_List_State"> + <tp:docstring> + The new value of <tp:member-ref>ContactListState</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <method name="GetContactListAttributes" + tp:name-for-bindings="Get_Contact_List_Attributes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return some contact attributes for a list of contacts + associated with the user. This list MUST include at least:</p> + + <ul> + <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref> + attribute is not No</li> + <li>all contacts whose <tp:token-ref>publish</tp:token-ref> + attribute is not No</li> + </ul> + + <p>but MAY contain other contacts.</p> + + <tp:rationale> + <p>For instance, on XMPP, all contacts on the roster would appear + here even if they have subscription="none", unless there's + reason to believe the user does not want to see them (such as + having been blocked).</p> + </tp:rationale> + + <p>This list does not need to contain every visible contact: for + instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear + here. Blocked contacts SHOULD NOT appear here, unless they still + have a non-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or + <tp:token-ref>publish</tp:token-ref> attribute + for some reason.</p> + + <tp:rationale> + <p>It's reasonable to assume that blocked contacts should not be + visible to the user unless they specifically go looking for them, + at least in protocols like XMPP where blocking a contact + suppresses presence.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. Equivalent to the corresponding argument + to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>, + except that if this list does not contain the ContactList + interface itself, it is treated as though that interface was also + requested.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Hold" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. + (If <tp:dbus-ref namespace="ofdT.Connection" + >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the + case in all new connection managers, this has no effect.)</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes, + equivalent to the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>ContactListState</tp:member-ref> is + None or Waiting. In particular, this error is raised if the + <tp:dbus-ref namespace="ofdT.Connection">Status</tp:dbus-ref> + is not yet Connection_Status_Connected.</p> + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:enum name="Subscription_State" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An enumeration indicating whether presence subscription is denied, + denied but pending permission, or allowed. The exact semantics + vary according to where this type is used: see the + <tp:token-ref>subscribe</tp:token-ref> and + <tp:token-ref>publish</tp:token-ref> contact attributes for + details.</p> + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring>The presence subscription state is + unknown.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="No" value="1"> + <tp:docstring>Presence information cannot be seen, and either the + subscription state Removed_Remotely does not apply, or it is + not known whether that state applies. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Removed_Remotely" value="2"> + <tp:docstring>Presence information cannot be seen because the + remote contact took action: either the local user's request to + see the remote contact's presence was denied, or the remote + contact requested to see the local user's presence but then + cancelled their request.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Ask" value="3"> + <tp:docstring>Presence information cannot be seen. Permission + to see presence information has been requested, and the request + has not yet been declined or accepted.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Yes" value="4"> + <tp:docstring>Presence information can be seen.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:contact-attribute name="subscribe" + type="u" tp:type="Subscription_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, this connection can + expect to receive their presence, along with any other information + that has the same access control.</p> + + <tp:rationale> + <p>This is subscription="from" or subscription="both" in XMPP, + the "forward list" on MSN, or the contact being "added to + the local user's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is not Yes, the local user cannot generally + expect to receive presence from this contact. Their presence status + as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref> + is likely to be (Unknown, "unknown", ""), unless the local user + can temporarily see their presence for some other reason (for + instance, on XMPP, contacts seen in chatrooms will temporarily + have available presence).</p> + + <p>If this attribute is Ask, this indicates that the local user has + asked to receive the contact's presence at some time. It is + implementation-dependent whether contacts' subscribe attributes + can remain set to Ask, or are reset to No, when the connection + disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that we wishes to see a contact's + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have been + asked during the current session will ever have Ask status.</p> + </tp:rationale> + + <p>If this attribute is Removed_Remotely, this indicates that the + local user has asked to receive the contact's presence at some time, + but the remote contact has rejected that request, and a local + user interface has not yet acknowledged this. It is + implementation-dependent whether contacts' subscribe attributes can + remain set to Removed_Remotely, or are reset to No, when the + connection disconnects.</p> + + <p>After notifying the user, user interfaces MAY acknowledge a change + to <tt>subscribe</tt>=Removed_Remotely by calling either + <tp:member-ref>Unsubscribe</tp:member-ref> or + <tp:member-ref>RemoveContacts</tp:member-ref>, which will set + <tt>subscribe</tt> to No (and perhaps remove the contact). This + allows user interfaces to detect that the user has been notified + about the rejected request.</p> + + <p>This attribute's value will be Unknown or omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish" + type="u" tp:type="Subscription_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, the local user's presence + is published to that contact, along with any other information that + shares an access-control mechanism with presence (depending on + protocol, server configuration and/or user configuration, this may + include avatars, "rich presence" such as location, etc.).</p> + + <tp:rationale> + <p>This is subscription="to" or subscription="both" in XMPP, + the "reverse list" on MSN, or the state of "being added to + the contact's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is not Yes, the + local user's presence is not published to that contact; however, + if it is Ask, the contact has requested that the local user's + presence is made available to them.</p> + + <p>It is implementation-dependent whether contacts' <tt>publish</tt> + attributes can remain set to Ask, or are reset to No, when the + connection disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that a contact wishes to see our + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have asked + during the current session will ever have Ask status.</p> + </tp:rationale> + + <p>If this attribute is Removed_Remotely, this indicates that the + remote contact has asked to receive the user's presence at some time, + but has then cancelled that request before a response was given by + the local user. User interfaces MAY reset <tt>publish</tt> from + Removed_Remotely to No, by calling either + <tp:member-ref>Unpublish</tp:member-ref> or + <tp:member-ref>RemoveContacts</tp:member-ref>.</p> + + <p>If multiple factors affect whether a contact can receive the local + user's presence, this attribute SHOULD reflect the overall + result. For instance, an XMPP contact with subscription="to" or + subscription="both", but who has been blocked via + <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy + Lists</a>, SHOULD have publish=No.</p> + + <p>This attribute's value will be Unknown or omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish-request" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the <tp:token-ref>publish</tp:token-ref> attribute is Ask, an + optional message that was sent by the contact asking to receive the + local user's presence; omitted if none was given.</p> + + <tp:rationale> + <p>If the contact asking to receive our presence is also using + Telepathy, this is the message they supplied as the Message + argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p> + </tp:rationale> + + <p>Otherwise, this SHOULD be omitted.</p> + + <p>This attribute will also be omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> + </tp:docstring> + </tp:contact-attribute> + + <property name="ContactListPersists" + tp:name-for-bindings="Contact_List_Persists" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscriptions (in both directions) on this + connection are stored by the server or other infrastructure.</p> + + <tp:rationale> + <p>XMPP, MSN, ICQ, etc. all behave like this.</p> + </tp:rationale> + + <p>If false, presence subscriptions on this connection are not + stored.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record + of subscriptions, as described below. In link-local XMPP, + subscriptions are implicit (everyone on the local network receives + presence from everyone else) so nothing is ever stored.</p> + </tp:rationale> + + <p>If <tp:member-ref>CanChangeContactList</tp:member-ref> + is true, Telepathy clients (e.g. user interfaces or address books) + MAY keep a record of permission to publish and requests to subscribe + locally, and attempt to restore it for each Connection. If + ContactListPersists is false, clients MAY do this for all contacts; + if ContactListPersists is true, clients SHOULD NOT change the state + of contacts that were not changed locally.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), ContactListPersists is false, but + CanChangeContactList is true. Presence will not be received + unless clients renew any subscriptions they have for each + connection, in the way described. There is no server-side storage, + so clients have no alternative but to maintain independent contact + lists.</p> + + <p>In protocols like XMPP and MSN, it may be useful for clients to + queue up subscription requests or removals made while offline and + process them next time the connection is online. However, clients + should only replay the changes, rather than resetting the contact + list to match a stored copy, to avoid overwriting changes that + were made on the server.</p> + </tp:rationale> + + <p>Clients that replay requests like this SHOULD do so by calling + AuthorizePublication to pre-approve publication of presence to the + appropriate contacts, followed by RequestSubscription to request the + appropriate contacts' presences.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <tp:enum name="Contact_Metadata_Storage_Type" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection.</p> + + <p>On some protocols, certain metadata (for instance, contact aliases) + can only be stored for contacts on the contact list, or contacts + with a particular contact list state.</p> + + <p>To make it easier to deal with such protocols, if clients set + metadata on a contact who is not in the required state, the + Connection MUST cache the metadata for the duration of the session. + If clients request the attributes of that contact after the + appropriate "set" method has returned successfully, the Connection + MUST return the new (cached) value.</p> + + <p>If the contact is later placed in the required state to store + metadata (for instance, if subscription to the contact's presence + is requested, on a protocol like MSN where the alias has storage type + Subscribed_Or_Pending), the connection MUST store the cached + metadata at that time.</p> + + <tp:rationale> + <p>If the Connection didn't cache changes in this way, a client + intending to change the alias on MSN would have to wait until + the server acknowledged the subscription request; in the meantime, + other clients would still display the old alias.</p> + </tp:rationale> + + <p>The only exception to that general rule is that if the Connection + cannot store particular metadata at all (i.e. the + storage type is None), it MUST reject attempts to set it.</p> + + <tp:rationale> + <p>If the implementation knows that metadata can't be stored at + all, it's useful to report that, which can be done + synchronously. In general, user interfaces should detect + storage type None and not display editing controls at all.</p> + </tp:rationale> + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This connection cannot store this type of metadata at all, and + attempting to do so will fail with NotImplemented.</p> + + <tp:rationale> + <p>Link-local XMPP can't store aliases or group memberships at + all, and subscription and presence states are implicit (all + contacts on the local network have subscribe = publish = Yes + and no other contacts exist).</p> + + <p>As of April 2010, the XMPP server for Facebook Chat provides a + read-only view of the user's Facebook contacts, so it could also + usefully have this storage type.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed_Or_Pending" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Ask or Yes.</p> + + <tp:rationale> + <p>Contact aliases and groups on MSN have this behaviour.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Yes.</p> + + <tp:rationale> + <p>No service with this behaviour is currently known, but it's a + stricter form of Subscribed_Or_Pending.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Anyone" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user can set this metadata for any valid contact identifier, + whether or not they have any presence subscription relationship + to it, and it will be stored on their contact list.</p> + + <tp:rationale> + <p>Contact aliases and groups on XMPP have this behaviour; it + is possible to put a contact in a group, or assign an alias + to them, without requesting that presence be shared.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Contact_Subscriptions" array-name=""> + <tp:docstring> + A single contact's subscribe, publish and publish-request attributes. + </tp:docstring> + + <tp:member name="Subscribe" type="u" tp:type="Subscription_State"> + <tp:docstring> + The new value of the contact's "subscribe" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish" type="u" tp:type="Subscription_State"> + <tp:docstring> + The new value of the contact's "publish" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish_Request" type="s"> + <tp:docstring> + The new value of the contact's "publish-request" attribute, + or the empty string if that attribute would be omitted. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Subscription_Map" array-name=""> + <tp:docstring> + A map from contacts to their subscribe, publish and publish-request + attributes. + </tp:docstring> + + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact's handle. + </tp:docstring> + </tp:member> + + <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions"> + <tp:docstring> + The contact's subscribe, publish and publish-request attributes. + </tp:docstring> + </tp:member> + </tp:mapping> + + <signal name="ContactsChangedWithID" + tp:name-for-bindings="Contacts_Changed_With_ID"> + <tp:added version="0.21.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the contact list becomes available, when contacts' + basic stored properties change, when new contacts are added to the + list that would be returned by + <tp:member-ref>GetContactListAttributes</tp:member-ref>, + or when contacts are removed from that list.</p> + + <tp:rationale> + <p>This provides change notification for that list, and for + contacts' <tp:token-ref>subscribe</tp:token-ref>, + <tp:token-ref>publish</tp:token-ref> and + <tp:token-ref>publish-request</tp:token-ref> attributes.</p> + </tp:rationale> + + <p>Connection managers SHOULD also emit this signal when a contact + requests that the user's presence is published to them, even if + that contact's <tp:token>publish</tp:token> attribute is already + Ask and the <tp:token>publish-request</tp:token> has not changed.</p> + + <tp:rationale> + <p>If the same contact sends 10 identical requests, 10 identical + signals should be emitted.</p> + </tp:rationale> + </tp:docstring> + + <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> + <tp:docstring> + The new <tp:token-ref>subscribe</tp:token-ref>, + <tp:token-ref>publish</tp:token-ref> and + <tp:token-ref>publish-request</tp:token-ref> attributes of all the + contacts that have been added, and all the contacts for which those + attributes have changed. + </tp:docstring> + </arg> + + <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The identifiers of the contacts in the <var>Changes</var> map. + </tp:docstring> + </arg> + + <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The contacts that have been removed from the list that would be + returned by + <tp:member-ref>GetContactListAttributes</tp:member-ref>. + This also implies that they have subscribe = No and publish = No; + contacts MUST NOT be listed both here and in <var>Changes</var>. + </tp:docstring> + </arg> + </signal> + + <signal name="ContactsChanged" + tp:name-for-bindings="Contacts_Changed"> + <tp:deprecated version="0.21.8">Connection managers MUST still + emit this signal, but clients SHOULD listen for the + <tp:member-ref>ContactsChangedWithID</tp:member-ref> signal in + addition, and ignore this signal after ContactsChangedWithID has been + emitted at least once. + </tp:deprecated> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted immediately after + <tp:member-ref>ContactsChangedWithID</tp:member-ref>, under the same + circumstances.</p> + + <p>If clients receive this signal without first receiving a + corresponding <tp:member-ref>ContactsChangedWithID</tp:member-ref>, + they MUST assume that only this signal will be emitted.</p> + </tp:docstring> + + <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> + <tp:docstring> + The same as the corresponding argument to + <tp:member-ref>ContactsChangedWithID</tp:member-ref>. + </tp:docstring> + </arg> + + <arg name="Removals" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The same as the corresponding argument to + <tp:member-ref>ContactsChangedWithID</tp:member-ref>, except that it + only includes handles and not identifiers. + </tp:docstring> + </arg> + </signal> + + <property name="CanChangeContactList" type="b" access="read" + tp:name-for-bindings="Can_Change_Contact_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscription and publication can be changed + using the + <tp:member-ref>RequestSubscription</tp:member-ref>, + <tp:member-ref>AuthorizePublication</tp:member-ref> and + <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p> + + <p>If false, all of those methods will always fail; they SHOULD raise + the error org.freedesktop.Telepathy.Error.NotImplemented.</p> + + <tp:rationale> + <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is + implicitly published to everyone in the local subnet, so the user + cannot control their presence publication.</p> + </tp:rationale> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given contacts allow the local user to + subscribe to their presence, i.e. that their subscribe attribute + becomes Yes.</p> + + <p>Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically allow the contacts to see the local user's + presence). User interfaces that require mutual subscription + MAY call <tp:member-ref>AuthorizePublication</tp:member-ref> + at the same time as this method.</p> + + <tp:rationale> + <p>Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.</p> + </tp:rationale> + + <p>Before calling this method on a connection where <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag, + user interfaces SHOULD obtain, from the user, an alias to + identify the contact in future, and store it using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >SetAliases</tp:dbus-ref>.</p> + + <p>The user MAY be + prompted using the contact's current self-assigned nickname, or + something derived from the contact's (presumably self-assigned) + identifier, as a default, but these names chosen by the contact + SHOULD NOT be used without user approval.</p> + + <tp:rationale> + <p>This is a generalization of + <a href="http://xmpp.org/extensions/xep-0165.html" + >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>) + to protocols other than XMPP. A reasonable user interface for + this, as used in many XMPP clients, is to have a text entry + for the alias adjacent to the text entry for the identifier + to add.</p> + </tp:rationale> + + <p>For contacts with subscribe=Yes, this method has no effect. + It MUST return successfully if all contacts are in this state.</p> + + <p>For contacts with subscribe=Ask, this method SHOULD send a new + request, with the given message, if allowed by the underlying + protocol.</p> + + <p>For contacts with subscribe=No or subscribe=Rejected, this method + SHOULD request that the contact allows the local user to subscribe + to their presence; in general, this will change their publish + attribute to Ask (although it could change directly to Yes in some + situations).</p> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + + <p>If the remote contact accepts the request, their subscribe + attribute will later change from Ask to Yes.</p> + + <p>If the remote contact explicitly rejects the request (in protocols + that allow this), their subscribe attribute will later change from + Ask to Rejected.</p> + + <p>If the subscription request is cancelled by the local user, the + contact's subscribe attribute will change from Ask to No.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to whom requests are to be sent.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An optional plain-text message from the user, to send to those + contacts with the subscription request. The + <tp:member-ref>RequestUsesMessage</tp:member-ref> property + indicates whether this message will be used or ignored.</p> + + <p>Clients SHOULD NOT send a non-empty message without first giving + the user an opportunity to edit it.</p> + + <tp:rationale> + <p>These messages are typically presented to the remote contact + as if the user had typed them, so as a minimum, the user should be + allowed to see what the UI will be saying on their behalf.</p> + </tp:rationale> + + <p>Connections where this message is not useful MUST still allow it to + be non-empty.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="RequestUsesMessage" type="b" access="read" + tp:name-for-bindings="Request_Uses_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the Message parameter to + <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be + significant, and user interfaces SHOULD prompt the user for a + message to send with the request; a message such as "I would like + to add you to my contact list", translated into the local user's + language, might make a suitable default.</p> + + <tp:rationale> + <p>This matches user expectations in XMPP and ICQ, for instance.</p> + </tp:rationale> + + <p>If false, the parameter is ignored; user interfaces SHOULD avoid + prompting the user, and SHOULD pass an empty string to + RequestSubscription.</p> + + <tp:rationale> + <p><em>FIXME: is there any such protocol?</em></p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="AuthorizePublication" + tp:name-for-bindings="Authorize_Publication"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For each of the given contacts, request that the local user's + presence is sent to that contact, i.e. that their publish attribute + becomes Yes.</p> + + <p>Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically request that the contacts allow the user to + subscribe to their presence). User interfaces that require mutual + subscription MAY call + <tp:member-ref>RequestSubscription</tp:member-ref> at the same time + as this method.</p> + + <tp:rationale> + <p>Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.</p> + </tp:rationale> + + <p>For contacts with publish=Yes, this method has no effect; it + MUST return successfully if all contacts given have this state.</p> + + <p>For contacts with publish=Ask, this method accepts the + contact's request to see the local user's presence, changing + their publish attribute from Ask to Yes.</p> + + <p>For contacts with publish=No, if the protocol allows it, this + method allows the contacts to see the local user's presence even + though they have not requested it, changing their publish attribute + from No to Yes. Otherwise, it merely records the fact that + presence publication to those contacts is allowed; if any of + those contacts ask to receive the local user's presence + later in the lifetime of the connection, the connection SHOULD + immediately allow them to do so, changing their publish + attribute directly from No to Yes.</p> + + <tp:rationale> + <p>This makes it easy to implement the common UI policy that if + the user attempts to subscribe to a contact's presence, requests + for reciprocal subscription are automatically approved.</p> + </tp:rationale> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to authorize.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove the given contacts from the contact list entirely. It is + protocol-dependent whether this works, and under which + circumstances.</p> + + <p>If possible, this method SHOULD set the contacts' subscribe and + publish attributes to No, remove any stored aliases for those + contacts, and remove the contacts from the result of + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + + <p>This method SHOULD succeed even if it was not possible to carry out + the request entirely or for all contacts (for instance, if there is an + outstanding request to subscribe to the contact's presence, and it's + not possible to cancel such requests). However, all signals that + immediately result from this method call MUST be emitted before it + returns, so that clients can interpret the result.</p> + + <tp:rationale> + <p>User interfaces removing a contact from the contact list are + unlikely to want spurious failure notifications resulting from + limitations of a particular protocol. However, emitting the + signals first means that if a client does want to check exactly + what happened, it can wait for the method to return (while + applying change-notification signals to its local cache of the + contact list's state), then consult its local cache of the + contact list's state to see whether the contact is still there.</p> + </tp:rationale> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' subscribe attribute to No, + i.e. stop receiving their presence.</p> + + <p>For contacts with subscribe=Ask, this attempts to cancel + an earlier request to subscribe to the contact's presence; for + contacts with subscribe=Yes, this attempts to + unsubscribe from the contact's presence.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unpublish" tp:name-for-bindings="Unpublish"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' publish attribute to No, + i.e. stop sending presence to them.</p> + + <p>For contacts with publish=Ask, this method explicitly rejects the + contact's request to subscribe to the user's presence; for + contacts with publish=Yes, this method attempts to prevent the + user's presence from being received by the contact.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml new file mode 100644 index 0000000..1020190 --- /dev/null +++ b/spec/Connection_Interface_Contacts.xml @@ -0,0 +1,191 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contacts" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser + General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public License + along with this library; if not, write to the Free Software Foundation, + Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Contacts"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.9"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface allows many attributes of many contacts to be + obtained in a single D-Bus round trip.</p> + + <p>Each contact attribute has an string identifier + (<tp:type>Contact_Attribute</tp:type>), which is namespaced + by the D-Bus interface which defines it.</p> + </tp:docstring> + + <tp:simple-type name="Contact_Attribute" type="s"> + <tp:docstring> + A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character + and an identifier for an attribute defined by that interface. The + attribute identifier SHOULD be in lower case. + + <tp:rationale> + These aren't D-Bus core Properties, and we want them to look visibly + different. + </tp:rationale> + </tp:docstring> + </tp:simple-type> + + <tp:mapping name="Single_Contact_Attributes_Map"> + <tp:docstring> + Some of the attributes of a single contact. + </tp:docstring> + + <tp:member type="s" tp:type="Contact_Attribute" name="Attribute"> + <tp:docstring> + The name of the attribute + </tp:docstring> + </tp:member> + + <tp:member type="v" name="Value"> + <tp:docstring> + The value of the attribute + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Contact_Attributes_Map"> + <tp:docstring>Mapping returned by + <tp:member-ref>GetContactAttributes</tp:member-ref>, representing a + collection of Contacts and their requested attributes.</tp:docstring> + + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact + </tp:docstring> + </tp:member> + + <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map" + name="Attributes"> + <tp:docstring> + Attributes of that contact + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="ContactAttributeInterfaces" access="read" type="as" + tp:type="DBus_Interface[]" + tp:name-for-bindings="Contact_Attribute_Interfaces"> + <tp:docstring> + A list of D-Bus interfaces for which + <tp:member-ref>GetContactAttributes</tp:member-ref> is expected to work. + This cannot change during the lifetime of the Connection. + </tp:docstring> + </property> + + <method name="GetContactAttributes" + tp:name-for-bindings="Get_Contact_Attributes"> + <tp:docstring> + Return any number of contact attributes for the given handles. + </tp:docstring> + + <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts. + </tp:docstring> + </arg> + + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.</p> + + <p>Connection managers SHOULD ignore interfaces requested which they + do not support (i.e. those not mentioned in the + <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> + property.)</p> + + <tp:rationale> + <p>This simplifies client-side code. Clients which care may + distinguish between unsupported interfaces (e.g. this Connection + does not support Avatars), and interfaces on which no information + is known for these contacts (e.g. we don't know the avatar tokens + of any of the contacts, so we omitted them all) by inspecting + <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>.</p> + </tp:rationale> + + <p>Attributes from the interface + <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> + are always returned, and need not be requested explicitly.</p> + + <p>As well as returning cached information immediately, the + connection MAY start asynchronous requests to obtain better + values for the contact attributes. If better values are later + obtained by this process, they will be indicated with the usual + signals (such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">AliasesChanged</tp:dbus-ref>).</p> + + <tp:rationale> + For instance, an XMPP connection manager could download vCards + in response to a request for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref> + attributes. + </tp:rationale> + </tp:docstring> + <tp:changed version="0.19.2"> + requesting information for interfaces not mentioned in + <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> is no + longer an error. Be aware that older connection managers may still + consider this an error. + </tp:changed> + </arg> + + <arg direction="in" name="Hold" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. + (If <tp:dbus-ref namespace="ofdT.Connection" + >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the + case in all new connection managers, this has no effect.)</p> + + <tp:rationale> + <p>For further round-trip avoidance.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes. + If any of the requested handles are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml new file mode 100644 index 0000000..e5457b1 --- /dev/null +++ b/spec/Connection_Interface_Forwarding.xml @@ -0,0 +1,346 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Forwarding" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This connection interface is for protocols that are capable of + signaling to remote contacts that incoming communication channels + should be instead sent to a separate contact. This might apply to + things such as call forwarding, for example.</p> + + <p>In some cases, a CM may register forwarding rules with an external + service; in those cases, it will never see the incoming channel, and + the forwarding will happen automatically.</p> + + <p>In other cases, the CM will handle the forwarding itself. When an + incoming channel is detected, the status of the local user will + determine whether or not a forwarding rule is matched. For some + rules, this MAY happen immediately (ie, if the user is Busy); for + others, there MAY be a timeout (in seconds) that must expire + before the forwarding rule is matched (the timeout is specified + by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p> + + <p>Once a forwarding rule is matched and any necessary timeouts have + expired, the CM can forward the incoming channel to the specified + handle. If for whatever reason the remote handle does not accept + the channel AND the CM supports multiple forwarding entries AND + any necessary timeouts have expired (specified by the next entry + in the list), the CM can forward the incoming channel to the next + handle in the entry list. This continues until the list is + exhausted, or the incoming channel is accepted.</p> + + <p>Note that the rule matches are only for the first entry in the + in the forwarding rule list. Once the incoming channel has been + forwarded, the next entry in the list (assuming one exists and + the contact that the channel has been forwarded to does not respond + after any necessary timeouts) is used regardless of the status of + the forwarded channel. The initial match rule might have been + Busy, whereas the contact that the channel has been forwarded to + might be offline. Even in this case, the Busy list is still + traversed until the channel is handled (or there are no more + forwarding entries in the list).</p> + + <p>For example, assuming the following dict for Forwarding_Rules:</p> + <pre> + ForwardingRules = { + Busy: ( initial-timeout: 30, [ + (handle: 3, timeout: 15), + (handle: 5, timeout: 20) + ]), + NoReply: ( initial-timeout: 15, [ + (handle: 5, timeout: 30), + (handle: 3, timeout: 20) + ]) + }</pre> + + <p>We can imagine a scenario where an incoming channel is detected, + the media stream is available (ie, not Busy), + and the local user is online. While the CM is waiting for the local user to + accept the channel, it looks at NoReply's first timeout value. After 15s if + the local user hasn't accepted, the CM forwards the channel to Handle #5. The + CM then waits 30s for Handle #5 to accept the channel. If after 30s it does + not, the CM forwards the incoming channel to Handle #3, which will have + 20s to accept the channel.</p> + + <p>When an unanswered <tp:dbus-ref + namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> call is + forwarded, both the contact and the self handle should be removed from + the group with the self handle as the actor, and + <tp:type>Channel_Group_Change_Reason</tp:type> <code>No_Answer</code> or + <code>Busy</code>, as appropriate. For <tp:dbus-ref + namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels, the + <tp:type>Call_State_Change_Reason</tp:type> <code>Forwarded</code> + should be used.</p> + </tp:docstring> + + <tp:enum name="Forwarding_Condition" type="u"> + <tp:docstring> + The various forwarding conditions that are supported by this interface. + In general, the conditions should not overlap; it should be very clear + which rule would be chosen given a CM's behavior with an incoming + channel. The exception to this is Unconditional, + which will override all other rules. + </tp:docstring> + + <tp:enumvalue value="0" suffix="Unconditional"> + <tp:docstring> + Incoming channels should always be forwarded. Note that setting this + will override any other rules. If not set, other rules will + be checked when an incoming communication channel is detected. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Busy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming channel should be forwarded if a busy signal is + detected. What defines "Busy" is CM-specific (perhaps a single + resource is already in use, or a user's status is set to Busy + <tp:type>Connection_Presence_Type</tp:type>).</p> + + <p>If initial timeout is specified for Busy condition and call + waiting is not supported by the service, the timeout will be + ignored.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="No_Reply"> + <tp:docstring> + The incoming channel should be forwarded if the local user doesn't + accept it within the specified amount of time. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="3" suffix="Not_Reachable"> + <tp:docstring> + The incoming channel should be forwarded if the user is offline. + This could be a manual setting (the user has chosen to set their + presence to offline or invisible) or something specified by the + underlying network (the user is not within range of a cell tower). + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Forwarding_Rule_Entry" + array-name="Forwarding_Rule_Entry_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A forwarding rule entry. These MAY be chained together + for CMs that support chaining of forwards (in other words, + a forwarding rule may have multiple entries; if the contact + in the first entry doesn't respond, the incoming channel + might be forwarded to the contact in the second entry).</p> + + <p>For CMs and protocols that don't support chaining of + entries, only the first entry would be used.</p> + </tp:docstring> + + <tp:member type="u" name="Timeout"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The length of time (in seconds) to wait the contact to respond + to the forwarded channel. This MAY be ignored by the CM if it + isn't supported by the underlying network/protocol for the + specific status of the remote contact (for example, a GSM call + that is forwarded may return Not_Reachable immediately without + waiting for the timeout value to expire).</p> + + <p>A value of 0 means the condition can match immediately. A + value of MAX_UINT32 means that the CM's default should be + used.</p> + </tp:docstring> + </tp:member> + + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The contact to forward an incoming channel to. If the handle + doesn't point to anything (e.g. points to a phone number that + doesn't exist), the entry SHOULD be skipped. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Forwarding_Rule_Chain"> + <tp:docstring> + A chain of forwarding rules and an initial timeout after which + the rules are applied. + </tp:docstring> + + <tp:member type="u" name="InitialTimeout"> + <tp:docstring>Initial timeout for the rule.</tp:docstring> + </tp:member> + + <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring>The forwarding targets (an array of type + <tp:type>Forwarding_Rule_Entry</tp:type>). + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Forwarding_Rule_Map" array-name=""> + <tp:docstring>A dictionary whose keys are forwarding conditions and + whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs. + </tp:docstring> + + <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> + <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain" + name="Rule_Chain" /> + </tp:mapping> + + <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name=""> + <tp:docstring>A dictionary whose keys are forwarding conditions and + whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> + for the condition. + </tp:docstring> + <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> + <tp:member type="u" name="Chain_Length" /> + </tp:mapping> + + <property name="SupportedForwardingConditions" type="a{uu}" access="read" + tp:type="Supported_Forwarding_Conditions_Map" + tp:name-for-bindings="Supported_Forwarding_Conditions"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map of forwarding conditions supported on this connection to + maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> + supported for the specific condition.</p> + + <tp:rationale> + <p>When forwarding is done by the provider, different providers + might support different chain sizes, or provider and local + implementation chain sizes might differ.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="ForwardingRules" type="a{u(ua(uu))}" access="read" + tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The current forwarding rules that are enabled for this connection. + Forwarding rules each contain an array of type + <tp:type>Forwarding_Rule_Entry</tp:type>.</p> + </tp:docstring> + </property> + + <signal name="ForwardingRuleChanged" + tp:name-for-bindings="Forwarding_Rule_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p> + + <p>By the time this is emitted, the property MUST have been updated + with the new rules being active. If any protocol/network + requests must be made, they should be completed before the signal + is emitted.</p> + </tp:docstring> + + <arg name="Condition" type="u" tp:type="Forwarding_Condition"> + <tp:docstring> + The condition of the forwarding rule that's been changed. + </tp:docstring> + </arg> + + <arg name="Timeout" type="u"> + <tp:docstring> + The new initial timeout for the rule. + </tp:docstring> + </arg> + + <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring> + The new (and as of the emission of the signal, currently active) + forwards. The order is relevant; those at the lowest array index + are used first. + </tp:docstring> + </arg> + </signal> + + <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule"> + <tp:docstring> + Update the forwarding rules. + </tp:docstring> + + <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The forwarding rule to override. Note that this SHOULD not affect + other rules; setting a rule that overrides others (such as + Forwarding_Rule_Unconditional) will not modify other rules. This + means that when a client sets Forwarding_Rule_Busy and then + temporarily sets Forwarding_Rule_Unconditional, the + Forwarding_Rule_Busy rule will retain settings after + Forwarding_Rule_Unconditional, has been unset.</p> + + <p>If the CM has no choice but to adjust multiple rules after a call + to this function (ie, due to the network or protocol forcing such + behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref> + signals for each changed rule. The order of the signals is + implementation-dependent, with the only requirement that the + last signal is for the rule that was originally requested to have + been changed (e.g. if Unconditional automatically modifies + Busy and NoReply, three + separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the + last signal being for Forwarding_Rule_Unconditional).</p> + + <p>Each forwarding condition will occur no more than once in + the rule array. Setting a rule will overwrite the old rule + with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring> + The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to + activate for the rule. An empty array will effectively disable the + rule. + </tp:docstring> + </arg> + + <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring> + The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>). + This is the list of entries that is being replaced with the call to + <tp:member-ref>SetForwardingRule</tp:member-ref>. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The specified Condition is not supported by this connection, + or the number of chained + <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should + be checked prior to calling + <tp:member-ref>SetForwardingRule</tp:member-ref>. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + A Handle that has been supplied is invalid. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Keepalive.xml b/spec/Connection_Interface_Keepalive.xml new file mode 100644 index 0000000..9f4ac68 --- /dev/null +++ b/spec/Connection_Interface_Keepalive.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Keepalive" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Keepalive.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.21.2">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Most messaging protocols allow the client to send periodic + content-less pings to the server when the connection is otherwise idle, + to reassure both itself and the server that its connection is still + alive. Depending on the nature of the network connection, and the + device running the client, the desired interval between such pings may + vary.</p> + + <tp:rationale> + <p>For instance, on a mobile handset connected via 3G, + overly-frequent keepalives can drain the battery through needlessly + waking up the radio, and a relatively high interval is appropiate. By + contrast, a desktop computer is less likely to be asleep in the first + place, and users expect dropped connections to be noticed as soon as + possible.</p> + </tp:rationale> + + <p>This interface provides a + <tp:member-ref>KeepaliveInterval</tp:member-ref> property which + controls the frequency of keepalive pings, if any. Connection managers + implementing this property should also include it in <tp:dbus-ref + namespace='org.freedesktop.Telepathy'>Protocol.Parameters</tp:dbus-ref> + with the <code>DBus_Property</code> flag, allowing the desired value to + be stored in <tp:dbus-ref + namespace='org.freedesktop.Telepathy'>Account.Parameters</tp:dbus-ref> + and passed onto the connection by the account manager.</p> + </tp:docstring> + + <property name="KeepaliveInterval" type="u" access="readwrite" + tp:name-for-bindings="Keepalive_Interval" + tp:is-connection-parameter='och aye'> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time in seconds between pings sent to the server to ensure that + the connection is still alive, or <tt>0</tt> to disable such + pings.</p> + + <p>This property (and parameter) supersedes the older + <tt>keepalive-interval</tt> + <tp:type>Connection_Parameter_Name</tp:type>.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml new file mode 100644 index 0000000..fe54923 --- /dev/null +++ b/spec/Connection_Interface_Location.xml @@ -0,0 +1,464 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Location" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Location"> + <tp:added version="0.17.27">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols which allow users to + publish their current geographical location, and subscribe to the + current location of their contacts.</p> + + <p>This interface is geared strongly towards automatic propagation and + use of this information, so focuses on latitude, longitude and + altitude which can be determined by GPS, although provision is also + included for an optional human-readable description of locations. All + co-ordinate information is required to be relative to the WGS84 + datum.</p> + + <p>The information published through this interface is intended to have + the same scope as presence information, so will normally be made + available to those individuals on the user's "publish" contact list. + Even so, user interfaces should not automatically publish location + information without the consent of the user, and it is recommended + that an option is made available to reduce the accuracy of the + reported information to allow the user to maintain their privacy.</p> + + <p>Location information is represented using the terminology of XMPP's + <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a> + or the XEP-0080-derived + <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where + possible.</p> + + <p>Clients of this interface SHOULD register an interest in it by calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref> with an argument + containing the name of this interface, + before calling any Location method. If they do so, they SHOULD also call + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> after use to allow + the CM to release resources associated with this interface.</p> + </tp:docstring> + + <!-- Potentially to be reinstated later: + http://bugs.freedesktop.org/show_bug.cgi?id=19585 + <tp:enum name="Location_Accuracy_Level" type="i"> + <tp:docstring> + A location accuracy level. This should be kept in sync with + GeoclueAccuracyLevel in the Geoclue project. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + The accuracy is unspecified. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Country" value="1"> + <tp:docstring> + The location indicates the contact's country. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Region" value="2"> + <tp:docstring> + The location indicates the contact's region within a country. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Locality" value="3"> + <tp:docstring> + The location indicates the contact's locality within a region + (e.g. the correct city). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Postal_Code" value="4"> + <tp:docstring> + The location indicates the correct postal code. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Street" value="5"> + <tp:docstring> + The location indicates the correct street. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Detailed" value="6"> + <tp:docstring> + The location's accuracy is given by the accuracy key. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + --> + + <tp:mapping name="Location"> + <tp:docstring> + A user's location, represented as an extensible mapping. + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + + <p>Civic addresses are represented by the following well-known + keys (all of which have string values), which should be kept in + sync with those used in XEP-0080 and in the Geoclue project:</p> + + <ul> + <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country + code, e.g. "us", "gb", "fr"</li> + <li>country - s: a country name in unspecified locale, e.g. + "USA"</li> + <li>region - s: an administrative region of the nation, such as a + state or province</li> + <li>locality - s: a locality within the administrative region, such + as a town or city</li> + <li>area - s: a named area such as a campus or neighborhood</li> + <li>postalcode - s: a code used for postal delivery</li> + <li>street - s: a thoroughfare within the locality, or a crossing of + two thoroughfares</li> + </ul> + + <p>The following address keys are defined in XEP-0080 but not by + Geoclue, and are also allowed:</p> + + <ul> + <li>building - s: a specific building on a street or in an area</li> + <li>floor - s: a particular floor in a building</li> + <li>room - s: a particular room in a building</li> + <li>text - s: any more specific information, e.g. + "Northwest corner of the lobby"</li> + <li>description - s: A natural-language name for or description of + the location, e.g. "Bill's house"</li> + <li>uri - s: a URI representing the location or pointing to more + information about it</li> + </ul> + + <p>Since the previous strings have data intended to be read by users, + the language used should be stated using:</p> + + <ul> + <li>language - s: a specific language or locale of location + information in a format compatible to RFC 4646. Note that UTF-8 + is the only allowed encoding, e.g. "en" or "fr-CA".</li> + </ul> + + <p>Positions are represented by the following well-known keys:</p> + + <ul> + <li>lat - d: latitude in decimal degrees north, -90 to +90, + relative to the WGS-84 datum + <tp:rationale> + This is from XEP-0080; the XEP allows use of a different + datum, but recommends this one. We enforce sanity by requiring + a consistent datum: a minimal compliant implementation of this + specification in terms of XEP-0080 would simply ignore the + <lat> and <lon> elements if <datum> exists + and has a value other than WGS-84, while an advanced + implementation might correct for the different datum. + </tp:rationale> + </li> + <li>lon - d: Longitude in decimal degrees east, -180 to +180, + relative to the WGS-84 datum + <tp:rationale> + Same rationale as 'lat' + </tp:rationale> + </li> + <li>alt - d: altitude in metres above sea level (negative + if below sea level) + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + + <!-- Potentially to be reinstated later: + http://bugs.freedesktop.org/show_bug.cgi?id=19585 + <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>): + an indication of accuracy, which SHOULD be omitted if it would be + Location_Accuracy_Level_None or + Location_Accuracy_Level_Detailed + <tp:rationale> + This is a struct field in GeoClue; the name is new in this + specification, and was chosen in an attempt to avoid clashing + with any future XEP-0080 terminology. + </tp:rationale> + </li> + --> + + <li>accuracy - d: horizontal position error in metres if + known + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + </ul> + + <p>Velocities are represented by the following well-known keys:</p> + + <ul> + <li>speed - d: speed in metres per second + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + <li>bearing - d: direction of movement in decimal degrees, + where North is 0 and East is 90 + <tp:rationale> + This is from XEP-0080, and is equivalent to the struct field + called "direction" in GeoClue + </tp:rationale> + </li> + </ul> + + <p>Other well-known keys:</p> + + <ul> + <li>timestamp - x (<tp:type>Unix_Timestamp64</tp:type>): the time + that the contact was at this location, in seconds since + 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC) + <tp:rationale> + XEP-0080 uses an ISO 8601 string for this, but a number of + seconds since the epoch is probably easier to work with. + </tp:rationale> + </li> + </ul> + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring> + The value corresponding to the well-known key. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Contact_Locations" type="a{ua{sv}}"> + <tp:docstring> + A map from contacts to their locations. + </tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact</tp:docstring> + </tp:member> + <tp:member name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring>The contact's location, which MAY be empty to indicate + that the contact's location is unknown</tp:docstring> + </tp:member> + </tp:mapping> + + <method name="GetLocations" tp:name-for-bindings="Get_Locations"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return the current locations of the given contacts, if they are + already known. If any of the given contacts' locations are not known, + request their current locations, but return immediately without waiting + for a reply; if a reply with a non-empty location is later received + for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref> + signal will be emitted for them.</p> + + <tp:rationale> + <p>This method is appropriate for "lazy" location finding, for instance + displaying the location (if available) of everyone in your contact + list.</p> + </tp:rationale> + + <p>For backwards compatibility, if this method is called by a client + whose "interest count" for this interface, as defined by <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref>, is zero, the + Connection SHOULD behave as if AddClientInterest had been called for + this interface just before that method call. Clients that do not + explicitly call AddClientInterest SHOULD NOT call <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose locations should be returned or signalled. + </tp:docstring> + </arg> + + <arg direction="out" name="Locations" type="a{ua{sv}}" + tp:type="Contact_Locations"> + <tp:docstring> + The contacts' locations, if already known. Contacts whose locations + are not already known are omitted from the mapping; contacts known + to have no location information appear in the mapping with an empty + Location dictionary. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RequestLocation" tp:name-for-bindings="Request_Location"> + <tp:docstring> + Return the current location of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + <tp:rationale> + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose location should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring> + The contact's location. It MAY be empty, indicating that no location + information was found. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + The requested contact does not allow the local user to see their + location information. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated"> + <tp:docstring> + Emitted when a contact's location changes or becomes known. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact + </tp:docstring> + </arg> + <arg name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring> + The contact's location, or empty to indicate that nothing is known + about the contact's location. + </tp:docstring> + </arg> + </signal> + + <method name="SetLocation" tp:name-for-bindings="Set_Location"> + <tp:docstring> + Set the local user's own location. + </tp:docstring> + + <arg direction="in" name="Location" type="a{sv}"> + <tp:docstring> + The location to advertise. If the user wants to obscure their + exact location by reducing the precision or accuracy, clients + MUST do this themselves, rather than relying on the connection + manager to do so. Clients that interact with more than one + connection SHOULD advertise the same reduced-accuracy location + to all of them, so that contacts cannot obtain an undesirably + accurate location by assuming that random errors have been added + and averaging the locations advertised on multiple connections. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The user's server does not support publishing their own location. + If it is possible to determine this ahead of time, the + <code>Can_Set</code> flag will not be set in + <tp:member-ref>SupportedLocationFeatures</tp:member-ref>. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <property name="LocationAccessControlTypes" type="au" access="read" + tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types"> + <tp:docstring>The types of access control that are supported by this + connection.</tp:docstring> + </property> + + <property name="LocationAccessControl" type="(uv)" access="readwrite" + tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control"> + <tp:docstring>The current access control mechanism and settings + for this connection. Before publishing location for the first time, + if this has not been set by a client, implementations SHOULD + set it to be as restrictive as possible (an empty whitelist, if + supported).</tp:docstring> + </property> + + <property name="SupportedLocationFeatures" + tp:name-for-bindings="Supported_Location_Features" + type="u" tp:type="Location_Features" access="read"> + <tp:added version="0.19.6"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Indicates the Location features supported by this connection. This + property MAY be undefined before <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref> + becomes <code>Connected</code>, but MUST remain constant thereafter. + </tp:docstring> + </property> + + <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature"> + <tp:flag suffix="Can_Set" value="1"> + <tp:docstring> + Indicates that setting your own location with + <tp:member-ref>SetLocation</tp:member-ref> is supported on this + connection. + </tp:docstring> + </tp:flag> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Flags describing the Location features which may be supported on any + given connection. + </tp:docstring> + </tp:flags> + + <tp:contact-attribute name="location" + type="a{sv}" tp:type="Location"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetLocations</tp:member-ref> for this contact. + Omitted from the result if the contact's location + is not known.</p> + + <p>For backwards compatibility, if contact attributes that include + this interface are requested + by a client whose "interest count" for this interface, as defined by + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref>, is zero, the + Connection SHOULD behave as if AddClientInterest was called for this + interface just before that request. Clients that do not explicitly + call AddClientInterest SHOULD NOT call <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml new file mode 100644 index 0000000..395e101 --- /dev/null +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -0,0 +1,624 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Mail_Notification" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Connection.Interface.MailNotification"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.21.3">(as stable API)</tp:added> + + <tp:client-interest> + <tp:docstring> + A client MUST notify interest in this feature before it will be + enabled. + </tp:docstring> + </tp:client-interest> + + <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" > + <tp:flag suffix="Supports_Unread_Mail_Count" value="1"> + <tp:docstring> + This Connection provides the number of unread e-mails (or e-mail + threads) in the main folder of your e-mail account, as the + <tp:member-ref>UnreadMailCount</tp:member-ref> property. The + connection manager will update this value by emitting the + <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Supports_Unread_Mails" value="2"> + <tp:docstring> + This Connection provides a detailed list of unread e-mails, as the + <tp:member-ref>UnreadMails</tp:member-ref> property. If this flag + is set, <tt>Supports_Unread_Mail_Count</tt> MUST be set, and + <tt>Emits_Mails_Received</tt> MUST NOT be set. + The Connection will update the list by emitting the + <tp:member-ref>UnreadMailsChanged</tp:member-ref> signals. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Emits_Mails_Received" value="4"> + <tp:docstring> + This Connection emits the <tp:member-ref>MailsReceived</tp:member-ref> + signal, which provides details about newly arrived e-mails but does + not maintain their read/unread status afterwards. This flag MUST NOT + be combined with <tt>Supports_Unread_Mails</tt>. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Supports_Request_Inbox_URL" value="8"> + <tp:docstring> + This Connection can provide a URL (with optional POST data) to + open the the inbox of the e-mail account in a web-based client, via + the <tp:member-ref>RequestInboxURL</tp:member-ref> method. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Supports_Request_Mail_URL" value="16"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This Connection can provide a URL (with optional POST data) to open + a specific mail in a web-based client, via the + <tp:member-ref>RequestMailURL</tp:member-ref> method. This feature + is not useful unless either Emits_Mails_Received or + Supports_Unread_Mails is set.</p> + + <p>If this flag is not set, clients SHOULD fall back to using + <tp:member-ref>RequestInboxURL</tp:member-ref> if available.</p> + </tp:docstring> + </tp:flag> + <tp:flag suffix="Thread_Based" value="32"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Each <tp:type>Mail</tp:type> represents a thread of e-mails, which + MAY have more than one sender.</p> + + <tp:rationale> + <p>Google Talk notifies users about new mail in terms of unread + threads, rather than unread e-mails.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:docstring> + <p>Flags representing capabilities provided by a connection manager. + Those values can be used as bitfield. Some flags depend on, or + conflict with, each other.</p> + + <p>Connections SHOULD implement as many of these features as the + underlying protocol allows, preferring to implement + Supports_Unread_Mails instead of Emits_Mails_Received if both are + possible.</p> + </tp:docstring> + </tp:flags> + + <tp:enum name="HTTP_Method" type="u"> + <tp:enumvalue suffix="Get" value="0"> + <tp:docstring> + Use the GET method when opening the URL. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Post" value="1"> + <tp:docstring> + Use the POST method when opening the URL. Refer to + <tp:type>HTTP_Post_Data</tp:type> for more details. + </tp:docstring> + </tp:enumvalue> + <tp:docstring> + The HTTP Method with which to request a URL. + </tp:docstring> + </tp:enum> + + <tp:struct name="HTTP_Post_Data" array-name="HTTP_Post_Data_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A pair (key, value) representing POST data compatible with the + application/x-www-form-urlencoded MIME type. The strings MUST be + valid UTF-8 strings, and the characters used in the key MUST obey + the requirements of the + <a href="http://www.w3.org/TR/html401/types.html#type-cdata"> + HTML CDATA type</a>. The value MUST NOT be + encoded with HTML entities.</p> + + <p>For example, if the POST data should contain a key "less-than" with value + "<", and a key "percent" with value "%", this should be represented as + two HTTP_Post_Data structures, ("less-than", "<") and ("percent", "%"), + resulting in a POST request whose request body is "less-than=&lt;&percent=%25". + If a client passes this to a browser by writing it into an HTML form, it + could do so by representing it as:</p> + + <pre> + <input type="hidden" name="less-than">&lt;</input> + <input type="hidden" name="percent">%</input> + </pre> + + <tp:rationale> + <p>This data can be used to generate a HTML file that will + automatically load the URL with appropriate POST data, in which case + the client MUST convert any characters that are special within HTML + into HTML entities. Alternatively, it can be used in an API that will + instruct the browser how to load the URL (like the Netscape Plug-in + API), in which case the client MUST escape + <a href="http://www.ietf.org/rfc/rfc1738.txt">characters that are + reserved in URLs</a>, if appropriate for that API.</p> + + <p>An array of pairs is used instead of a map from keys to values, + because it's valid to repeat keys in both HTML and + x-www-form-urlencoded data.</p> + </tp:rationale> + </tp:docstring> + <tp:member type="s" name="Key"> + <tp:docstring>The key, corresponding to a HTML control + name</tp:docstring> + </tp:member> + <tp:member type="s" name="Value"> + <tp:docstring>The value</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Mail_Address" array-name="Mail_Address_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A pair (name, address) representing an e-mail address, + such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At + least one of name and address MUST be provided. A missing element will + be represented by the empty string.</p> + <tp:rationale> + <p>The CM should provide as much information as possible, but not all + protocols provide both the displayed name and the address. (If a + protocol doesn't provide either, it should omit the appropriate + field from the <tp:type>Mail</tp:type> entirely.)</p> + </tp:rationale> + </tp:docstring> + <tp:member type="s" name="Name"> + <tp:docstring>The displayed name corresponding to the e-mail + address</tp:docstring> + </tp:member> + <tp:member type="s" name="Address"> + <tp:docstring>The actual e-mail address</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Mail_URL"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A structure containing the required information to open a web-based + e-mail UI, without needing re-authentication (if possible).</p> + + <p>Because the URL and POST data frequently contain short-lived + credential tokens, a new URL should be requested (by calling one of + the methods that returns a Mail_URL) for each visit to the web-based + UI, and the URL should be visited soon after it is returned.</p> + </tp:docstring> + <tp:member type="s" name="URL"> + <tp:docstring> + The URL to which to send a request. + </tp:docstring> + </tp:member> + <tp:member type="u" name="Method" tp:type="HTTP_Method"> + <tp:docstring> + The HTTP method of the request. + </tp:docstring> + </tp:member> + <tp:member type="a(ss)" name="Post_Data" tp:type="HTTP_Post_Data[]"> + <tp:docstring> + An array of name-value pairs containing the POST data to use when + opening the URL. This MUST be an empty array if the Method is not + POST. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Mail" array-name="Mail_List"> + <tp:docstring> + An extensible map representing a mail, or (on protocols where + <tt>Thread_Based</tt> appears in + <tp:member-ref>MailNotificationFlags</tp:member-ref>) a thread of + mails. All keys are optional where not otherwise stated; however, at + least one of "senders" and "subject" must be included. + </tp:docstring> + + <tp:member type="s" name="Key"> + <tp:docstring> + <p>A key providing information about the mail or thread. Well-known + keys are as follows:</p> + + <dl> + <dt>id — s</dt> + <dd> + <p>A unique ID for this e-mail. CMs with + <tt>Supports_Unread_Mails</tt> set in + <tp:member-ref>MailNotificationFlags</tp:member-ref> MUST provide + this key in each <tp:type>Mail</tp:type>.</p> + + <p>If provided, the ID SHOULD be unique to a Mail at least until + that mail is removed with the + <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal + (in protocols with <tt>Supports_Unread_Emails</tt>), or + unique for the duration of a session (otherwise).</p> + + <tp:rationale> + <p>In protocols with Supports_Unread_Mails, this key is used to + indicate which mail was removed. In protocols without that + feature, it's impossible to tell when a mail has been removed + (and hence how long the identifier will remain valid for use + with <tp:member-ref>RequestMailURL</tp:member-ref>).</p> + </tp:rationale> + </dd> + + <dt>url-data — any type</dt> + <dd>An opaque identifier (typically a string or list of strings) + provided to the Connection when calling + <tp:member-ref>RequestMailURL</tp:member-ref>, + containing information used by the Connection to build the URL. + </dd> + + <dt>senders — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> + <dd> + An array of sender display name and e-mail address pairs. Note that + only e-mails represented as a thread can have multiple senders. + </dd> + + <dt>to-addresses — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> + <dd> + An array of display name and e-mail address pairs representing + the recipients. + </dd> + + <dt>cc-addresses — a(ss) (<tp:type>Mail_Address</tp:type>)</dt> + <dd> + An array of display name and e-mail address pairs representing + the carbon-copy recipients. + </dd> + + <dt>sent-timestamp — x (<tp:type>Unix_Timestamp64</tp:type>)</dt> + <dd>A UNIX timestamp indicating when the message was sent, or for + a thread, when the most recent message was sent. + </dd> + + <dt>received-timestamp — x (<tp:type>Unix_Timestamp64</tp:type>)</dt> + <dd>A UNIX timestamp indicating when the message was received, or for + a thread, when the most recent message was received. + </dd> + + <dt>has-attachments — b</dt> + <dd>If true, this mail has attachments.</dd> + + <dt>subject — s</dt> + <dd> + The subject of the message. This MUST be encoded in UTF-8. + </dd> + + <dt>content-type — s</dt> + <dd> + <p>The MIME type of the message content. Two types are currently + supported: "text/plain" for plain text, and "text/html" for a + HTML document. If omitted, "text/plain" MUST be assumed. + Regardless of MIME type, the content MUST be valid UTF-8 (which + may require that the Connection transcodes it from a legacy + encoding).</p> + + <tp:rationale> + <p>All strings on D-Bus must be UTF-8.</p> + </tp:rationale> + </dd> + + <dt>truncated — b</dt> + <dd> + If true, the content is only a partial message; if false or + omitted, the content is the entire message. + </dd> + + <dt>content — s</dt> + <dd> + The body of the message, possibly truncated, encoded as appropriate + for "content-type". + </dd> + + <dt>folder — s</dt> + <dd> + The name of the folder containing this e-mails. + If omitted, the inbox SHOULD be assumed. + </dd> + </dl> + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring>The value, of whatever type is appropriate for the + key.</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="MailNotificationFlags" type="u" access="read" + tp:type="Mail_Notification_Flags" + tp:name-for-bindings="Mail_Notification_Flags"> + <tp:docstring> + Integer representing the bitwise-OR of supported features for e-mails + notification on this server. This property MUST NOT change after the + Connection becomes CONNECTED. + + <tp:rationale> + This property indicates the behavior and availability + of the other properties and signals within this interface. A + connection manager that cannot at least set one of the flags + in the <tp:type>Mail_Notification_Flags</tp:type> + SHOULD NOT provide this interface. + </tp:rationale> + </tp:docstring> + </property> + + <property name="UnreadMailCount" type="u" access="read" + tp:name-for-bindings="Unread_Mail_Count"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The number of unread messages in the Inbox. Change notification is + via <tp:member-ref>UnreadMailsChanged</tp:member-ref>.</p> + + <p>This property is only useful if <tt>Supports_Unread_Mail_Count</tt> + is set in the <tp:member-ref>MailNotificationFlags</tp:member-ref>; + otherwise, it MUST be zero.</p> + + <p>If <tt>Thread_Based</tt> appears in the + <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property + counts the number of threads, not the number of mails.</p> + + <p>Note that this count MAY be bigger than the number of items in + <tp:member-ref>UnreadMails</tp:member-ref>. See + <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p> + </tp:docstring> + </property> + + <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]" + tp:name-for-bindings="Unread_Mails" access="read"> + <tp:docstring> + <p>An array of unread <tp:type>Mail</tp:type>s. Change notification is + via <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property + is only useful if <tt>Supports_Unread_Mails</tt> is set in + <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it + MUST be an empty list.</p> + <p>The array size MAY be shorter than + <tp:member-ref>UnreadMailCount</tp:member-ref>.</p> + <tp:rationale> + <p>Some servers may limits the amount of detailed e-mails sent. This + can significantly reduce the network traffic for large inbox. For + this reason, it is normal that + <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal + to the size of this array.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="MailAddress" type="s" + tp:name-for-bindings="Mail_Address" access="read"> + <tp:docstring> + A string representing the e-mail address of the account. The CMs MUST + provide this information. + <tp:rationale> + In close integration of MailNotification with other e-mail services, + the e-mail address can be used has a unique identifier for the + account. Possible integration could be between Telepathy and + Evolution where the e-mail address is the common information in + both interfaces. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="MailsReceived" tp:name-for-bindings="Mails_Received"> + <arg name="Mails" type="aa{sv}" tp:type="Mail[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of <tp:type>Mail</tp:type>s. Those e-mail MUST NOT have + the "id" key.</p> + + <tp:rationale> + <p>On connections that emit this signal, it's impossible to tell + when a mail has been removed, and hence when "id" has become + invalid.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <tp:docstring> + Emitted when new e-mails messages arrive to the inbox associated with + this connection. This signal is used for protocols that are not able + to maintain the <tp:member-ref>UnreadMails</tp:member-ref> list, but + do provide real-time notification about newly arrived e-mails. It MUST + NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in + <tp:member-ref>MailNotificationFlags</tp:member-ref>. + </tp:docstring> + </signal> + + <signal name="UnreadMailsChanged" + tp:name-for-bindings="Unread_Mails_Changed"> + <arg name="Count" type="u"> + <tp:docstring> + Number of unread messages in the inbox (the new value of + <tp:member-ref>UnreadMailCount</tp:member-ref>). + </tp:docstring> + </arg> + <arg name="Mails_Added" type="aa{sv}" tp:type="Mail[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of <tp:type>Mail</tp:type> that are being added or updated + in <tp:member-ref>UnreadMails</tp:member-ref>.</p> + + <tp:rationale> + <p>Mails may be updated when the URL information (URL and POST data) + have changed, or senders were added or removed from an e-mail + thread.</p> + </tp:rationale> + + <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list + MUST be empty, even if Count has increased.</p> + </tp:docstring> + </arg> + <arg name="Mails_Removed" type="as"> + <tp:docstring> + A list of e-mail IDs that are being removed from + <tp:member-ref>UnreadMails</tp:member-ref>. + If the <tt>Supports_Unread_Mails</tt> flag is not set, this list + MUST be empty, even if Count has decreased. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or + <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST + NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set + in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p> + + <p><tt>Mails_Added</tt> and + <tt>Mails_Removed</tt> MUST be empty if the + <tt>Supports_Unread_Mails</tt> flag is not set.</p> + </tp:docstring> + </signal> + + <method name="RequestInboxURL" + tp:name-for-bindings="Request_Inbox_URL"> + <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" > + <tp:docstring> + A struture containing a URL and optional additional data to open a + webmail client, without re-authentication if possible. + </tp:docstring> + </arg> + <tp:docstring> + This method creates and returns a URL and an optional POST data that + allow opening the Inbox folder of a webmail account. This URL MAY + contain tokens with a short lifetime, so clients SHOULD request a new + URL for each visit to the webmail interface. This method is implemented + only if the <tt>Supports_Request_Inbox_URL</tt> flag is set in + <tp:member-ref>MailNotificationFlags</tp:member-ref>. + + <tp:rationale> + We are not using properties here because the tokens are unsuitable + for sharing between clients, and network round-trips may be required + to obtain the information that leads to authentication free webmail + access. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + </tp:possible-errors> + </method> + + <method name="RequestMailURL" + tp:name-for-bindings="Request_Mail_URL"> + <arg direction="in" name="ID" type="s"> + <tp:docstring> + The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type> + structure, or the empty string if no <tt>id</tt> key was provided. + </tp:docstring> + </arg> + <arg direction="in" name="URL_Data" type="v"> + <tp:docstring> + Whatever <tt>url-data</tt> was found in the <tp:type>Mail</tp:type> + structure, or the boolean value False (D-Bus type 'b') if no + <tt>url-data</tt> was provided in the Mail. + </tp:docstring> + </arg> + <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" > + <tp:docstring> + A struture that contains a URL and optional additional data to open a + webmail client, without re-authentication if possible. + </tp:docstring> + </arg> + <tp:docstring> + This method creates and returns a URL and optional POST data that + allow opening a specific mail in a webmail interface. This + method is implemented only if <tt>Supports_Request_Mail_URL</tt> flag + is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>. + <tp:rationale> + See <tp:member-ref>RequestInboxURL</tp:member-ref> for design + rationale. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface to support receiving notifications about a e-mail + account associated with this connection.</p> + + <p>In protocols where this is possible, this interface also allows the + connection manager to provide the necessary information for clients + to open a web-based mail client without having to re-authenticate.</p> + + <p>To use this interface, a client MUST first subscribe by passing the + name of this interface to the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref> method. The subscription + mechanic aims at reducing network traffic and memory footprint in the + situation where nobody is currently interesting in provided + information. When done with this interface, clients SHOULD call + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> to allow the CM to + release resources.</p> + + <p>Protocols have various different levels of Mail Notification support. + To describe the level of support, the interface provides a property + called <tp:member-ref>MailNotificationFlags</tp:member-ref>. + Not all combinations are valid; protocols can be divided into four + categories as follows.</p> + + <p>Connections to the most capable protocols, such as Google's XMPP Mail + Notification extension, have the Supports_Unread_Mails flag (this + implies that they must also have Supports_Unread_Mail_Count, but not + Emits_Mails_Received). On these connections, clients + requiring change notification MUST monitor the + <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and + either recover the initial state from the + <tp:member-ref>UnreadMails</tp:member-ref> property (if they require + details other than the number of mails) or the + <tp:member-ref>UnreadMailCount</tp:member-ref> property (if they + are only interested in the number of unread mails). The + <tp:member-ref>MailsReceived</tp:member-ref> signal is never emitted + on these connections, so clients that will display a short-term + notification for each new mail MUST do so in response to emission of + the <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.</p> + + <p>The most common situation, seen in protocols like MSN and Yahoo, is + that the number of unread mails is provided and kept up-to-date, + and a separate notification is emitted with some details of each new + mail. This is a combination of the following two features, and clients + SHOULD implement one or both as appropriate for their requirements.</p> + + <p>On protocols that have the Emits_Mails_Received flag (which implies + that they do not have Supports_Unread_Mails), the CM does not keep + track of any mails; it simply emits a notification whenever new mail + arrives. Those events may be used for short term display (like a + notification popup) to inform the user. No protocol is known to support + only this feature, but it is useful for integration with libraries that + that do not implement tracking of the number of mails. Clients + requiring these notifications MUST monitor the + <tp:member-ref>MailsReceived</tp:member-ref> signal on any connections + with this flag.</p> + + <p>On protocols that have the Supports_Unread_Mail_Count flag but not + the Supports_Unread_Mails flag, clients cannot display complete + details of unread email, but can display an up-to-date count of the + <em>number</em> of unread mails. To do this, they must monitor the + <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and + retrieve the initial state from the + <tp:member-ref>UnreadMailCount</tp:member-ref> property.</p> + + <p> + Orthogonal features described by the + <tp:member-ref>MailNotificationFlags</tp:member-ref> property include the + RequestSomethingURL methods, which are used to obtain URLs allowing + clients to open a webmail client. Connections SHOULD support as many + of these methods as possible.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> + diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml new file mode 100644 index 0000000..571bf6d --- /dev/null +++ b/spec/Connection_Interface_Power_Saving.xml @@ -0,0 +1,109 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Power_Saving" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright> Copyright © 2007-2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface + name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some protocols support mechanisms for reducing bandwidth usage—and + hence power usage, on mobile devices—when the user is not directly + interacting with their IM client. For instance, Google Talk's XMPP + server supports queueing incoming presence updates at the client's + instruction; the client can instruct the server to deliver all + outstanding presence updates at a later time. This interface may be + used to instruct the connection manager to enable and disable such + protocol-level features when a screensaver is activated, the device + screen is locked, and so on, by calling the + <tp:member-ref>SetPowerSaving</tp:member-ref> method.</p> + + <p>Enabling power saving SHOULD NOT change behaviour in any way + that is noticable to a user not actively interacting with their client. + For example, delaying presence updates somewhat is unlikely to be + noticed by a user not staring at their device waiting for a contact to + come online; on the other hand, requesting that the server queue + incoming messages would be noticable by the user, so is not an + acceptable effect of calling + <tp:member-ref>SetPowerSaving</tp:member-ref>.</p> + </tp:docstring> + + <method name="SetPowerSaving" tp:name-for-bindings="Set_Power_Saving"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Turn power saving mode on or off.</p> + + <tp:rationale> + <p>Depending on the device's activity level, the + connection can have its power saving mode turned on or off.</p> + </tp:rationale> + + <p>Errors raised by this method indicate that power saving could not be + enabled, which SHOULD NOT generally be treated as fatal.</p> + + <tp:rationale> + If the CM cannot switch modes, either because of the + protocol (<code>NotImplemented</code>), or because of the service + (<code>NotAvailable</code>), Mission Control (or whoever manages this) + should be made aware. The error could be ignored or, in the extreme, + be fascist and disconnect the account. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Activate" type="b"> + <tp:docstring> + <code>True</code> if protocol-level power saving features should be + activated; <code>False</code> if they should be de-activated. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The current connection has no power saving features. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + </tp:possible-errors> + </method> + + <property name="PowerSavingActive" type="b" access="read" + tp:name-for-bindings="Power_Saving_Active"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p><code>True</code> if protocol-level power saving features are + currently activated. This property can be changed using the + <tp:member-ref>SetPowerSaving</tp:member-ref> method; change + notifications is via the + <tp:member-ref>PowerSavingChanged</tp:member-ref> signal.</p> + </tp:docstring> + </property> + + <signal name="PowerSavingChanged" + tp:name-for-bindings="Power_Saving_Changed"> + <arg name="Active" type="b"> + <tp:docstring> + The new state of the power saving feature. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <tp:member-ref>PowerSavingActive</tp:member-ref> + property changed. + </tp:docstring> + </signal> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml new file mode 100644 index 0000000..8a344d4 --- /dev/null +++ b/spec/Connection_Interface_Presence.xml @@ -0,0 +1,346 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright (C) 2005, 2006 Collabora Limited + </tp:copyright> + <tp:copyright> +Copyright (C) 2005, 2006 Nokia Corporation + </tp:copyright> + <tp:copyright> +Copyright (C) 2006 INdT + </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> + + <tp:mapping name="Multiple_Status_Map"> + <tp:docstring>Mapping used in + <tp:type>Last_Activity_And_Statuses</tp:type> and passed to + <tp:member-ref>SetStatus</tp:member-ref>, representing a collection of + statuses. Use of this mapping with more than one member is + deprecated.</tp:docstring> + <tp:member type="s" name="Status"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> + </tp:mapping> + <tp:struct name="Last_Activity_And_Statuses" array-name=""> + <tp:docstring>Structure representing a contact's presence, containing + a last-activity time (deprecated) and a Multiple_Status_Map. + </tp:docstring> + <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/> + <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map" + name="Statuses"/> + </tp:struct> + <tp:mapping name="Contact_Presences"> + <tp:docstring>Mapping returned by + <tp:member-ref>GetPresence</tp:member-ref> and signalled by + <tp:member-ref>PresenceUpdate</tp:member-ref>, where the keys are + contacts and the values represent their presences.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses" + name="Presence"/> + </tp:mapping> + <tp:struct name="Status_Spec" array-name=""> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/> + <tp:member type="b" name="May_Set_On_Self"/> + <tp:member type="b" name="Exclusive"/> + <tp:member type="a{ss}" tp:type="String_String_Map" + name="Parameter_Types"/> + </tp:struct> + <tp:mapping name="Status_Spec_Map"> + <tp:member type="s" name="Identifier"/> + <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/> + </tp:mapping> + + <method name="AddStatus" tp:name-for-bindings="Add_Status"> + <arg direction="in" name="Status" type="s"> + <tp:docstring> + The string identifier of the desired status + </tp:docstring> + </arg> + <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + A dictionary of optional parameter names mapped to their variant-boxed values + </tp:docstring> + </arg> + <tp:docstring> + Request that a single presence status is published for the user, along + with any desired parameters. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <method name="ClearStatus" tp:name-for-bindings="Clear_Status"> + <tp:docstring> + Request that all of a user's presence statuses be removed. Be aware + that this request may simply result in the statuses being replaced by a + default available status. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <method name="GetPresence" tp:name-for-bindings="Get_Presence"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> + <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}" + tp:type="Contact_Presences"> + <tp:docstring> + Presence information in the same format as for the + <tp:member-ref>PresenceUpdate</tp:member-ref> signal + </tp:docstring> + </arg> + <tp:docstring> + Get presence previously emitted by + <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts. + Data is returned in the same structure as the PresenceUpdate signal. + Using this method in favour of + <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that + it will not wake up each client connected to the PresenceUpdate signal. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + <method name="GetStatuses" tp:name-for-bindings="Get_Statuses"> + <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map" + name="Available_Statuses"> + <tp:docstring> + A dictionary of string identifiers mapped to a struct for each status, containing: + <ul> + <li>a type value from one of the values above</li> + <li>a boolean to indicate if this status may be set on yourself</li> + <li>a boolean to indicate if this is an exclusive status which you + may not set alongside any other</li> + <li>a dictionary of valid optional string argument names mapped to + their types</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Get a dictionary of the valid presence statuses for this connection. + This is only available when online because only some statuses will + be available on some servers. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + <signal name="PresenceUpdate" tp:name-for-bindings="Presence_Update"> + <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences"> + <tp:docstring> + A dictionary of contact handles mapped to a struct containing + a UNIX timestamp of the last activity time (in UTC), and + a dictionary mapping the contact's current status identifiers to + a dictionary of optional parameter names mapped to their + variant-boxed values + </tp:docstring> + </arg> + <tp:docstring> + This signal should be emitted when your own presence has been changed, + or the presence of the member of any of the connection's channels has + been changed, or when the presence requested by + <tp:member-ref>RequestPresence</tp:member-ref> is available. + </tp:docstring> + </signal> + <method name="RemoveStatus" tp:name-for-bindings="Remove_Status"> + <arg direction="in" name="Status" type="s"> + <tp:docstring> + The string identifier of the status not to publish anymore for the user + </tp:docstring> + </arg> + <tp:docstring> + Request that the given presence status is no longer published for the + user. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As + with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may + actually result in it being replaced by a default available status. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring>The status requested is not currently set</tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="RequestPresence" tp:name-for-bindings="Request_Presence"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> + <tp:docstring> + Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref> + signal will be emitted when they are received. This is not the same as + subscribing to the presence of a contact, which must be done using the + 'subscription' <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>, + and on some protocols presence information may not be available unless + a subscription exists. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The presence of the requested contacts is not reported to this connection + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="SetLastActivityTime" + tp:name-for-bindings="Set_Last_Activity_Time"> + <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A UNIX timestamp of the user's last activity time (in UTC) + </tp:docstring> + </arg> + <tp:docstring> + Request that the recorded last activity time for the user be updated on + the server. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + This protocol has no concept of idle time + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="SetStatus" tp:name-for-bindings="Set_Status"> + <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map"> + <tp:docstring> + A dictionary mapping status identifiers to dictionaries, which + map optional parameter names to their variant-boxed values + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the user's presence be changed to the given statuses + and desired parameters. Changes will be reflected by + <tp:member-ref>PresenceUpdate</tp:member-ref> + signals being emitted.</p> + + <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.</p> + + <tp:rationale> + <p>The same rationale as for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref> + applies.</p> + </tp:rationale> + + <p>On certain protocols, this method may be + called on a newly-created connection which is still in the + DISCONNECTED state, and will sign on with the requested status. + If the requested status is not available after signing on, + NotAvailable will be returned and the connection will remain + offline, or if the protocol does not support signing on with + a certain status, Disconnected will be returned.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:deprecated version="0.17.21">Client implementations + SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + instead.</tp:deprecated> + <tp:changed version="0.17.23">Connection managers implementing + Presence MUST implement SimplePresence too.</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + + <p>This interface is for services which have a concept of presence which + can be published for yourself and monitored on your contacts. + Telepathy's definition of presence is based on that used by + <a href="http://www.galago-project.org/">the Galago project</a>.</p> + + <p>Presence on an individual (yourself or one of your contacts) is modelled as + a last activity time along with a set of zero or more statuses, each of + which may have arbitrary key/value parameters. Valid statuses are defined + per connection, and a list of them can be obtained with the + <tp:member-ref>GetStatuses</tp:member-ref> method.</p> + + <p>(The SimplePresence interface which replaces this one restricts + presences to one status per contact, with an optional message, which is + in practice all that was implemented on this interface.)</p> + + <p>Each status has an arbitrary string identifier which should have an agreed + meaning between the connection manager and any client which is expected to + make use of it. The well-known values defined by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + interface SHOULD be used where possible</p> + + <p>As well as these well-known status identifiers, every status also has a + numerical type value chosen from + <tp:type>Connection_Presence_Type</tp:type> which can be used by the client + to classify even unknown statuses into different fundamental types.</p> + + <p>These numerical types exist so that even if a client does not understand + the string identifier being used, and hence cannot present the presence to + the user to set on themselves, it may display an approximation of the + presence if it is set on a contact.</p> + + <p>The dictionary of variant types allows the connection manager to exchange + further protocol-specific information with the client. It is recommended + that the string (s) argument 'message' be interpreted as an optional + message which can be associated with a presence status.</p> + + <p>If the connection has a 'subscribe' contact list, + <tp:member-ref>PresenceUpdate</tp:member-ref> signals should be emitted to + indicate changes of contacts on this list, and should also be emitted for + changes in your own presence. Depending on the protocol, the signal may + also be emitted for others such as people with whom you are communicating, + and any user interface should be updated accordingly.</p> + + <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> may + only succeed on contacts on your 'subscribe' list, and other contacts will + cause a PermissionDenied error. On protocols where there is no 'subscribe' + list, and RequestPresence succeeds, a client may poll the server + intermittently to update any display of presence information.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml new file mode 100644 index 0000000..b89d968 --- /dev/null +++ b/spec/Connection_Interface_Privacy.xml @@ -0,0 +1,94 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Privacy" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Privacy" + tp:causes-havoc='not well-tested'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <method name="GetPrivacyMode" tp:name-for-bindings="Get_Privacy_Mode"> + <arg direction="out" type="s"> + <tp:docstring> + A string representing the current privacy mode + </tp:docstring> + </arg> + <tp:docstring> + Return the current privacy mode, which must be one of the values + returned by GetPrivacyModes. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + <method name="GetPrivacyModes" tp:name-for-bindings="Get_Privacy_Modes"> + <arg direction="out" type="as"> + <tp:docstring> + An array of valid privacy modes for this connection + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Returns the privacy modes available on this connection. The following + well-known names should be used where appropriate: + <dl> + <dt>allow-all</dt><dd>any contact may initiate communication</dd> + <dt>allow-specified</dt><dd>only contacts on your 'allow' list may initiate communication</dd> + <dt>allow-subscribed</dt><dd>only contacts on your subscription list may initiate communication</dd> + </dl> + </tp:docstring> + </method> + <signal name="PrivacyModeChanged" + tp:name-for-bindings="Privacy_Mode_Changed"> + <arg name="Mode" type="s"> + <tp:docstring> + The current privacy mode + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the privacy mode is changed or the value has been + initially received from the server. + </tp:docstring> + </signal> + <method name="SetPrivacyMode" tp:name-for-bindings="Set_Privacy_Mode"> + <arg direction="in" name="Mode" type="s"> + <tp:docstring> + The desired privacy mode + </tp:docstring> + </arg> + <tp:docstring> + Request that the privacy mode be changed to the given value, which + must be one of the values returned by GetPrivacyModes. Success is + indicated by the method returning and the PrivacyModeChanged + signal being emitted. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + <tp:docstring> + An interface to support getting and setting privacy modes to configure + situations such as not being contactable by people who are not on your + subscribe list. If this interface is not implemented, the default can be + presumed to be allow-all (as defined in GetPrivacyModes). + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml new file mode 100644 index 0000000..d08b748 --- /dev/null +++ b/spec/Connection_Interface_Renaming.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Renaming" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming" + tp:causes-havoc='not well-tested'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <signal name="Renamed" tp:name-for-bindings="Renamed"> + <arg name="Original" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the original identifier + </tp:docstring> + </arg> + <arg name="New" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the new identifier + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the unique identifier of a contact on the server + changes.</p> + + <p>Any channels associated with the contact's original handle will + continue to be to that handle, and so are no longer useful (unless + the contact renames back, or another contact connects with that + unique ID). Clients may open a similar channel associated with the + new handle to continue communicating with the contact.</p> + + <p>For example, if a GUI client associates text + channels with chat windows, it should detach the old channel + from the chat window, closing it, and associate a channel to the + new handle with the same window.</p> + + <p>If the contact's old handle is in any of the member lists of + a channel which has the groups interface, it will be removed from + the channel and the new handle will be added. The resulting + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> + signal must be emitted <em>after</em> the + <tp:member-ref>Renamed</tp:member-ref> signal; the reason should be + RENAMED. + </p> + + <p>The handles may be either general-purpose or channel-specific. + If the original handle is general-purpose, the new handle must be + general-purpose; if the original handle is channel-specific, the + new handle must be channel-specific in the same channel. + </p> + </tp:docstring> + </signal> + <method name="RequestRename" tp:name-for-bindings="Request_Rename"> + <arg direction="in" name="Identifier" type="s"> + <tp:docstring> + The desired identifier + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the user's own identifier is changed on the server. + If successful, a <tp:member-ref>Renamed</tp:member-ref> signal will + be emitted for the current "self handle" as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>.</p> + <p>It is protocol-dependent how the identifier that's actually + used will be derived from the supplied identifier; some sort of + normalization might take place.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <tp:docstring> + An interface on connections to support protocols where the unique + identifiers of contacts can change. Because handles are immutable, + this is represented by a pair of handles, that representing the + old name, and that representing the new one. + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml new file mode 100644 index 0000000..2f233fa --- /dev/null +++ b/spec/Connection_Interface_Requests.xml @@ -0,0 +1,628 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Requests" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Requests"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.11">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An enhanced version of the Telepathy connection interface, which can + represent bundles of channels that should be dispatched together, and + does not assume any particular properties by which channels are + uniquely identifiable.</p> + + <p>If this interface is implemented on a connection, then + <tp:member-ref>NewChannels</tp:member-ref> MUST be emitted for + all new channels, even those created with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection" + >RequestChannel</tp:dbus-ref>.</p> + </tp:docstring> + + <tp:struct name="Channel_Details" array-name="Channel_Details_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + + <tp:docstring> + Enough details of a channel that clients can work out how to dispatch + or handle it. + </tp:docstring> + + <tp:member name="Channel" type="o"> + <tp:docstring> + The object path of the channel. + </tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel.</p> + + <p>Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.</p> + + <tp:rationale> + <p>If properties that could change were included, the following + race condition would be likely to exist in some cases:</p> + + <ul> + <li>NewChannels or Get("Channels") includes a property P with + value V1</li> + <li>Client creates a proxy object for the channel</li> + <li>The value of P changes to V2</li> + <li>Client connects to PChanged signal</li> + <li>Client should call Get("P") or GetAll here, to avoid the + race, but client's author has forgotten to do so</li> + <li>Proxy object thinks P == V1, but actually P == V2</li> + </ul> + + <p>We've taken the opportunity to make the API encourage the + client author to get it right. Where possible, we intend that + properties whose value will be used in channel dispatching + or other "early" processing will be defined so that they are + immutable (can never change).</p> + </tp:rationale> + + <p>Each dictionary MUST contain the keys + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref> + and + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>. + </p> + + <tp:rationale> + <p>We expect these to be crucial to the channel-dispatching + process.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:changed version="0.17.14">It is now guaranteed that + CreateChannel returns the channel before NewChannels announces it + (the reverse was previously guaranteed).</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that an entirely new channel is created.</p> + + <tp:rationale> + <p>There is deliberately no flag corresponding to the + suppress_handler argument to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>, + because passing a FALSE value for that argument is deprecated. + Requests made using this interface always behave as though + suppress_handler was TRUE.</p> + </tp:rationale> + + </tp:docstring> + + <arg direction="in" name="Request" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties, which MUST include + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>. + Some properties + are defined such that only an exact match makes sense, and + connection managers MUST NOT satisfy a request with a channel + where that property does not match; some properties are defined + such that the connection manager MAY treat the request as merely + a hint, and make a best-effort attempt to satisfy it. This is + documented separately for each property.</p> + + <p>If this dictionary contains a property whose semantics + are not known to the connection manager, this method MUST fail + without side-effects (in particular it must not create a new + channel).</p> + + <tp:rationale> + <p>This is necessary if we want to be able to invent properties + in future that, when used in a request, are hard requirements + rather than just hints. A connection manager that did not know + the semantics of those properties could incorrectly return a + new channel that did not satisfy the requirements.</p> + </tp:rationale> + + <p>The connection manager MUST NOT respond successfully, + and SHOULD NOT create a new channel or cause any other + side-effects, unless it can create a new channel that satisfies + the client's requirements.</p> + + <p>Properties that will be set by this argument need not have write + access after the channel has been created - indeed, it is + expected that most will be read-only.</p> + </tp:docstring> + </arg> + + <arg name="Channel" direction="out" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Channel object, which MUST NOT be signalled with + <tp:member-ref>NewChannels</tp:member-ref> until after this method + returns.</p> + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" direction="out" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel that was produced, equivalent to + the properties in <tp:type>Channel_Details</tp:type>. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + <tp:type>Channel_Details</tp:type>.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + An invalid handle was requested as the value of a property whose + value is a handle (like + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request matched the fixed properties of a + <tp:type>Requestable_Channel_Class</tp:type> in + <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + allowed arguments did not make sense; for example, a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> + was requested, but the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> + property provided was not a valid DNS name. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requested channel cannot be created, but in + principle, a similar request might succeed in future. + For instance, this might be because:</p> + + <ul> + <li>a channel matching the request already exists and the + protocol requires that only one such channel can exist at a + time</li> + <li>a channel matching the request has already been requested + (by a previous call to CreateChannel, + <tp:member-ref>EnsureChannel</tp:member-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> + or similar) and the protocol requires that only one such + channel can exist at a time</li> + </ul> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> + <tp:added version="0.17.12"/> + <tp:changed version="0.17.14">It is now guaranteed that if + the channel was created by this call to EnsureChannel, it's returned + before NewChannels announces it (the reverse was previously + guaranteed).</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that channels are ensured to exist.</p> + + <tp:rationale> + <p>The connection manager is in the best position to determine which + existing channels could satisfy which requests.</p> + </tp:rationale> + + </tp:docstring> + + <arg direction="in" name="Request" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties, with the same + semantics as the corresponding parameter to + <tp:member-ref>CreateChannel</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg name="Yours" direction="out" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If false, the caller of EnsureChannel MUST assume that some + other process is handling this channel; if true, the caller of + EnsureChannel SHOULD handle it themselves or delegate it to another + client.</p> + + <p>If the creation of a channel makes several calls to EnsureChannel + (and no other requests) successful, exactly one of those calls MUST + return a true value for this argument.</p> + + <p>If the creation of a channel makes other requests successful, + the value returned for this argument MUST be such that exactly + one of the clients making requests ends up responsible for the + channel. In particular, if + <tp:member-ref>CreateChannel</tp:member-ref> returns a channel + <em>C</em>, any EnsureChannel calls that also return <em>C</em> + MUST return a false value for this argument.</p> + </tp:docstring> + </arg> + + <arg name="Channel" direction="out" type="o"> + <tp:docstring> + The Channel object. If it was created as a result of this method + call, it MUST NOT be signalled by + <tp:member-ref>NewChannels</tp:member-ref> until after this method + returns. + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" direction="out" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel that was produced, equivalent to + the properties in <tp:type>Channel_Details</tp:type>. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + <tp:type>Channel_Details</tp:type>.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + An invalid handle was requested as the value of a property whose + value is a handle (like + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request matched the fixed properties of a + <tp:type>Requestable_Channel_Class</tp:type> in + <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + allowed arguments did not make sense; for example, a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> + was requested, but the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> + property provided was not a valid DNS name. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <signal name="NewChannels" tp:name-for-bindings="New_Channels"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:changed version="0.17.14">Added a guarantee of ordering + relative to NewChannel</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>New channels have been created. The connection manager SHOULD emit + a single signal for any group of closely related channels that are + created at the same time, so that the channel dispatcher can try to + dispatch them to a handler as a unit.</p> + + <p>In particular, if additional channels are created as a side-effect + of a call to <tp:member-ref>CreateChannel</tp:member-ref>, + these channels SHOULD appear in the same NewChannels signal as + the channel that satisfies the request.</p> + + <tp:rationale> + <p>Joining a MUC Tube in XMPP requires joining the corresponding + MUC (chatroom), so a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + channel can be created as a side-effect.</p> + </tp:rationale> + + <p>Every time NewChannels is emitted, it MUST be followed by + a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal for each channel.</p> + + <tp:rationale> + <p>The double signal emission is for the benefit of older Telepathy + clients, which won't be listening for NewChannels.</p> + + <p>The more informative NewChannels signal comes first so that + clients that did not examine the connection to find + out whether Requests is supported will see the more informative + signal for each channel first, and then ignore the less + informative signal because it announces a new channel of which + they are already aware.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"> + <tp:docstring> + The channels and their details. All channels that are signalled + together like this MUST have the same + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> + property, which may + either refer to an existing bundle, or establish a new bundle. + </tp:docstring> + </arg> + </signal> + + <property name="Channels" tp:name-for-bindings="Channels" + type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring> + A list of all the channels which currently exist on this connection. + Change notification is via the + <tp:member-ref>NewChannels</tp:member-ref> and + <tp:member-ref>ChannelClosed</tp:member-ref> signals. + </tp:docstring> + </property> + + <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring> + Emitted when a channel is closed and hence disappears from the + <tp:member-ref>Channels</tp:member-ref> property. + + <tp:rationale> + This is redundant with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref> + signal on the channel itself, but it does provide full change + notification for the Channels property. + </tp:rationale> + </tp:docstring> + + <arg name="Removed" type="o"> + <tp:docstring> + The channel which has been removed from the Channels property + </tp:docstring> + </arg> + </signal> + + <tp:mapping name="Channel_Class" array-name="Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Mapping representing a class of channels that can be requested + from a connection manager, can be handled by a user interface, + are supported by a contact, etc.</p> + + <p>Classes of channel are identified by the fixed values of + a subset of their properties.</p> + + <p>Channel classes SHOULD always include the keys + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref> + and + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>. + </p> + </tp:docstring> + + <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> + <tp:docstring> + A D-Bus interface name, followed by a dot and a D-Bus property name. + </tp:docstring> + </tp:member> + + <tp:member type="v" name="Value"> + <tp:docstring> + The value of the property. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Requestable_Channel_Class" + array-name="Requestable_Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Structure representing a class of channels that can be requested, + identified by a set of properties that identify that class of + channel.</p> + + <tp:rationale> + <p>This will often just be the channel type and the handle type, + but can include other properties of the channel - for instance, + encrypted channels might require properties that + unencrypted channels do not, like an encryption key.</p> + </tp:rationale> + + <p>In some cases, these classes of channel may overlap, in the sense + that one class fixes all the properties that another class does, + plus some more properties.</p> + + <tp:rationale> + <p>For older clients to still be able to understand how to request + channels in the presence of a hypothetical "encryption" interface, + we'd need to represent it like this:</p> + + <ul> + <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li> + <li>class 2: Channel.ChannelType = Text, + Channel.TargetHandleType = CONTACT, + Encryption.Encrypted = TRUE</li> + </ul> + </tp:rationale> + </tp:docstring> + + <tp:member name="Fixed_Properties" type="a{sv}" + tp:type="Channel_Class"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The property values that identify this requestable channel class. + These properties MUST be included in requests for a channel of this + class, and MUST take these values.</p> + + <p>Clients that do not understand the semantics of all the + Fixed_Properties MUST NOT request channels of this class, since + they would be unable to avoid making an incorrect request.</p> + + <p>This implies that connection managers wishing to make channels + available to old or minimal clients SHOULD have a channel class + with the minimum number of Fixed_Properties, and MAY additionally + have channel classes with extra Fixed_Properties.</p> + + <p>Interface designers SHOULD avoid introducing fixed properties + whose types are not serializable in a <code>.manager</code> + file.</p> + + <tp:rationale> + <p>Connection managers with a fixed property that is not + serializable cannot have a complete <code>.manager</code> + file.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + + <tp:member name="Allowed_Properties" type="as" + tp:type="DBus_Qualified_Member[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties that MAY be set when requesting a channel of this + channel type and handle type.</p> + + <p>This array MUST NOT include properties that are in the + Fixed_Properties mapping.</p> + + <p>Properties in this array may either be required or optional, + according to their documented semantics.</p> + + <tp:rationale> + <p>For instance, if + TargetHandleType takes a value that is not Handle_Type_None, + one or the other of TargetHandle and TargetID is required. + Clients are expected to understand the documented relationship + between the properties, so we do not have separate arrays + of required and optional properties.</p> + </tp:rationale> + + <p>If this array contains the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> + property, then this class of channel can be combined with other + channels with that property in a request, or added to an existing + bundle. If not, this signifies that the connection manager is + unable to mark channels of this class as part of a bundle - this + means that to the remote contact they are likely to be + indistinguishable from channels requested separately.</p> + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="RequestableChannelClasses" access="read" + type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" + tp:name-for-bindings="Requestable_Channel_Classes"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The classes of channel that are expected to be available on this + connection, i.e. those for which + <tp:member-ref>CreateChannel</tp:member-ref> can reasonably + be expected to succeed. User interfaces can use this information + to show or hide UI components.</p> + + <p>This property cannot change after the connection has gone to + state Connection_Status_Connected, so there is no change + notification (if the connection has context-dependent capabilities, + it SHOULD advertise support for all classes of channel that it might + support during its lifetime). Before this state has been reached, + the value of this property is undefined.</p> + + <tp:rationale> + <p>This is not on an optional interface, because connection + managers can always offer some sort of clue about the channel + classes they expect to support (at worst, they can announce + support for everything for which they have code).</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Resources.xml b/spec/Connection_Interface_Resources.xml new file mode 100644 index 0000000..716089c --- /dev/null +++ b/spec/Connection_Interface_Resources.xml @@ -0,0 +1,212 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Resources" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Resources.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.21.1">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to show contact attributes for + specific resources of a contact, if the protocol supports + multiple resources. Resources are most common in XMPP, hence the + name of this interface, but they are also present in MSN, where + they are called points of presence.</p> + + <p>When a client requests some attribute of a contact using its + handle on the connection, the CM uses an algorithm to choose the + most appropriate resource for the job. If there is only one + resource, then the choice is obvious. If, however, there is more + than one resource connected at any one time, the CM either + aggregates all appropriate information to return (in the case of + capabilities), or chooses one specific resource (in the case of + presence).</p> + + <p>Resources in XMPP have names, and it can be extremely useful + for the user to be able to know which resources of a contact are + online, providing the names are human-readable. Before now, + resources have not been exposed in Telepathy, but this interface + attempts to change this.</p> + + <p>When using this interface, it is a little like using the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface" + >Contacts</tp:dbus-ref> interface, but only resource-specific + attributes are ever returned. The resource-specific contact + attributes are decided on by the CM, but XMPP's are listed + below:</p> + + <ul> + <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li> + <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li> + <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/client-types</tp:dbus-ref></li> + </ul> + + </tp:docstring> + + <method name="GetResources" tp:name-for-bindings="Get_Resources"> + <tp:docstring> + Return the resource information of the given contacts. If any + of the contact attributes for specific resources of the given + contacts' are not known return immediately without waiting for + a reply. + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose resource attributes should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Resources" type="a{ua{sa{sv}}}" + tp:type="Resources_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contacts' resources and the contact attributes specific + to each resource. If contact attributes are not immediately + known, the behaviour is defined by the interface; the + attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>For every contact handle passed into this method, it is + guaranteed that there will be a key in the returned map + that corresponds to said handle. If there is no information + regarding the contact the resource information map will be + empty.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <tp:enum name="Resources_Human_Readability" type="u"> + <tp:enumvalue suffix="Never" value="0"> + <tp:docstring> + The resource string is never human-readable. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Maybe" value="1"> + <tp:docstring> + The resource string might be human-readable. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="ResourcesHumanReadable" type="u" access="read" + tp:type="Resources_Human_Readability" + tp:name-for-bindings="Resources_Human_Readable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref> + are human readable or not.</p> + + <p>If the connection manager knows that all resource names are + automatically generated, then the resource strings mean + nothing to the user. Showing these strings in the UI would + be confusing, so by setting this to + Resources_Human_Readability_Never, the UI is advised not to + show resources.</p> + + <p>If on the other hand, all resources are set to nice names + (such as "office" or "home") then it might be wise to expose + these strings in the UI, so this property would be set to + Resources_Human_Readability_Maybe. This is the case in XMPP -- + most resources are set in a way that the user can deduce some + information from them. The absence of an Always enum value is + because in the case of XMPP, the resource string could be + partially human-readable (as on Google Talk, where a resource + of "home" is changed by the server to a unique string like + "home_1234fdec") or not at all human-readable.</p> + + </tp:docstring> + </property> + + <signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated"> + <tp:docstring> + Emitted when a contact has a resource added or removed, or any + contact attribute for any resource changes. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact. + </tp:docstring> + </arg> + <arg name="Resources" tp:type="Resource_Information_Map" + type="a{sa{sv}}"> + <tp:docstring> + The contact's resource information. All resource information + is given, not just the details which have changed. + </tp:docstring> + </arg> + </signal> + + <tp:mapping name="Resource_Information_Map"> + <tp:docstring> + A map of a contact's resources to their resource-specific + information. + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring> + <p>The name of the resource.</p> + </tp:docstring> + </tp:member> + + <tp:member name="Contact_Attributes" type="a{sv}" + tp:type="Single_Contact_Attributes_Map"> + <tp:docstring> + A map of contact attributes whose data is specific to this + resource. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Resources_Attributes_Map"> + <tp:docstring>Mapping returned by + <tp:member-ref>GetResources</tp:member-ref>, representing a + collection of Contacts, their resources, and their + resource-specific contact attributes.</tp:docstring> + + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact. + </tp:docstring> + </tp:member> + + <tp:member type="a{sa{sv}}" tp:type="Resource_Information_Map" + name="Resources"> + <tp:docstring> + A map of the contact's resources to their resource-specific + information. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:contact-attribute name="resources" type="a{sa{sv}}" + tp:type="Resource_Information_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetResources</tp:member-ref> for this contact.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml new file mode 100644 index 0000000..b135c04 --- /dev/null +++ b/spec/Connection_Interface_Service_Point.xml @@ -0,0 +1,136 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ServicePoint"> + <tp:added version="0.19.7">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections whose channels may be able to indicate + specific they are connected to some form + of service station. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.</p> + </tp:docstring> + + <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List"> + <tp:member type="(us)" tp:type="Service_Point" name="Service_Point"> + <tp:docstring> + The service point. + </tp:docstring> + </tp:member> + <tp:member type="as" name="Service_IDs"> + <tp:docstring> + A list of IDs that are mapped to this service. This is provided as + a convenience for the UIs, but the preferred method for + requesting channel to a service is by setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint">InitialServicePoint</tp:dbus-ref> + property in a channel request. + </tp:docstring> + </tp:member> + <tp:docstring> + <p>Description of a service point and IDs which are mapped to it.</p> + + <p>An example Service Point info for GSM emergency calls (callable + through "911" and "112") could look like:</p> + +<pre> + ServicePointInfo = ( + Service_Point: ( + Service_Point_Type: 1 (Emergency), + Service_Point: "urn:service:sos" + ), + Service_IDs: [ "911", "112" ] + ) +</pre> + </tp:docstring> + </tp:struct> + + <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points" + type="a((us)as)" tp:type="Service_Point_Info[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The list of all (known) service points. + </tp:docstring> + </property> + + <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed"> + <arg name="Service_Points" type="a((us)as)" tp:type="Service_Point_Info[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new value of + <tp:member-ref>KnownServicePoints</tp:member-ref>.</p> + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the list of known service points (or their IDs) has + changed. + </tp:docstring> + </signal> + + <tp:struct name="Service_Point"> + <tp:docstring>A service point.</tp:docstring> + <tp:member type="u" name="Service_Point_Type" + tp:type="Service_Point_Type"> + <tp:docstring> + The service type. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Service"> + <tp:docstring> + String representation of the service point. The representation is + service specific; it may be a 'service' Uniform Resource Name as + specified by <a + href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>, + or may be in some other form. Empty, unused or unknown value is + represented by "". + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum name="Service_Point_Type" type="u"> + <tp:docstring> + The various types of service points a channel might connect to. + </tp:docstring> + + <tp:enumvalue value="0" suffix="None"> + <tp:docstring> + The channel is not communicating with a service point, or it is not + known whether it is communicating with a service point (e.g. an + ordinary call). + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Emergency"> + <tp:docstring> + The service point is a generic emergency point. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Counseling"> + <tp:docstring> + The service point is some kind of counseling service (ie, mental health + or child-services counseling). + </tp:docstring> + </tp:enumvalue> + </tp:enum> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml new file mode 100644 index 0000000..7788161 --- /dev/null +++ b/spec/Connection_Interface_Simple_Presence.xml @@ -0,0 +1,634 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Simple_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser + General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public License + along with this library; if not, write to the Free Software Foundation, + Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:struct name="Simple_Presence"> + <tp:docstring> + A struct representing the presence of a contact. + </tp:docstring> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"> + <tp:docstring> + The presence type, e.g. Connection_Presence_Type_Away. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Status"> + <tp:docstring> + The string identifier of the status, e.g. "brb", as defined in the + <tp:member-ref>Statuses</tp:member-ref> property. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Status_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user-defined status message, e.g. "Back soon!".</p> + + <p>Clients SHOULD set the status message for the local + user to the empty string, unless the user has actually provided + a specific message (i.e. one that conveys more information than the + Status).</p> + + <p>User interfaces SHOULD regard an empty status message as unset, + and MAY replace it with a localized string corresponding to the + Status or Type.</p> + + <tp:rationale> + Use case: Daf sets his status in Empathy by choosing the Welsh + translation of "Available" from a menu. + It is more informative for his English-speaking colleagues + to see the English translation of "Available" (as localized + by their own clients) than to see "Ar Gael" (which they don't + understand anyway). + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Simple_Contact_Presences"> + <tp:docstring> + Mapping returned by <tp:member-ref>GetPresences</tp:member-ref> + and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>, + indicating the presence of a number of contacts. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact + </tp:docstring> + </tp:member> + <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence"> + <tp:docstring> + The contact's presence + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Simple_Status_Spec"> + <tp:docstring> + A struct containing information about a status. + </tp:docstring> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"> + <tp:docstring> + The type of a presence. This SHOULD NOT be used as a way to set + statuses that the client does not recognise (as explained in + <tp:member-ref>SetPresence</tp:member-ref>), but MAY be used to check + that the client's assumptions about a particular status name + match the connection manager's. + </tp:docstring> + </tp:member> + <tp:member type="b" name="May_Set_On_Self"> + <tp:docstring> + If true, the user can set this status on themselves using + <tp:member-ref>SetPresence</tp:member-ref>. + </tp:docstring> + </tp:member> + <tp:member type="b" name="Can_Have_Message"> + <tp:docstring> + If true, a non-empty message can be set for this status. Otherwise, + the empty string is the only acceptable message. + + <tp:rationale> + On IRC you can be Away with a status message, but if you are + available you cannot set a status message. + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Simple_Status_Spec_Map"> + <tp:docstring> + A mapping describing possible statuses. + </tp:docstring> + + <tp:member type="s" name="Identifier"> + <tp:docstring> + The string identifier of this status. + </tp:docstring> + </tp:member> + <tp:member type="(ubb)" tp:type="Simple_Status_Spec" name="Spec"> + <tp:docstring> + Details of this status. + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="SetPresence" tp:name-for-bindings="Set_Presence"> + <arg direction="in" name="Status" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string identifier of the desired status. Possible status + identifiers are defined in the + <tp:member-ref>Statuses</tp:member-ref> property.</p> + + <p>Clients MUST NOT set a status whose string value they do not + recognise, even if its presence type in Statuses + matches what the user requested.</p> + + <tp:rationale> + <p>Suppose a protocol has statuses that include 'phone' (of type + BUSY) and 'in-a-meeting' (of type BUSY), but there is no + generic 'busy' status.</p> + + <p>If the user requests "Busy" status from a menu, a + client author might be tempted to pick an arbitrary status + that has type BUSY. However, on this protocol, neither of + the choices would be appropriate, and incorrect information + about the user would be conveyed.</p> + </tp:rationale> + + <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.</p> + + <tp:rationale> + <p>To go offline, call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref> + instead. The "error" and "unknown" statuses make no sense.</p> + </tp:rationale> + </tp:docstring> + </arg> + <arg direction="in" name="Status_Message" type="s"> + <tp:docstring> + The status message associated with the current status. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the presence status and status message are published for + the connection. Changes will be indicated by + <tp:member-ref>PresencesChanged</tp:member-ref> + signals being emitted.</p> + + <p>This method may be called on a newly-created connection while it + is still in the DISCONNECTED state, to request that when the + connection connects, it will do so with the selected status.</p> + + <p>In DISCONNECTED state the + <tp:member-ref>Statuses</tp:member-ref> + property will indicate which statuses are allowed to be set + while DISCONNECTED (none, if the Connection Manager doesn't allow + this). This value MUST NOT be cached, as the set of allowed + presences might change upon connecting.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Either the specified status is not supported, the specified + status cannot be set on the user themselves, or a non-empty + message was supplied for a status that does not + accept a message. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="GetPresences" tp:name-for-bindings="Get_Presences"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of the contacts whose presence should be obtained. + </tp:docstring> + </arg> + <arg direction="out" name="Presence" type="a{u(uss)}" + tp:type="Simple_Contact_Presences"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Presence information in the same format as for the + <tp:member-ref>PresencesChanged</tp:member-ref> signal. + The returned mapping MUST include an entry for each contact + in the method's argument.</p> + + <p>The definition of the connection presence types Unknown + and Offline means that if a connection manager will return + Unknown for contacts not on the subscribe list, it MUST delay + the reply to this method call until it has found out which + contacts are, in fact, on the subscribe list.</p> + </tp:docstring> + </arg> + <tp:docstring> + Get presence previously emitted by + <tp:member-ref>PresencesChanged</tp:member-ref> for the given + contacts. Data is returned in the same structure as the + PresencesChanged signal; no additional network requests are made. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"> + <tp:docstring> + While discovering the subscribe list in order to distinguish + between Unknown and Offline statuses, a network error occurred. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <property name="Statuses" tp:name-for-bindings="Statuses" access="read" + type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary where the keys are the presence statuses that are + available on this connection, and the values are the corresponding + presence types.</p> + + <p>While the connection is in the DISCONNECTED state, it contains + the set of presence statuses allowed to be set before connecting. + The connection manager will attempt to set the appropriate status + when the connection becomes connected, but cannot necessarily + guarantee it. The available statuses cannot change until the + connection status changes, so there is no change notification.</p> + + <p>While the connection is in the CONNECTED state, this property + contains the set of presence statuses which are actually available + on this protocol. This set is constant for the remaining lifetime + of the connection, so again, there is no change notification.</p> + + <p>While the connection is in the CONNECTING state, the value of + this property is undefined and SHOULD NOT be used. It can change + at any time without notification (in particular, any cached values + from when the connection was in the DISCONNECTED or CONNECTING + state MUST NOT be assumed to still be correct when the state has + become CONNECTED).</p> + + <p>This property MUST include the special statuses "unknown" and + "error" if and only if the connection manager can emit them + as a contact's status.</p> + + <tp:rationale> + For instance, connection managers for local-xmpp (XEP-0174) would + omit "unknown" since there is no such concept. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="PresencesChanged" tp:name-for-bindings="Presences_Changed"> + <arg name="Presence" type="a{u(uss)}" tp:type="Simple_Contact_Presences"> + <tp:docstring> + A dictionary of contact handles mapped to the status, + presence type and status message. + </tp:docstring> + </arg> + <tp:docstring> + This signal should be emitted when your own presence has been changed, + or the presence of the member of any of the connection's channels has + been changed. + </tp:docstring> + </signal> + + <tp:enum name="Connection_Presence_Type" type="u"> + <tp:enumvalue suffix="Unset" value="0"> + <tp:docstring> + An invalid presence type used as a null value. This value MUST NOT + appear in the <tp:member-ref>Statuses</tp:member-ref> property, + or in the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Presence">GetStatuses</tp:dbus-ref> + on the deprecated <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref> + interface. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Offline" value="1"> + <tp:docstring> + Offline + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Available" value="2"> + <tp:docstring> + Available + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Away" value="3"> + <tp:docstring> + Away + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Extended_Away" value="4"> + <tp:docstring> + Away for an extended time + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Hidden" value="5"> + <tp:docstring> + Hidden (invisible) + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Busy" value="6"> + <tp:added version="0.17.0"/> + <tp:docstring> + Busy, Do Not Disturb. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Unknown" value="7"> + <tp:added version="0.17.8"/> + <tp:docstring> + Unknown, unable to determine presence for this contact, for example + if the protocol only allows presence of subscribed contacts. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Error" value="8"> + <tp:added version="0.17.8"/> + <tp:docstring> + Error, an error occurred while trying to determine presence. The + message, if set, is an error from the server. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Access_Control_Type" type="u" + array-name="Access_Control_Type_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A type for communication access control. These control + policies are used in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">CommunicationPolicy.DRAFT</tp:dbus-ref> + as well as most rich presence interfaces.</p> + + <p>New interfaces should use this type, and NOT + <tp:type>Rich_Presence_Access_Control_Type</tp:type>.</p> + </tp:docstring> + <tp:enumvalue suffix="Whitelist" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Only allow contacts that are in a certain whitelist.</p> + + <p>The associated variant + in <tp:type>Access_Control</tp:type> is a list of + <tp:type>Contact_Handle</tp:type> representing + the whitelist, with signature <code>au</code>.</p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Publish_List" value="1"> + <tp:docstring> + Allow contacts in the user's 'publish' list. The associated + variant in <tp:type>Access_Control</tp:type> is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Group" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Only allow contacts that are in a certain group.</p> + + <p>The associated variant in <tp:type>Access_Control</tp:type> is a + <tp:type>Group_Handle</tp:type> representing the permitted + group.</p> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="3"> + <tp:docstring> + Allow all contacts. The associated + variant in <tp:type>Access_Control</tp:type> is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Subscribe_Or_Publish_List" value="4"> + <tp:docstring> + Allow all contacts in the user's 'subscribe' or 'publish' + list. The associated variant in <tp:type>Access_Control</tp:type> is + ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Closed" value="5"> + <tp:docstring> + Forbid all contacts. The associated variant in + <tp:type>Access_Control</tp:type> is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Understood" value="6"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The access control rule is too complex to be represented + in the current Telepathy API. The associated variant is + meaningless. Setting this mode is never valid; the + connection manager MUST raise an error if this is attempted.</p> + + <tp:rationale> + XEP-0016 Privacy Lists can easily produce access control + mechanisms that can't be expressed in a simpler API. We + need to be able to at least indicate that fact. + </tp:rationale> + + <p>The associated variant in <tp:type>Access_Control</tp:type> is + ignored.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Rich_Presence_Access_Control_Type" type="u" + array-name="Rich_Presence_Access_Control_Type_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A type of access control for Rich_Presence_Access_Control. + For most types, the exact access control is given by an associated + variant.</p> + + <tp:rationale> + <p>These are the access control types from XMPP publish/subscribe + (XEP-0060).</p> + </tp:rationale> + + <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref> + uses this for historical reasons, new interfaces will use + <tp:type>Access_Control_Type</tp:type>.</p> + </tp:docstring> + + <tp:enumvalue suffix="Whitelist" value="0"> + <tp:docstring> + The associated variant is a list of contacts (signature 'au', + Contact_Handle[]) who can see the extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Publish_List" value="1"> + <tp:docstring> + All contacts in the user's 'publish' contact list can see the + extended presence information. The associated variant is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Group" value="2"> + <tp:docstring> + The associated variant is a handle of type Group (signature 'u', + Group_Handle) representing a group of contacts who can see the + extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="3"> + <tp:docstring> + Anyone with access to the service can see the extended presence + information. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Access_Control"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence + interfaces.</p> + + <p>New interfaces should use this type, and NOT + <tp:type>Rich_Presence_Access_Control</tp:type>.</p> + </tp:docstring> + + <tp:member name="Type" type="u" tp:type="Access_Control_Type"> + <tp:docstring> + The type of access control to apply. + </tp:docstring> + </tp:member> + <tp:member name="Detail" type="v"> + <tp:docstring> + Any additional information required by the Type. The required + type and semantics are defined for each + <tp:type>Access_Control_Type</tp:type>. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Rich_Presence_Access_Control"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence interfaces + such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>.</p> + + <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref> + uses this for historical reasons, new interfaces will use + <tp:type>Access_Control_Type</tp:type>.</p> + </tp:docstring> + + <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type"> + <tp:docstring> + The type of access control to apply. + </tp:docstring> + </tp:member> + <tp:member name="Detail" type="v"> + <tp:docstring> + Any additional information required by the Type. The required + type and semantics are defined for each + <tp:type>Rich_Presence_Access_Control_Type</tp:type>. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:contact-attribute name="presence" + type="(uss)" tp:type="Simple_Presence"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same struct that would be returned by + <tp:member-ref>GetPresences</tp:member-ref> + (always present with some value if information from the + SimplePresence interface was requested)</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface is for services which have a concept of presence which + can be published for yourself and monitored on your contacts.</p> + + <p>Presence on an individual (yourself or one of your contacts) is + modelled as a status and a status message. Valid statuses are defined + per connection, and a list of those that can be set on youself + can be obtained from the + <tp:member-ref>Statuses</tp:member-ref> + property.</p> + + <p>Each status has an arbitrary string identifier which should have an + agreed meaning between the connection manager and any client which is + expected to make use of it. The following well-known values should be + used where possible to allow clients to identify common choices:</p> + + <table> + <tr> + <th>status identifier</th> + <th>Connection_Presence_Type</th> + <th>comments</th> + </tr> + <tr> + <td>available</td> + <td>Connection_Presence_Type_Available</td> + <td></td> + </tr> + <tr> + <td>away</td> + <td>Connection_Presence_Type_Away</td> + <td></td> + </tr> + <tr> + <td>brb</td> + <td>Connection_Presence_Type_Away</td> + <td>Be Right Back (a more specific form of Away)</td> + </tr> + <tr> + <td>busy</td> + <td>Connection_Presence_Type_Busy</td> + <td></td> + </tr> + <tr><td>dnd</td> + <td>Connection_Presence_Type_Busy</td> + <td>Do Not Disturb (a more specific form of Busy)</td> + </tr> + <tr> + <td>xa</td> + <td>Connection_Presence_Type_Extended_Away</td> + <td>Extended Away</td> + </tr> + <tr> + <td>hidden</td> + <td>Connection_Presence_Type_Hidden</td> + <td>Also known as "Invisible" or "Appear Offline"</td> + </tr> + <tr> + <td>offline</td> + <td>Connection_Presence_Type_Offline</td> + <td></td> + </tr> + <tr> + <td>unknown</td> + <td>Connection_Presence_Type_Unknown</td> + <td>special, see below</td> + </tr> + <tr> + <td>error</td> + <td>Connection_Presence_Type_Error</td> + <td>special, see below</td> + </tr> + </table> + + <p>As well as these well-known status identifiers, every status also has + a numerical type value chosen from + <tp:type>Connection_Presence_Type</tp:type> which can be + used by the client to classify even unknown statuses into different + fundamental types.</p> + + <p>These numerical types exist so that even if a client does not + understand the string identifier being used, and hence cannot present + the presence to the user to set on themselves, it may display an + approximation of the presence if it is set on a contact.</p> + + <p>As well as the normal status identifiers, there are two special ones + that may be present: 'unknown' with type Unknown and 'error' with type + Error. 'unknown' indicates that it is impossible to determine the + presence of a contact at this time, for example because it's not on the + 'subscribe' list and the protocol only allows one to determine the + presence of contacts you're subscribed to. 'error' indicates that there + was a failure in determining the status of a contact.</p> + + <p>If the connection has a 'subscribe' contact list, + <tp:member-ref>PresencesChanged</tp:member-ref> + signals should be emitted to indicate changes of contacts on this list, + and should also be emitted for changes in your own presence. Depending + on the protocol, the signal may also be emitted for others such as + people with whom you are communicating, and any user interface should + be updated accordingly.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml new file mode 100644 index 0000000..d75d866 --- /dev/null +++ b/spec/Connection_Manager.xml @@ -0,0 +1,614 @@ +<?xml version="1.0" ?> +<node name="/Connection_Manager" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.ConnectionManager"> + + <tp:simple-type name="Connection_Manager_Name" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a connection manager, found in its well-known + bus name and object path. This must be a non-empty string of + ASCII letters, digits and underscores, starting with a letter. + This is typically the name of the executable with any "telepathy-" + prefix removed, and any hyphen/minus signs replaced by + underscores.</p> + + <p>Connection manager names SHOULD NOT be the same as the name of + the protocol they implement.</p> + + <tp:rationale> + <p>This is likely to lead to conflicts between different + implementations of the same protocol (or indeed inability + to distinguish between the different implementations!). The + Telepathy project traditionally uses some sort of pun (Haze is + based on libpurple, Salut implements a protocol often called + Bonjour, and Wilde implements the OSCAR protocol).</p> + </tp:rationale> + + <p>Connection manager names SHOULD NOT be the same as the name of + a library on which they are based.</p> + + <tp:rationale> + <p>We often abbreviate, for instance, telepathy-haze as "Haze", + but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause + confusion between the connection manager and the library it + uses. Please don't repeat that mistake.</p> + </tp:rationale> + </tp:docstring> + <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed + characters were not specified</tp:changed> + </tp:simple-type> + + <tp:simple-type name="Protocol" type="s" array-name="Protocol_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An instant messaging protocol. It must consist only of ASCII + letters, digits and hyphen/minus signs (U+002D "-"), and must start + with a letter. Where possible, this SHOULD be + chosen from the following well-known values:</p> + + <ul> + <li>aim - AOL Instant Messenger (OSCAR or TOC)</li> + <li>gadugadu - Gadu-Gadu</li> + <li>groupwise - Novell Groupwise</li> + <li>icq - ICQ (OSCAR)</li> + <li>irc - Internet Relay Chat (RFC 1459, 2810-2813)</li> + <li>jabber - XMPP (RFC 3920, 3921) or Jabber</li> + <li>local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)</li> + <li>msn - MSNP (Windows Live Messenger)</li> + <li>myspace - MySpaceIM</li> + <li>mxit - MXit</li> + <li>napster - Napster</li> + <li>qq - Tencent QQ</li> + <li>sametime - IBM Lotus Sametime</li> + <li>silc - SILC</li> + <li>sip - Session Initiation Protocol (SIP), with or without + SIMPLE support</li> + <li>skype - Skype</li> + <li>tel - telephony (the + <abbr title="Public Switched Telephone Network">PSTN</abbr>, + including GSM, CDMA and fixed-line telephony)</li> + <li>trepia - Trepia</li> + <li>yahoo - YMSG (Yahoo! Messenger)</li> + <li>yahoojp - Japanese version of YMSG</li> + <li>zephyr - Zephyr</li> + </ul> + </tp:docstring> + <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed + characters were not specified</tp:changed> + </tp:simple-type> + + <tp:struct name="Param_Spec" array-name="Param_Spec_List"> + <tp:docstring>A struct representing an allowed parameter, as returned + by GetParameters on the ConnectionManager interface.</tp:docstring> + <tp:member type="s" name="Name"> + <tp:docstring>A string parameter name</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Conn_Mgr_Param_Flags" name="Flags"> + <tp:docstring>A bitwise OR of the parameter flags</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Signature" name="Signature"> + <tp:docstring>A string containing the D-Bus type signature + for this parameter</tp:docstring> + </tp:member> + <tp:member type="v" name="Default_Value"> + <tp:docstring>The default value (if the Has_Default flag is not + present, there is no default and this takes some dummy value, + which SHOULD be of the appropriate D-Bus type)</tp:docstring> + </tp:member> + </tp:struct> + + <tp:flags name="Conn_Mgr_Param_Flags" value-prefix="Conn_Mgr_Param_Flag" type="u"> + <tp:flag suffix="Required" value="1"> + <tp:docstring> + This parameter is required for connecting to the server. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Register" value="2"> + <tp:docstring> + This parameter is required for registering an account on the + server. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Has_Default" value="4"> + <tp:docstring> + This parameter has a default value, which is returned in + GetParameters; not providing this parameter is equivalent to + providing the default. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Secret" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This parameter should be considered private or secret; for + instance, clients should store it in a "password safe" like + gnome-keyring or kwallet, omit it from debug logs, and use a + text input widget that hides the value of the parameter.</p> + + <p>(Clients that support older connection managers may also treat + any parameter whose name contains "password" as though it had this + flag.)</p> + </tp:docstring> + <tp:added version="0.17.2"/> + </tp:flag> + <tp:flag suffix="DBus_Property" value="16"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This parameter is also a D-Bus property on the resulting + <tp:dbus-ref + namespace="ofdT">Connection</tp:dbus-ref>; a + parameter named <code>com.example.Duck.Macaroni</code> with this + flag corresponds to the <code>Macaroni</code> property on the + <code>com.example.Duck</code> interface. Its value can be queried + and possibly changed on an existing Connection using methods on the + <code>org.freedesktop.DBus.Properties</code> interface.</p> + + <p>When a parameter with this flag is changed with <tp:dbus-ref + namespace="ofdT">Account.UpdateParameters</tp:dbus-ref>, the + account manager will attempt to update its value on any running + connections. Thus, clients generally do not need to directly access + or update the connection property; instead, they SHOULD manipulate + <tp:dbus-ref namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> + + <tp:rationale> + <p>This allows runtime-configurable options to be stored and + maintained by the <tp:dbus-ref + namespace='ofdT'>AccountManager</tp:dbus-ref>, without needing to + invent a separate account preference for “properties that should + be set on the connection as soon as it is created”. It was + originally invented to manage <tp:dbus-ref + namespace='ofdT.Connection.Interface'>Cellular</tp:dbus-ref> + preferences.</p> + </tp:rationale> + </tp:docstring> + <tp:added version="0.17.16"/> + </tp:flag> + </tp:flags> + + <method name="GetParameters" tp:name-for-bindings="Get_Parameters"> + <arg direction="in" name="Protocol" type="s" tp:type="Protocol"> + <tp:docstring> + The required protocol name + </tp:docstring> + </arg> + <arg direction="out" type="a(susv)" tp:type="Param_Spec[]" + name="Parameters"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs representing possible parameters. + </tp:docstring> + </arg> + <tp:docstring> + Get a list of the parameters which must or may be provided to the + <tp:member-ref>RequestConnection</tp:member-ref> method when connecting + to the given protocol, + or registering (the boolean "register" parameter is available, + and set to true). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested protocol is not supported by this manager + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:mapping name="Protocol_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from protocol identifiers supported by a connection + manager to the immutable properties of the corresponding + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Protocol</tp:dbus-ref> objects.</p> + </tp:docstring> + + <tp:member name="Protocol" type="s" tp:type="Protocol"> + <tp:docstring>A protocol name</tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring>The immutable properties of the corresponding + Protocol object</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="Protocols" tp:name-for-bindings="Protocols" + access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from protocol identifiers supported by this connection + manager to the immutable properties of the corresponding + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Protocol</tp:dbus-ref> objects.</p> + + <tp:rationale> + <p>Providing the immutable properties here means that + when the API of Protocol objects has been finalized, + most clients will only need one D-Bus round trip to interrogate + the ConnectionManager about all its protocols.</p> + </tp:rationale> + + <p>If this map is empty or missing, clients SHOULD fall back to + calling <tp:member-ref>ListProtocols</tp:member-ref> and + <tp:member-ref>GetParameters</tp:member-ref>.</p> + </tp:docstring> + </property> + + <method name="ListProtocols" tp:name-for-bindings="List_Protocols"> + <arg direction="out" type="as" tp:type="Protocol[]" name="Protocols"> + <tp:docstring> + The keys of the <tp:member-ref>Protocols</tp:member-ref> map. + </tp:docstring> + </arg> + <tp:docstring> + Get a list of protocol identifiers that are implemented by this + connection manager. + </tp:docstring> + </method> + + <signal name="NewConnection" tp:name-for-bindings="New_Connection"> + <arg name="Bus_Name" type="s" tp:type="DBus_Bus_Name"> + <tp:docstring> + The D-Bus service where the connection object can be found + </tp:docstring> + </arg> + <arg name="Object_Path" type="o"> + <tp:docstring> + The object path of the Connection object on this service + </tp:docstring> + </arg> + <arg name="Protocol" type="s" tp:type="Protocol"> + <tp:docstring> + The identifier for the protocol this connection uses + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object + is created. + </tp:docstring> + </signal> + + <method name="RequestConnection" tp:name-for-bindings="Request_Connection"> + <arg direction="in" name="Protocol" type="s" tp:type="Protocol"> + <tp:docstring> + The protocol identifier + </tp:docstring> + </arg> + <arg direction="in" name="Parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + A dictionary mapping parameter names to values of the appropriate + type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> + and the well-known list of names and value types documented on the + <tp:type>Connection_Parameter_Name</tp:type> type. + </tp:docstring> + </arg> + <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name"> + <tp:docstring> + A D-Bus service name where the new Connection object can be found + </tp:docstring> + </arg> + <arg direction="out" type="o" name="Object_Path"> + <tp:docstring> + The D-Bus object path to the Connection on this service + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + object representing a given account on a given + protocol with the given parameters. The method returns the bus name + and the object path where the new Connection object can be found, + which should have the status of Connection_Status_Disconnected, to + allow signal handlers to be attached before connecting is started + with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref> + method.</p> + + <p>The parameters which must and may be provided in the parameters + dictionary can be discovered with the + <tp:member-ref>GetParameters</tp:member-ref> method. These + parameters, their types, and their default values may be cached + in files so that all available connection managers do not need to be + started to discover which protocols are available.</p> + + <p>To request values for these parameters from the user, a client must + have prior knowledge of the meaning of the parameter names, so the + well-known names and types defined by the + <tp:type>Connection_Parameter_Name</tp:type> type should be used where + appropriate.</p> + + <p>Connection manager authors SHOULD avoid introducing parameters + whose default values would not be serializable in a + <code>.manager</code> file.</p> + + <tp:rationale> + <p>The same serialization format is used in Mission Control + to store accounts.</p> + </tp:rationale> + + <p>Every successful RequestConnection call will cause the emission of a + <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly + created connection. The + requester can use the returned object path and service name + independently of the emission of that signal. In that case this signal + emission is most useful for, e.g. other processes that are monitoring + the creation of new connections.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested protocol is not supported by this manager + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested connection already appears to exist + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Unrecognised connection parameters + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:simple-type name="Connection_Parameter_Name" type="s"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known connection parameter names, along with their expected + type. Where possible, connection managers should use names and types + from this list in the <tp:dbus-ref + namespace='ofdT.Protocol'>Parameters</tp:dbus-ref> that may be passed + to <tp:member-ref>RequestConnection</tp:member-ref>.</p> + + <dl> + <dt>account (s)</dt> + <dd>The identifier for the user's account on the server</dd> + + <dt>server (s)</dt> + <dd>A fully qualified domain name or numeric IPv4 or IPv6 address. + Using the fully-qualified domain name form is recommended whenever + possible. If this parameter is specified and the account for that + protocol also specifies a server, this parameter should override + that in the user id.</dd> + + <dt>port (q)</dt> + <dd>A TCP or UDP port number. If this parameter is specified and the + account for that protocol also specifies a port, this parameter + should override that in the account.</dd> + + <dt>password (s)</dt> + <dd>A password associated with the account.</dd> + + <dt>require-encryption (b)</dt> + <dd>Require encryption for this connection. A connection should fail + to connect if require-encryption is set and an encrypted connection + is not possible.</dd> + + <dt>register (b)</dt> + <dd>This account should be created on the server if it does not + already exist.</dd> + + <dt>ident (s)</dt> + <dd>The local username to report to the server if necessary, such as + in IRC.</dd> + + <dt>fullname (s)</dt> + <dd>The user's full name if the service requires this when + authenticating or registering.</dd> + + <dt>stun-server (s)</dt> + <dd>The IP address or FQDN of a STUN server to use for NAT traversal, + without any ":port" suffix.</dd> + + <dt>stun-port (q)</dt> + <dd>The UDP port number on the stun-server to use for STUN. Only + significant if the stun-server is also supplied.</dd> + + <dt>keepalive-interval (u)</dt> + <dd> + <p>The time in seconds between pings sent to the server to ensure + that the connection is still alive, or <tt>0</tt> to disable such + pings.</p> + + <p>This parameter is superseded by the <tp:dbus-ref + namespace='ofdT.Connection.Interface.Keepalive.DRAFT'>KeepaliveInterval</tp:dbus-ref> + property, which can be updated on an already-established + connection as well as being specified when requesting the + connection. Clients SHOULD provide that parameter instead, if + allowed; new connection managers SHOULD implement it in + preference to this one.</p> + </dd> + </dl> + + <p>The following well-known parameter names correspond to D-Bus + properties, and thus their <tp:type>Conn_Mgr_Param_Flags</tp:type> + should include DBus_Property. See that flag for more details on this + kind of parameter.</p> + + <tp:list-dbus-property-parameters/> + </tp:docstring> + </tp:simple-type> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the extra interfaces provided by this connection manager + (i.e. extra functionality that can be provided even before a + connection has been created).</p> + + <p>No interfaces suitable for listing in this property are currently + defined; it's provided as a hook for possible future + functionality.</p> + + <p>To be compatible with older connection managers, if retrieving + this property fails, clients SHOULD assume that its value is + an empty list.</p> + + <p>Connection managers with a non-empty list of Interfaces MUST + represent them in the <code>.manager</code> file, if they have one, + as an <code>Interfaces</code> key in the + group headed <code>[ConnectionManager]</code>, whose value is a list + of strings each followed by a semicolon.</p> + </tp:docstring> + <tp:added version="0.17.8"/> + </property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A D-Bus service which allows connections to be created. The manager + processes are intended to be started by D-Bus service activation.</p> + + <p>For service discovery, each Telepathy connection manager must have + a <em>connection manager name</em> (see + <tp:type>Connection_Manager_Name</tp:type> for syntax).</p> + + <p>The connection manager must then provide a well-known bus name of + <code>org.freedesktop.Telepathy.ConnectionManager.<em>cmname</em></code> + where <em>cmname</em> is its connection manager name. If it makes sense + to start the connection manager using D-Bus service activation, it + must register that well-known name for service activation by installing + a .service file.</p> + + <p>Clients can list the running connection managers by calling the + ListNames method on the D-Bus daemon's org.freedesktop.DBus interface + and looking for names matching the above pattern; they can list the + activatable connection managers by calling ListActivatableNames, and + they should usually combine the two lists to get a complete list of + running or activatable connection managers.</p> + + <p>When the connection manager is running, it must have an object + implementing the ConnectionManager interface at the object path + <code>/org/freedesktop/Telepathy/ConnectionManager/<em>cmname</em></code>. + </p> + + <p>Connection managers' capabilities can be determined dynamically by + calling their <tp:member-ref>ListProtocols</tp:member-ref> method, then + for each protocol of interest, calling + <tp:member-ref>GetParameters</tp:member-ref> to discover the required and + optional parameters. + However, since it is inefficient to activate all possible connection + managers on the system just to find out what they can do, there + is a standard mechanism to store static information about CMs in + ".manager files".</p> + + <p>To look up a connection manager's supported protocols, clients + should search the data directories specified by + <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">the + freedesktop.org XDG Base Directory Specification</a> ($XDG_DATA_HOME, + defaulting to $HOME/.local/share if unset, followed by + colon-separated paths from $XDG_DATA_DIRS, defaulting to + /usr/local/share:/usr/share if unset) for the first file named + <code>telepathy/managers/<em>cmname</em>.manager</code> that can be + read without error. This file has the same syntax as a + <a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p> + + <p>Clients must still support connection managers for which no + <code>.manager</code> file can be found, which they can do by activating + the connection manager and calling its methods; the + <code>.manager</code> file is merely an optimization. Connection managers + whose list of protocols can change at any time (for instance, via + a plugin architecture) should not install a <code>.manager</code> + file.</p> + + <p>The <code>.manager</code> file SHOULD have a group headed + <code>[ConnectionManager]</code>, containing a key + <code>Interfaces</code> representing + <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings + each followed by a semicolon (the "localestrings" type from the Desktop + Entry Specification).</p> + + <p>The <code>[ConnectionManager]</code> group SHOULD NOT contain keys + <code>ObjectPath</code> or <code>BusName</code>. If it does, they MUST + be ignored.</p> + + <tp:rationale> + <p>The object path and bus name are derivable from the connection + manager's name, which is part of the filename, so these keys are + redundant. They were required in very old versions of Telepathy.</p> + </tp:rationale> + + <p>For each protocol name <em>proto</em> that would be returned by + ListProtocols, the .manager file contains a group + headed <code>[Protocol <em>proto</em>]</code>. For each parameter + <em>p</em> that would be returned by GetParameters(<em>proto</em>), the + .manager file contains a key <code>param-<em>p</em></code> with a value + consisting of a D-Bus signature (a single complete type), optionally + followed by a space and a space-separated list of flags. The supported + flags are:</p> + + <ul> + <li><code>required</code>, corresponding to + Conn_Mgr_Param_Flag_Required</li> + <li><code>register</code>, corresponding + to Conn_Mgr_Param_Flag_Register</li> + <li><code>secret</code>, corresponding + to Conn_Mgr_Param_Flag_Secret</li> + <li><code>dbus-property</code>, corresponding + to Conn_Mgr_Param_Flag_DBus_Property</li> + </ul> + + <p>The group may also contain a key <code>default-<em>p</em></code> + whose value is a string form of the default value for the parameter. + If this key exists, it sets the default, and also sets the flag + Conn_Mgr_Param_Flag_Has_Default. The default value is formatted + according to the D-Bus signature as follows:</p> + + <dl> + <dt>s (string)</dt> + <dd>The UTF-8 string, with the standard backslash escape + sequences supported by the Desktop Entry Specification + (the "localestring" type from the Desktop Entry Specification)</dd> + <dt>o (object path)</dt> + <dd>The object path as an ASCII string</dd> + <dt>b (boolean)</dt> + <dd>"true" (case-insensitively) or "1" means True, "false" + (case-insensitively) or "0" means False; when writing a file, + "true" and "false" SHOULD be used</dd> + <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt> + <dd>ASCII decimal integer</dd> + <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt> + <dd>ASCII decimal integer, optionally prefixed with "-"</dd> + <dt>d (double-precision floating point)</dt> + <dd>ASCII decimal number</dd> + <dt>as (array of string)</dt> + <dd>A sequence of UTF-8 strings each followed by a semicolon, with + any semicolons they contain escaped with a backslash + (the "localestrings" type from the Desktop Entry Specification)</dd> + </dl> + + <p>Currently, no other D-Bus signatures are allowed to have default values, + but clients parsing the .manager file MUST ignore defaults + that they cannot parse, and treat them as if the + <code>default-<em>p</em></code> key was not present at all.</p> + + <p>It is not required that a connection manager be able to support multiple + protocols, or even multiple connections. When a connection is made, a + service name where the connection object can be found is returned. A + manager which can only make one connection may then remove itself from its + well-known bus name, causing a new connection manager to be activated when + somebody attempts to make a new connection.</p> + </tp:docstring> + + <tp:changed version="0.17.2">Prior to version 0.17.2, support for + CMs with no .manager file was not explicitly required.</tp:changed> + <tp:changed version="0.17.16">Prior to version 0.17.16 the serialization + of string arrays (signature 'as') was not defined</tp:changed> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Debug.xml b/spec/Debug.xml new file mode 100644 index 0000000..70a82e9 --- /dev/null +++ b/spec/Debug.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" ?> +<node name="/Debug" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2009 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Debug"> + <tp:added version="0.17.27">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for providing debug messages.</p> + + <p>This interface is primarily provided by one object per + service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.</p> + </tp:docstring> + + <property name="Enabled" type="b" access="readwrite" + tp:name-for-bindings="Enabled"> + <tp:docstring> + TRUE if the <tp:member-ref>NewDebugMessage</tp:member-ref> signal + should be emitted when a new debug message is generated. + </tp:docstring> + </property> + + <method name="GetMessages" tp:name-for-bindings="Get_Messages"> + <tp:docstring> + Retrieve buffered debug messages. An implementation could have a + limit on how many message it keeps and so the array returned from + this method should not be assumed to be all of the messages in + the lifetime of the service. + </tp:docstring> + + <arg direction="out" name="Messages" type="a(dsus)" + tp:type="Debug_Message[]"> + <tp:docstring> + A list of debug messages. + </tp:docstring> + </arg> + </method> + + <signal name="NewDebugMessage" tp:name-for-bindings="New_Debug_Message"> + <tp:docstring> + Emitted when a debug messages is generated if the + <tp:member-ref>Enabled</tp:member-ref> property is set to TRUE. + </tp:docstring> + + <arg name="time" type="d"> + <tp:docstring> + Timestamp of the debug message. + </tp:docstring> + </arg> + <arg name="domain" type="s"> + <tp:docstring> + Domain of the debug message, as described in the Debug_Message struct. + </tp:docstring> + </arg> + <arg name="level" type="u" tp:type="Debug_Level"> + <tp:docstring> + Level of the debug message. + </tp:docstring> + </arg> + <arg name="message" type="s"> + <tp:docstring> + The text of the debug message. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Debug_Level" type="u"> + <tp:enumvalue suffix="Error" value="0"> + <tp:docstring> + Log level for errors. Error messages are always fatal, resulting + in the service terminating after something completely + unexpected occurred. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Critical" value="1"> + <tp:docstring> + Log level for critical messages. Critical messages are messages + that the service might predict and it is up to the service itself + to decide whether to terminate following a critical message. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Warning" value="2"> + <tp:docstring> + Log level for warnings. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Message" value="3"> + <tp:docstring> + Log level for messages. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Info" value="4"> + <tp:docstring> + Log level for information messages. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Debug" value="5"> + <tp:docstring> + Log level for debug messages. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Debug_Message" array-name="Debug_Message_List"> + <tp:docstring> + A struct representing a debug message, as returned by + <tp:member-ref>GetMessages</tp:member-ref>. + </tp:docstring> + + <tp:member type="d" name="Timestamp"> + <tp:docstring> + Timestamp of the debug message. This is a double to allow + more accuracy in the time the message was logged. + </tp:docstring> + </tp:member> + + <tp:member type="s" name="Domain"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Domain of the debug message. This is used to identify + the source of debug messages. For example, debug messages + from a connection manager could have this Domain struct + member be the name of the connection manager, and logs + from any helper library could have the name of the helper + library.</p> + + <p>The domain could also contain a category as to where + the log message originated separated by a forward-slash. + For example, if a debug message was output in a connection + manager called "dummy", in the file-transfer code, this + Domain struct member might be <tt>dummy/file-transfer</tt>.</p> + </tp:docstring> + </tp:member> + + <tp:member type="u" tp:type="Debug_Level" name="Level"> + <tp:docstring> + Level of the debug message. This states the severity of the + debug message. + </tp:docstring> + </tp:member> + + <tp:member type="s" name="Message"> + <tp:docstring> + The text of the debug message. + </tp:docstring> + </tp:member> + </tp:struct> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Media_Session_Handler.xml b/spec/Media_Session_Handler.xml new file mode 100644 index 0000000..70aa750 --- /dev/null +++ b/spec/Media_Session_Handler.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" ?> +<node name="/Media_Session_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Media.SessionHandler"> + <method name="Error" tp:name-for-bindings="Error"> + <arg direction="in" name="Error_Code" type="u" + tp:type="Media_Stream_Error"/> + <arg direction="in" name="Message" type="s"/> + <tp:deprecated version="0.13.4"> + Use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media">StreamHandler.Error</tp:dbus-ref> + on each StreamHandler object instead. + </tp:deprecated> + <tp:docstring> + Informs the connection manager that an error occured in this session. + If used, the connection manager must terminate the session and all of + the streams within it, and may also emit a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">StreamError</tp:dbus-ref> + signal on the channel for each stream within the session. + </tp:docstring> + </method> + <signal name="NewStreamHandler" tp:name-for-bindings="New_Stream_Handler"> + <arg name="Stream_Handler" type="o"> + <tp:docstring> + The path of a new object implementing the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Media">StreamHandler</tp:dbus-ref> + interface. + </tp:docstring> + </arg> + <arg name="ID" type="u"> + <tp:docstring> + The unique ID of the new stream + </tp:docstring> + </arg> + <arg name="Media_Type" type="u" tp:type="Media_Stream_Type"> + <tp:docstring> + Type of media that this stream should handle + </tp:docstring> + </arg> + <arg name="Direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + Direction of this stream + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a new stream handler has been created for this + session. + </tp:docstring> + </signal> + <method name="Ready" tp:name-for-bindings="Ready"> + <tp:docstring> + Inform the connection manager that a client is ready to handle + this session handler (i.e. that it has connected to the + <tp:member-ref>NewStreamHandler</tp:member-ref> signal and done any + other necessary setup). + </tp:docstring> + </method> + <tp:docstring> + An media session handler is an object that handles a number of synchronised + media streams. + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml new file mode 100644 index 0000000..123ea8b --- /dev/null +++ b/spec/Media_Stream_Handler.xml @@ -0,0 +1,725 @@ +<?xml version="1.0" ?> +<node name="/Media_Stream_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Media.StreamHandler"> + + <tp:struct name="Media_Stream_Handler_Candidate" + array-name="Media_Stream_Handler_Candidate_List"> + <tp:member type="s" name="Name"/> + <tp:member type="a(usuussduss)" name="Transports" + tp:type="Media_Stream_Handler_Transport[]"/> + </tp:struct> + + <tp:struct name="Media_Stream_Handler_Transport" + array-name="Media_Stream_Handler_Transport_List"> + <tp:member type="u" name="Component_Number"/> + <tp:member type="s" name="IP_Address"/> + <tp:member type="u" name="Port"/> + <tp:member type="u" tp:type="Media_Stream_Base_Proto" name="Protocol"/> + <tp:member type="s" name="Subtype"/> + <tp:member type="s" name="Profile"/> + <tp:member type="d" name="Preference_Value"/> + <tp:member type="u" tp:type="Media_Stream_Transport_Type" + name="Transport_Type"/> + <tp:member type="s" name="Username"/> + <tp:member type="s" name="Password"/> + </tp:struct> + + <tp:struct name="Media_Stream_Handler_Codec" + array-name="Media_Stream_Handler_Codec_List"> + <tp:docstring> + Information about a codec supported by a client or a peer's client. + </tp:docstring> + + <tp:member type="u" name="Codec_ID"> + <tp:docstring> + The codec's payload identifier, as per RFC 3551 (static or dynamic) + </tp:docstring> + </tp:member> + <tp:member type="s" name="Name"> + <tp:docstring>The codec's name</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type"> + <tp:docstring>Type of stream this codec supports</tp:docstring> + </tp:member> + <tp:member type="u" name="Clock_Rate"> + <tp:docstring>Sampling frequency in Hertz</tp:docstring> + </tp:member> + <tp:member type="u" name="Number_Of_Channels"> + <tp:docstring>Number of supported channels</tp:docstring> + </tp:member> + <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map"> + <tp:docstring>Codec-specific optional parameters</tp:docstring> + </tp:member> + </tp:struct> + + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" + type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The IP addresses of possible STUN servers to use for NAT traversal, as + dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. + This property cannot change once the stream has been created, so there + is no change notification. The IP addresses MUST NOT be given as DNS + hostnames. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + </tp:rationale> + </tp:docstring> + </property> + + <property name="CreatedLocally" tp:name-for-bindings="Created_Locally" + type="b" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + True if we were the creator of this stream, false otherwise. + <tp:rationale> + This information is needed for some nat traversal mechanisms, such + as ICE-UDP, where the creator gets the role of the controlling agent. + </tp:rationale> + </tp:docstring> + </property> + + <property name="NATTraversal" tp:name-for-bindings="NAT_Traversal" + type="s" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The transport (NAT traversal technique) to be used for this + stream. Well-known values include:</p> + + <dl> + <dt>none</dt> + <dd>Raw UDP, with or without STUN, should be used. If the + <tp:member-ref>STUNServers</tp:member-ref> property is non-empty, + STUN SHOULD be used.</dd> + + <dt>stun</dt> + <dd>A deprecated synonym for 'none'.</dd> + + <dt>gtalk-p2p</dt> + <dd>Google Talk peer-to-peer connectivity establishment should be + used, as implemented in libjingle 0.3.</dd> + + <dt>ice-udp</dt> + <dd>Interactive Connectivity Establishment should be used, + as defined by the IETF MMUSIC working group.</dd> + + <dt>wlm-8.5</dt> + <dd>The transport used by Windows Live Messenger 8.5 or later, + which resembles ICE draft 6, should be used.</dd> + + <dt>wlm-2009</dt> + <dd>The transport used by Windows Live Messenger 2009 or later, + which resembles ICE draft 19, should be used.</dd> + </dl> + + <p>This property cannot change once the stream has been created, so + there is no change notification.</p> + </tp:docstring> + </property> + + <property name="RelayInfo" type="aa{sv}" access="read" + tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:</p> + + <dl> + <dt><code>ip</code> - s</dt> + <dd>The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + </tp:rationale> + </dd> + + <dt><code>type</code> - s</dt> + <dd> + <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this + key is omitted), <code>tcp</code> for TCP, or + <code>tls</code>.</p> + + <p>The precise meaning of this key depends on the + <tp:member-ref>NATTraversal</tp:member-ref> property: if + NATTraversal is <code>ice-udp</code>, <code>tls</code> means + TLS over TCP as referenced by ICE draft 19, and if + NATTraversal is <code>gtalk-p2p</code>, <code>tls</code> means + a fake SSL session over TCP as implemented by libjingle.</p> + </dd> + + <dt><code>port</code> - q</dt> + <dd>The UDP or TCP port of the relay server as an ASCII unsigned + integer</dd> + + <dt><code>username</code> - s</dt> + <dd>The username to use</dd> + + <dt><code>password</code> - s</dt> + <dd>The password to use</dd> + + <dt><code>component</code> - u</dt> + <dd>The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + <tp:rationale> + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + </tp:rationale> + </dd> + </dl> + + <tp:rationale> + <p>An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.</p> + </tp:rationale> + + <p>The type of relay server that this represents depends on + the value of the <tp:member-ref>NATTraversal</tp:member-ref> + property. If NATTraversal is ice-udp, this is a TURN server; + if NATTraversal is gtalk-p2p, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.</p> + + <p>If relaying is not possible for this stream, the list is empty.</p> + + <p>This property cannot change once the stream has been created, so + there is no change notification.</p> + </tp:docstring> + </property> + + <signal name="AddRemoteCandidate" + tp:name-for-bindings="Add_Remote_Candidate"> + <arg name="Candidate_ID" type="s"> + <tp:docstring> + String identifier for this candidate + </tp:docstring> + </arg> + <arg name="Transports" type="a(usuussduss)" + tp:type="Media_Stream_Handler_Transport[]"> + <tp:docstring> + Array of transports for this candidate with fields, + as defined in NewNativeCandidate + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client of a new remote candidate. + </tp:docstring> + </signal> + <signal name="Close" tp:name-for-bindings="Close"> + <tp:docstring> + Signal emitted when the connection manager wishes the stream to be + closed. + </tp:docstring> + </signal> + <method name="CodecChoice" tp:name-for-bindings="Codec_Choice"> + <arg direction="in" name="Codec_ID" type="u"/> + <tp:docstring> + Inform the connection manager of codec used to receive data. + </tp:docstring> + </method> + <method name="Error" tp:name-for-bindings="Error"> + <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error"> + <tp:docstring> + ID of error, from the MediaStreamError enumeration + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="s"> + <tp:docstring> + String describing the error + </tp:docstring> + </arg> + <tp:docstring> + Inform the connection manager that an error occured in this stream. The + connection manager should emit the StreamError signal for the stream on + the relevant channel, and remove the stream from the session. + </tp:docstring> + </method> + <tp:enum name="Media_Stream_Error" type="u"> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + An unknown error occured. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="EOS" value="1"> + <tp:docstring> + The end of the stream was reached. + </tp:docstring> + <tp:deprecated version="0.17.27"> + This error has no use anywhere. In Farsight 1 times, it was used to + indicate a GStreamer EOS (when the end of a file is reached). But + since this is for live calls, it makes no sense. + </tp:deprecated> + </tp:enumvalue> + <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2"> + <tp:added version="0.17.27"/> + <tp:docstring> + There are no common codecs between the local side + and the other particpants in the call. The possible codecs are not + signalled here: the streaming implementation is assumed to report + them in an implementation-dependent way, e.g. Farsight should use + GstMissingElement. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connection_Failed" value="3"> + <tp:added version="0.17.27"/> + <tp:docstring> + A network connection for the Media could not be established or was + lost. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Network_Error" value="4"> + <tp:added version="0.17.27"/> + <tp:docstring> + There was an error in the networking stack + (other than the connection failure). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="No_Codecs" value="5"> + <tp:added version="0.17.27"/> + <tp:docstring> + There are no installed codecs for this media type. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Invalid_CM_Behavior" value="6"> + <tp:added version="0.17.27"/> + <tp:docstring> + The CM is doing something wrong. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Media_Error" value="7"> + <tp:added version="0.17.27"/> + <tp:docstring> + There was an error in the media processing stack. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <method name="NativeCandidatesPrepared" + tp:name-for-bindings="Native_Candidates_Prepared"> + <tp:docstring> + Informs the connection manager that all possible native candisates + have been discovered for the moment. + </tp:docstring> + </method> + <method name="NewActiveCandidatePair" + tp:name-for-bindings="New_Active_Candidate_Pair"> + <arg direction="in" name="Native_Candidate_ID" type="s"/> + <arg direction="in" name="Remote_Candidate_ID" type="s"/> + <tp:docstring> + Informs the connection manager that a valid candidate pair + has been discovered and streaming is in progress. + </tp:docstring> + </method> + <method name="NewActiveTransportPair" + tp:name-for-bindings="New_Active_Transport_Pair"> + <arg direction="in" name="Native_Candidate_ID" type="s"/> + <arg direction="in" name="Native_Transport" type="(usuussduss)" + tp:type="Media_Stream_Handler_Transport"/> + <arg direction="in" name="Remote_Candidate_ID" type="s"/> + <arg direction="in" name="Remote_Transport" type="(usuussduss)" + tp:type="Media_Stream_Handler_Transport"/> + <tp:docstring> + <p>Informs the connection manager that a valid transport pair + has been discovered and streaming is in progress. Component + id MUST be the same for both transports and the pair is + only valid for that component.</p> + + <tp:rationale> + <p>The connection manager might need to send the details of + the active transport pair (e.g. c and o parameters of SDP + body need to contain address of selected native RTP transport + as stipulated by RFC 5245). However, the candidate ID might + not be enough to determine these info if the transport was + found after <tp:member-ref>NativeCandidatesPrepared</tp:member-ref> + has been called (e.g. peer reflexive ICE candidate). </p> + </tp:rationale> + + <p>This method must be called before + <tp:member-ref>NewActiveCandidatePair</tp:member-ref>.</p> + + <tp:rationale> + <p>This way, connection managers supporting this method can + safely ignore subsequent + <tp:member-ref>NewActiveCandidatePair</tp:member-ref> call.</p> + </tp:rationale> + + <p>Connection managers SHOULD NOT implement this method unless + they need to inform the peer about selected transports. As a + result, streaming implementations MUST NOT treat errors raised + by this method as fatal.</p> + + <tp:rationale> + <p>Usually, connection managers only need to do one answer/offer + round-trip. However, some protocols give the possibility to + to send an updated offer (e.g. ICE defines such mechanism to + avoid some race conditions and to properly set the state of + gateway devices).</p> + </tp:rationale> + </tp:docstring> + </method> + <tp:enum name="Media_Stream_Base_Proto" type="u"> + <tp:enumvalue suffix="UDP" value="0"> + <tp:docstring>UDP (User Datagram Protocol)</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="TCP" value="1"> + <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring> + </tp:enumvalue> + </tp:enum> + <method name="NewNativeCandidate" + tp:name-for-bindings="New_Native_Candidate"> + <arg direction="in" name="Candidate_ID" type="s"> + <tp:docstring> + String identifier for this candidate + </tp:docstring> + </arg> + <arg direction="in" name="Transports" type="a(usuussduss)" + tp:type="Media_Stream_Handler_Transport[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Array of transports for this candidate, with fields: + <ul> + <li>component number</li> + <li>IP address (as a string)</li> + <li>port</li> + <li>base network protocol (one of the values of MediaStreamBaseProto)</li> + <li>proto subtype (e.g. RTP)</li> + <li>proto profile (e.g. AVP)</li> + <li>our preference value of this transport (double in range 0.0-1.0 + inclusive); 1 signals the most preferred transport</li> + <li>transport type, one of the values of MediaStreamTransportType</li> + <li>username if authentication is required</li> + <li>password if authentication is required</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Inform this MediaStreamHandler that a new native transport candidate + has been ascertained. + </tp:docstring> + </method> + <tp:enum name="Media_Stream_Transport_Type" type="u"> + <tp:enumvalue suffix="Local" value="0"> + <tp:docstring> + A local address + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Derived" value="1"> + <tp:docstring> + An external address derived by a method such as STUN + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Relay" value="2"> + <tp:docstring> + An external stream relay + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <method name="Ready" tp:name-for-bindings="Ready"> + <arg direction="in" name="Codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Locally-supported codecs. + </tp:docstring> + </arg> + <tp:docstring> + Inform the connection manager that a client is ready to handle + this StreamHandler. Also provide it with info about all supported + codecs. + </tp:docstring> + </method> + <method name="SetLocalCodecs" tp:name-for-bindings="Set_Local_Codecs"> + <arg name="Codecs" type="a(usuuua{ss})" direction="in" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Locally-supported codecs + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used to provide codecs after Ready(), so the media client can go + ready for an incoming call and exchange candidates/codecs before + knowing what local codecs are available.</p> + + <p>This is useful for gatewaying calls between two connection managers. + Given an incoming call, you need to call + <tp:member-ref>Ready</tp:member-ref> to get the remote codecs before + you can use them as the "local" codecs to place the outgoing call, + and hence receive the outgoing call's remote codecs to use as the + incoming call's "local" codecs.</p> + + <p>In this situation, you would pass an empty list of codecs to the + incoming call's Ready method, then later call SetLocalCodecs on the + incoming call in order to respond to the offer.</p> + </tp:docstring> + </method> + <signal name="RemoveRemoteCandidate" + tp:name-for-bindings="Remove_Remote_Candidate"> + <arg name="Candidate_ID" type="s"> + <tp:docstring> + String identifier for remote candidate to drop + </tp:docstring> + </arg> + <tp:deprecated version="0.17.18"> + There is no case where you want to release candidates (except + for an ICE reset, and there you'd want to replace then all, + using <tp:member-ref>SetRemoteCandidateList</tp:member-ref>). + </tp:deprecated> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client that the remote end has removed a previously usable + candidate. + + <tp:rationale> + It seemed like a good idea at the time, but wasn't. + </tp:rationale> + </tp:docstring> + </signal> + <signal name="SetActiveCandidatePair" + tp:name-for-bindings="Set_Active_Candidate_Pair"> + <arg name="Native_Candidate_ID" type="s"/> + <arg name="Remote_Candidate_ID" type="s"/> + <tp:docstring> + Emitted by the connection manager to inform the client that a + valid candidate pair has been discovered by the remote end + and streaming is in progress. + </tp:docstring> + </signal> + <signal name="SetRemoteCandidateList" + tp:name-for-bindings="Set_Remote_Candidate_List"> + <arg name="Remote_Candidates" type="a(sa(usuussduss))" + tp:type="Media_Stream_Handler_Candidate[]"> + <tp:docstring> + A list of candidate id and a list of transports + as defined in NewNativeCandidate + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client of all the available remote candidates at once. + </tp:docstring> + </signal> + <signal name="SetRemoteCodecs" tp:name-for-bindings="Set_Remote_Codecs"> + <arg name="Codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Codecs supported by the remote peer. + </tp:docstring> + </arg> + <tp:docstring> + Signal emitted when the connection manager wishes to inform the + client of the codecs supported by the remote end. + If these codecs are compatible with the remote codecs, then the client + must call <tp:member-ref>SupportedCodecs</tp:member-ref>, + otherwise call <tp:member-ref>Error</tp:member-ref>. + </tp:docstring> + </signal> + <signal name="SetStreamPlaying" tp:name-for-bindings="Set_Stream_Playing"> + <arg name="Playing" type="b"/> + <tp:docstring> + If emitted with argument TRUE, this means that the connection manager + wishes to set the stream playing; this means that the streaming + implementation should expect to receive data. If emitted with argument + FALSE this signal is basically meaningless and should be ignored. + + <tp:rationale> + We're very sorry. + </tp:rationale> + </tp:docstring> + </signal> + <signal name="SetStreamSending" tp:name-for-bindings="Set_Stream_Sending"> + <arg name="Sending" type="b"/> + <tp:docstring> + Signal emitted when the connection manager wishes to set whether or not + the stream sends to the remote end. + </tp:docstring> + </signal> + <signal name="StartTelephonyEvent" + tp:name-for-bindings="Start_Telephony_Event"> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + A telephony event code. + </tp:docstring> + </arg> + <tp:docstring> + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. + </tp:docstring> + </signal> + <signal name="StartNamedTelephonyEvent" + tp:name-for-bindings="Start_Named_Telephony_Event"> + <tp:added version="0.21.2"/> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + A telephony event code as defined by RFC 4733. + </tp:docstring> + </arg> + <arg name="Codec_ID" type="u"> + <tp:docstring> + The payload type to use when sending events. The value 0xFFFFFFFF + means to send with the already configured event type instead of using + the specified one. + </tp:docstring> + </arg> + <tp:docstring> + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as a RFC 4733 named event, not as sound. You can also force a specific + Codec ID. + </tp:docstring> + </signal> + <signal name="StartSoundTelephonyEvent" + tp:name-for-bindings="Start_Sound_Telephony_Event"> + <tp:added version="0.21.2"/> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + A telephony event code as defined by RFC 4733. + </tp:docstring> + </arg> + <tp:docstring> + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as sound instead of as a named event. + </tp:docstring> + </signal> + <signal name="StopTelephonyEvent" + tp:name-for-bindings="Stop_Telephony_Event"> + <tp:docstring> + Request that any ongoing telephony events (as defined by RFC 4733) + being transmitted over this stream are stopped. + </tp:docstring> + </signal> + <method name="StreamState" tp:name-for-bindings="Stream_State"> + <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"/> + <tp:docstring> + Informs the connection manager of the stream's current state, as + as specified in Channel.Type.StreamedMedia::ListStreams. + </tp:docstring> + </method> + + <method name="SupportedCodecs" tp:name-for-bindings="Supported_Codecs"> + <arg direction="in" name="Codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Locally supported codecs. + </tp:docstring> + </arg> + <tp:docstring> + Inform the connection manager of the supported codecs for this session. + This is called after the connection manager has emitted SetRemoteCodecs + to notify what codecs are supported by the peer, and will thus be an + intersection of all locally supported codecs (passed to Ready) + and those supported by the peer. + </tp:docstring> + </method> + + <method name="CodecsUpdated" tp:name-for-bindings="Codecs_Updated"> + <arg direction="in" name="Codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Locally supported codecs, which SHOULD be the same as were previously + in effect, but possibly with different parameters. + </tp:docstring> + </arg> + <tp:docstring> + Inform the connection manager that the parameters of the supported + codecs for this session have changed. The connection manager should + send the new parameters to the remote contact. + + <tp:rationale> + This is required for H.264 and Theora, for example. + </tp:rationale> + </tp:docstring> + </method> + + <signal name="SetStreamHeld" tp:name-for-bindings="Set_Stream_Held"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the connection manager wishes to place the stream on + hold (so the streaming client should free hardware or software + resources) or take the stream off hold (so the streaming client + should reacquire the necessary resources).</p> + + <p>When placing a channel's streams on hold, the connection manager + SHOULD notify the remote contact that this will be done (if + appropriate in the protocol) before it emits this signal.</p> + + <tp:rationale> + <p>It is assumed that relinquishing a resource will not fail. + If it does, the call is probably doomed anyway.</p> + </tp:rationale> + + <p>When unholding a channel's streams, the connection manager + SHOULD emit this signal and wait for success to be indicated + via HoldState before it notifies the remote contact that the + channel has been taken off hold.</p> + + <tp:rationale> + <p>This means that if a resource is unavailable, the remote + contact will never even be told that we tried to acquire it.</p> + </tp:rationale> + </tp:docstring> + <tp:added version="0.17.3"/> + + <arg name="Held" type="b"> + <tp:docstring> + If true, the stream is to be placed on hold. + </tp:docstring> + </arg> + </signal> + + <method name="HoldState" tp:name-for-bindings="Hold_State"> + <tp:docstring> + Notify the connection manager that the stream's hold state has + been changed successfully in response to SetStreamHeld. + </tp:docstring> + <tp:added version="0.17.3"/> + <arg direction="in" name="Held" type="b"> + <tp:docstring> + If true, the stream is now on hold. + </tp:docstring> + </arg> + </method> + + <method name="UnholdFailure" tp:name-for-bindings="Unhold_Failure"> + <tp:docstring> + Notify the connection manager that an attempt to reacquire the + necessary hardware or software resources to unhold the stream, + in response to SetStreamHeld, has failed. + </tp:docstring> + <tp:added version="0.17.3"/> + </method> + + <tp:docstring> + Handles signalling the information pertaining to a specific media stream. + A client should provide information to this handler as and when it is + available. + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml new file mode 100644 index 0000000..bc9c8b2 --- /dev/null +++ b/spec/Properties_Interface.xml @@ -0,0 +1,194 @@ +<?xml version="1.0" ?> +<node name="/Properties_Interface" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2007 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Properties"> + + <tp:struct name="Property_Spec" array-name="Property_Spec_List"> + <tp:docstring>A struct (property ID, property name, D-Bus signature, + flags) representing a property, as returned by ListProperties on the + Properties interface.</tp:docstring> + <tp:member type="u" name="Property_ID"/> + <tp:member type="s" name="Name"/> + <tp:member type="s" tp:type="DBus_Signature" name="Signature"/> + <tp:member type="u" tp:type="Property_Flags" name="Flags"/> + </tp:struct> + + <tp:struct name="Property_Flags_Change" + array-name="Property_Flags_Change_List"> + <tp:docstring>A struct (property ID, flags) representing a change to + a property's flags, as seen in the PropertyFlagsChanged signal on + the Properties interface.</tp:docstring> + <tp:member type="u" name="Property_ID"/> + <tp:member type="u" name="New_Flags"/> + </tp:struct> + + <tp:simple-type name="Property_ID" type="u" array-name="Property_ID_List"> + <tp:docstring> + An unsigned integer used to represent a Telepathy property. + </tp:docstring> + </tp:simple-type> + + <tp:struct name="Property_Value" array-name="Property_Value_List"> + <tp:docstring>A struct (property ID, value) representing a + property's value, as seen in the PropertiesChanged signal on + the Properties interface, returned by the GetProperties method + and passed to the SetProperties method.</tp:docstring> + <tp:member type="u" tp:type="Property_ID" name="Identifier"/> + <tp:member type="v" name="Value"/> + </tp:struct> + + <method name="GetProperties" tp:name-for-bindings="Get_Properties"> + <tp:docstring> + Returns an array of (identifier, value) pairs containing the current + values of the given properties. + </tp:docstring> + <arg direction="in" name="Properties" type="au" tp:type="Property_ID[]"> + <tp:docstring>An array of property identifiers</tp:docstring> + </arg> + <arg direction="out" type="a(uv)" tp:type="Property_Value[]" + name="Values"> + <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of structs containing:</p> + <ul> + <li>integer identifiers</li> + <li>variant boxed values</li> + </ul> + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Some property identifier requested is invalid + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + Some property requested does not have the PROPERTY_FLAG_READ flag + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="ListProperties" tp:name-for-bindings="List_Properties"> + <tp:docstring> + Returns a dictionary of the properties available on this channel. + </tp:docstring> + <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]" + name="Available_Properties"> + <!-- XXX: if we're ever breaking API compatibility, make this + a{u(ssu)} ? --> + <tp:docstring> + An array of structs containing: + <ul> + <li>an integer identifier</li> + <li>a string property name</li> + <li>a string representing the D-Bus signature of this property</li> + <li>a bitwise OR of the flags applicable to this property</li> + </ul> + </tp:docstring> + </arg> + </method> + <signal name="PropertiesChanged" tp:name-for-bindings="Properties_Changed"> + <tp:docstring> + Emitted when the value of readable properties has changed. + </tp:docstring> + <arg name="Properties" type="a(uv)" tp:type="Property_Value[]"> + <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of structs containing:</p> + <ul> + <li>integer identifiers</li> + <li>variant boxed values</li> + </ul> + <p>The array should contain only properties whose values have + actually changed.</p> + </tp:docstring> + </arg> + </signal> + <signal name="PropertyFlagsChanged" + tp:name-for-bindings="Property_Flags_Changed"> + <tp:docstring> + Emitted when the flags of some room properties have changed. + </tp:docstring> + <arg name="Properties" type="a(uu)" tp:type="Property_Flags_Change[]"> + <!-- XXX: if we're ever breaking API compatibility, make this a{uu} --> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of structs containing:</p> + <ul> + <li>integer identifiers</li> + <li>a bitwise OR of the current flags</li> + </ul> + <p>The array should contain only properties whose flags have actually + changed.</p> + </tp:docstring> + </arg> + </signal> + <method name="SetProperties" tp:name-for-bindings="Set_Properties"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Takes an array of (identifier, value) pairs containing desired + values to set the given properties. In the case of any errors, no + properties will be changed. When the changes have been acknowledged + by the server, the PropertiesChanged signal will be emitted.</p> + + <p>All properties given must have the PROPERTY_FLAG_WRITE flag, or + PermissionDenied will be returned. If any variants are of the wrong + type, NotAvailable will be returned. If any given property identifiers + are invalid, InvalidArgument will be returned.</p> + </tp:docstring> + + <arg direction="in" name="Properties" type="a(uv)" + tp:type="Property_Value[]"> + <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> + <tp:docstring> + An array mapping integer property identifiers to boxed values + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels and other objects, to allow querying and setting + properties. ListProperties returns which properties are valid for + the given channel, including their type, and an integer handle used to + refer to them in GetProperties, SetProperties, and the PropertiesChanged + signal. The values are represented by D-Bus variant types, and are + accompanied by flags indicating whether or not the property is readable or + writable.</p> + + <p>Each property also has a flags value to indicate what methods are + available. This is a bitwise OR of PropertyFlags values.</p> + </tp:docstring> + <tp:flags name="Property_Flags" value-prefix="Property_Flag" type="u"> + <tp:flag suffix="Read" value="1"> + <tp:docstring>The property can be read</tp:docstring> + </tp:flag> + <tp:flag suffix="Write" value="2"> + <tp:docstring>The property can be written</tp:docstring> + </tp:flag> + </tp:flags> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol.xml b/spec/Protocol.xml new file mode 100644 index 0000000..5e2c9b1 --- /dev/null +++ b/spec/Protocol.xml @@ -0,0 +1,485 @@ +<?xml version="1.0" ?> +<node name="/Protocol" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Protocol"> + <tp:added version="0.19.10">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An object representing a protocol for which this <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref> + can create <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s.</p> + + <p>Each Protocol object has the same well-known bus name as its parent + ConnectionManager. Its object path is formed by taking the + ConnectionManager's object path and appending '/', followed by the + <tp:type>Protocol</tp:type> name with any hyphen/minus '-' converted + to underscores '_'.</p> + + <tp:rationale> + <p>This is the same as the representation of protocol names + in Account object paths, and in Connection object paths and bus + names. For instance, telepathy-gabble and telepathy-salut would + implement objects at + <code>/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber</code> + and + <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>, + respectively.</p> + </tp:rationale> + + <p>If the ConnectionManager has a <tt>.manager</tt> file, each + Protocol's immutable properties must be represented in that file; + the representation is described as part of the documentation for + each property. For instance, a very simple ConnectionManager with one + Protocol might be represented like this:</p> + +<pre> +[ConnectionManager] +Interfaces= + +[Protocol example] +Interfaces= +ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests; +param-account=s required +param-password=s required secret +RequestableChannelClasses=text; +VCardField=x-example +EnglishName=Example +Icon=im-example +AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication; + +[text] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; +</pre> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + access="read" type="as" tp:type="DBus_Interface[]" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of interfaces supported by this Protocol object.</p> + + <p>This property should not be confused with + <tp:member-ref>ConnectionInterfaces</tp:member-ref>, + which refers to the interfaces of <em>connections</em> to this + protocol.</p> + + <p>Connection managers with a <code>.manager</code> file + (as described as part of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface) MUST cache this + property in the protocol's section of the <code>.manager</code> + file, using the key <code>Interfaces</code>. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.</p> + </tp:docstring> + </property> + + <property name="Parameters" tp:name-for-bindings="Parameters" + access="read" type="a(susv)" tp:type="Param_Spec[]" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The parameters which must or may be provided to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> method when connecting to the + given protocol.</p> + + <p>Connection managers with a <code>.manager</code> file + (as described as part of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface) MUST cache this + property in the protocol's section of the <code>.manager</code> + file via keys of the form <code>param-<em>p</em></code> and + <code>default-<em>p</em></code>, as documented in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface.</p> + </tp:docstring> + </property> + + <property name="ConnectionInterfaces" + tp:name-for-bindings="Connection_Interfaces" + access="read" type="as" tp:type="DBus_Interface[]" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of interface names which might be in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection" + >Interfaces</tp:dbus-ref> property of a + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref> to this protocol. Whether a Connection + will have all, some or none of these interfaces depends on server + capabilities.</p> + + <p>This property should not be confused with + <tp:member-ref>Interfaces</tp:member-ref>.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file, using the key + <code>ConnectionInterfaces</code>. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.</p> + </tp:docstring> + </property> + + <property name="RequestableChannelClasses" + tp:name-for-bindings="Requestable_Channel_Classes" + access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of channel classes which might be requestable from a + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref> to this protocol (i.e. they will, + or might, appear in the Connection's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref> property).</p> + + <p>Whether a Connection will have all, some or none of these + requestable channel classes depends on server capabilities; + similarly, individual contacts are not guaranteed to support + all of these channel classes.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file, using the key + <code>RequestableChannelClasses</code>. The corresponding value + is a list of opaque strings, each followed by a semicolon; each + of those strings is the name of a group in the <code>.manager</code> + file which represents a channel class.</p> + + <p>The names of the groups representing channel classes are not + significant, and MUST NOT be interpreted. When writing + <tt>.manager</tt> files, authors MAY choose mnemonic group names, + generate group names mechanically (e.g. with an incrementing + integer), or use some combination of these.</p> + + <p>Each group representing a channel class has a key + <code>allowed</code> which is a list of D-Bus property names + representing allowed parameters. Any other keys that do not contain + a space MUST be ignored. Any key containing a space represents + a fixed property; the key has the form + "<code><em>propertyname</em> <em>type</em></code>", and the value + is encoded in the same way as for the <code>default-<em>p</em></code> + keys described in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> documentation.</p> + + <p>Connection managers that have channel classes whose fixed + properties are not representable in this form SHOULD NOT have + <code>.manager</code> files.</p> + + <p>For instance, this <code>.manager</code> file could represent + a connection manager that supports 1-1 Text messages and + StreamedMedia audio calls:</p> + +<pre>[Protocol jabber] +param-account=s required +param-password=s required +RequestableChannelClasses=rcc0;rcc1; + +[rcc0] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; + +[rcc1] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio; +</pre> + </tp:docstring> + </property> + + <property name="VCardField" tp:name-for-bindings="VCard_Field" + access="read" type="s" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the most common vCard field used for this protocol's + contact identifiers, normalized to lower case, or the empty string + if there is no such field.</p> + + <p>For example, this would be <code>x-jabber</code> for + Jabber/XMPP (including Google Talk), or <code>tel</code> for + the <abbr title="Public Switched Telephone Network">PSTN</abbr>.</p> + + <p>A more exhaustive list of addressable vCard fields can be found in + the Protocol's Addressing interface's + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p> + + <p>It is not necessarily valid to interpret contacts' identifiers + as values of this vCard field. For instance, telepathy-sofiasip + supports contacts whose identifiers are of the form + sip:jenny@example.com or tel:8675309, which would not normally + both be represented by any single vCard field. Arbitrary + handles/identifiers as vCard fields are represented + through the Connection's + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Addressing.DRAFT</tp:dbus-ref> + contact attributes.</p> + + <tp:rationale> + <p>This is taken from Mission Control profiles as used on Maemo 5. + One valid use of this field is to answer the question: given a + contact's vCard containing an X-JABBER field, how can you + communicate with the contact? By iterating through protocols + looking for an x-jabber VCardField, one can build up a list of + protocols that handle x-jabber, then offer the user a list of + accounts for those protocols and/or the option to create a new + account for one of those protocols.</p> + </tp:rationale> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>VCardField</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> + </tp:docstring> + </property> + + <property name="EnglishName" tp:name-for-bindings="English_Name" + access="read" type="s" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the protocol in a form suitable for display to users, + such as "AIM" or "Yahoo!", or the empty string if none is + available.</p> + + <p>This is effectively in the C locale (international English); + user interfaces requiring a localized protocol name SHOULD look + one up in their own message catalog based on either the Telepathy + <tp:type>Protocol</tp:type> name or this property, but SHOULD use + this English version as a fallback if no translated version can be + found.</p> + + <tp:rationale> + <p>Many protocols are named after a company or product which isn't + translated in non-English locales. This also provides a fallback + display name, for UIs with no prior knowledge of a particular + protocol.</p> + </tp:rationale> + + <p>If this property's value is empty, clients MAY fall back to using + the Telepathy <tp:type>Protocol</tp:type> name, possibly with its + capitalization adjusted.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>EnglishName</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> + </tp:docstring> + </property> + + <property name="Icon" tp:name-for-bindings="Icon" + access="read" type="s" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of an icon in the system's icon theme, such as "im-msn", or + the empty string.</p> + + <tp:rationale> + <p>This can be used as a default if the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref> + property is not set on an Account, or used by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref> + to choose a default icon if none is set during account + creation.</p> + </tp:rationale> + + <p>If this property's value is empty, clients MAY fall back to + generating a name based on the <tp:type>Protocol</tp:type> name.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>Icon</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> + </tp:docstring> + </property> + + <method name="IdentifyAccount" + tp:name-for-bindings="Identify_Account"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return a string which uniquely identifies the account to which the + given parameters would connect.</p> + + <tp:rationale> + <p>For many protocols, this would return the well-known 'account' + parameter. However, for IRC the returned string would be composed + from the 'account' (i.e. nickname) and 'server' parameters. + AccountManager implementations can use this to form the + account-specific part of an Account's object path.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Parameters" + type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + A set of parameters as would be provided to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> + </tp:docstring> + </arg> + + <arg direction="out" name="Account_ID" type="s"> + <tp:docstring> + <p>An opaque string suitable for use as the account-specific part of + an <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Account</tp:dbus-ref>'s object path. This is not necessarily + globally unique, but should represent a "best-effort" + identification of the account.</p> + + <tp:rationale> + <p>For a pathological case, consider a user signing in as + 'me@example.com' with 'server' set to either jabber1.example.com + or jabber2.example.com. Both of these should result in + me@example.com being returned from this method, even if the user + can actually be signed in to those two servers + simultaneously.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The IdentifyAccount method is not supported by this connection + manager. The caller SHOULD fall back to deriving identification + from the parameters. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="NormalizeContact" + tp:name-for-bindings="Normalize_Contact"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given contact ID. Where possible, this + SHOULD return the same thing that would be returned by + InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref>.</p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <tp:rationale> + <p>One common example of a best-effort offline normalization + differing from the ideal normalization is XMPP.</p> + + <p>On XMPP, contacts' JIDs should normally have the resource removed + during normalization, but for contacts in a MUC (chatroom), the + resource is an integral part of the JID - so the contact JID + alice@example.com/Empathy should normalize to alice@example.com, + but the in-MUC JID wonderland@conference.example.com/Alice should + normalize to itself.</p> + + <p>While online, the connection manager has enough context to know + which chatrooms the user is in, and can infer from that whether + to remove resources, but the best-effort normalization performed + while offline does not have this context, so the best that can be + done is to remove the resource from all JIDs.</p> + </tp:rationale> + + <p>This method MAY simply raise NotImplemented on some protocols.</p> + + <tp:rationale> + <p>In link-local XMPP, you can't talk to someone who isn't present + on your local network, so normalizing identifiers in advance is + meaningless.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact_ID" type="s"> + <tp:docstring> + The identifier of a contact in this protocol + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_Contact_ID" type="s"> + <tp:docstring> + The identifier of a contact in this protocol, normalized as much + as possible + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The NormalizeContact method is not supported by this connection + manager. The caller MAY recover by using the contact ID as-is. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="AuthenticationTypes" + tp:name-for-bindings="Authentication_Types" access="read" type="as" + tp:type="DBus_Interface[]" tp:immutable="yes"> + <tp:added version="0.21.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of D-Bus interfaces which provide information as to + what kind of authentication channels can possibly appear + before the connection reaches the CONNECTED state.</p> + + <p>These can either be channel types, or where the channel + type isn't enough information to be useful, interfaces + indicating a specific use of a channel type. For example, + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> + channels are obviously about TLS certificates so the channel + type would appear in this list. However, a + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel type alone does not explain enough about the authentication type + in use as it is merely a base for the channel interfaces that appear in + said channels. In this case, CMs should use the value of the + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref> + property in this list.</p> + + <p>For example, if a protocol's + <tp:member-ref>AuthenticationTypes</tp:member-ref> contains + two values:</p> + + <blockquote> + <pre> +[ ...<tp:dbus-ref namespace="ofdT">Channel.Type.ServerTLSConnection</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT">Channel.Interface.SASLAuthentication</tp:dbus-ref> ]</pre></blockquote> + + <p>This tells a client that before the connection status + reached CONNECTED, a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> + could appear carrying a TLS certificate. It also tells the + client that before the connection status reaches CONNECTED, a + <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel could also appear, where <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>=<tp:dbus-ref + namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>. A + hypothetical future Channel.Interface.Captcha interface would + also appear in this list if the CM might require the user + solve a captcha before connecting.</p> + + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml new file mode 100644 index 0000000..3722c3b --- /dev/null +++ b/spec/Protocol_Interface_Addressing.xml @@ -0,0 +1,300 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Addressing" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.12">(as draft)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols that support multiple forms of + addressing contacts, for example through vCard addresses and URIs.</p> + + <p>If the ConnectionManager has a <tt>.manager</tt> file, and it + supports this interface, the interface's immutable properties + must be represented in the file; the representation is described as + part of the documentation for each property.</p> + + <p>For instance, a SIP connection manager might have the + following lines in the <tt>.manager</tt> file.</p> + +<pre> +[Protocol sip] +AddressableVCardFields=tel;x-sip; +AddressableURISchemes=tel;sip; +</pre> + </tp:docstring> + + <property name="AddressableVCardFields" + tp:name-for-bindings="Addressable_VCard_Fields" + access="read" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard fields that can be used to request a contact with + normalized to lower case. If the <code>URL</code> vCard + field is addressable, a colon, followed by the supported URI + schemes will be concatenated.</p> + + <p>For example: <code>["tel", "x-sip"]</code>.</p> + + <p>The <code>url</code> vCard field MUST NOT appear here; see + <tp:member-ref>AddressableURISchemes</tp:member-ref> instead.</p> + + <tp:rationale> + <p>In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.</p> + </tp:rationale> + + <p>This property should only be used when the connection is + offline. When it is connected the addressable fields should be + retrieved from the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s + TargetVCardField fixed-property instead.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>AddressableVCardFields</code>. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.</p> + + <p>Well-known vCard fields:</p> + + <dl> + <dt><code>tel</code></dt> + <dd>The TEL vCard field. Used for phone numbers.</dd> + <dt><code>x-sip</code></dt> + <dd>The X-SIP vCard field. Used for SIP addresses.</dd> + <dt><code>x-aim</code></dt> + <dd>The X-AIM vCard field. Used for AIM user IDs.</dd> + <dt><code>x-icq</code></dt> + <dd>The X-ICQ vCard field. Used for ICQ UINs.</dd> + <dt><code>x-skype</code></dt> + <dd>The X-SKYPE vCard field. Used for Skype user names or + telephone numbers. There is also a X-SKYPE-USERNAME field, + but for Telepathy purposes, <code>x-skype</code> is preferred</dd> + <dt><code>x-groupwise</code></dt> + <dd>The X-GROUPWISE vCard field. Used for Groupwise contacts.</dd> + <dt><code>x-gadugadu</code></dt> + <dd>The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.</dd> + <dt><code>x-jabber</code></dt> + <dd>The X-JABBER vCard field. Used for XMPP JIDs.</dd> + <dt><code>x-msn</code></dt> + <dd>The X-MSN vCard field. Used for MSN contacts.</dd> + <dt><code>x-yahoo</code></dt> + <dd>The X-YAHOO vCard field. Used for Yahoo! IDs.</dd> + </dl> + + </tp:docstring> + </property> + + <property name="AddressableURISchemes" + tp:name-for-bindings="Addressable_URI_Schemes" + access="read" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The URI schemes that are supported by this protocol.</p> + + <p>For example: <code>["tel", "sip"]</code>.</p> + + <p>This property should only be used when the connection is + offline. When it is connected the addressable URI schemes should be + retrieved from the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s + TargetURIScheme fixed-property instead.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>AddressableURISchemes</code>. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.</p> + + <p>Well-known URI schemes:</p> + + <dl> + <dt><code>sip</code></dt> + <dd>SIP protocol. + For example: <code>sip:julien@example.com</code>.</dd> + <dt><code>sips</code></dt> + <dd>Secure (encrypted) SIP protocol. + For example: <code>sips:julien@example.com</code>.</dd> + <dt><code>tel</code></dt> + <dd>Used for telephone numbers. + For example: <code>tel:+12065551234</code>.</dd> + <dt><code>xmpp</code></dt> + <dd>XMPP protocol. + For example: <code>xmpp:julien@example.com</code>.</dd> + <dt><code>msnim</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>add</code>; the + <code>contact</code> field in the query string is used to + identify the contact. + For example: <code>msnim:add?contact=julien</code>.</dd> + <dt><code>aim</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>addbuddy</code>; the + <code>screenname</code> field in the query string is used to + identify the contact. + For example: <code>aim:addbuddy?screenname=julien</code>.</dd> + <dt><code>skype</code></dt> + <dd>Skype protocol. + For example: <code>skype:julien</code>.</dd> + <dt><code>ymsgr</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>addfriend</code>; the + query string is used to identify the contact. + For example: <code>ymsgr:addfriend?julien</code>.</dd> + <dt><code>gg</code></dt> + <dd>Gadu-Gadu protocol. + For example: <code>gg:julien</code>.</dd> + </dl> + </tp:docstring> + </property> + + <method name="NormalizeVCardAddress" + tp:name-for-bindings="Normalize_VCard_Address"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given vCard address. Where possible, this + SHOULD return an address that would appear in the + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses</code> + attribute for a contact on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. + </p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <p>An example would be a vCard TEL field with a formatted + number in the form of <code>+1 (206) 555 1234</code>, this would be + normalized to <code>+12065551234</code>.</p> + + <p>This method MAY simply raise NotImplemented on some + protocols, if it has no use.</p> + </tp:docstring> + + <arg direction="in" name="VCard_Field" type="s"> + <tp:docstring> + The vCard field of the address we are normalizing. The + field name SHOULD be in lower case, and MUST appear in + <tp:member-ref>AddressableVCardFields</tp:member-ref>. + </tp:docstring> + </arg> + + <arg direction="in" name="VCard_Address" type="s"> + <tp:docstring> + The address to normalize. + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_VCard_Address" type="s"> + <tp:docstring> + The vCard address, normalized as much as possible. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The vCard field is not supported (it is not in + <tp:member-ref>AddressableVCardFields</tp:member-ref>). + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The address is syntactically incorrect. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="NormalizeURI" + tp:name-for-bindings="Normalize_URI"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given contact URI. Where possible, this + SHOULD return an address that would appear in the + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris</code> + attribute for a contact on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. + </p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to + <code>xmpp:eitan@example.com</code>.</p> + + <p>This method MAY simply raise NotImplemented on some + protocols, if it has no use.</p> + </tp:docstring> + + <arg direction="in" name="URI" type="s"> + <tp:docstring> + The URI to normalize. The URI's scheme (i.e. the part before + the first colon) MUST appear in + <tp:member-ref>AddressableURISchemes</tp:member-ref>. + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_URI" type="s"> + <tp:docstring> + A URI, normalized as much as possible. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The URI scheme is not supported (it is not in + <tp:member-ref>AddressableURISchemes</tp:member-ref>). + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The URI is syntactically incorrect. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml new file mode 100644 index 0000000..cd91351 --- /dev/null +++ b/spec/Protocol_Interface_Avatars.xml @@ -0,0 +1,157 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Avatars" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Protocol.Interface.Avatars"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols where it might be possible to set the + user's avatar, and the expected size limits and supported MIME types + are known before connecting.</p> + + <tp:rationale> + <p>If the avatar requirements cannot be discovered while offline, + it's impossible to avoid setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Account</tp:dbus-ref>'s <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Avatar" + >Avatar</tp:dbus-ref> property to an unsupported avatar.</p> + </tp:rationale> + + <p>Each property on this interface SHOULD be cached in the + <code>.manager</code> file, using a key of the same name as the + property in the <code>[Protocol <em>proto</em>]</code> + group. All properties are encoded in ASCII decimal in the obvious + way, except for + <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is + encoded as a sequence of strings each followed by a semicolon + (as for the "localestrings" type in the Desktop Entry + Specification).</p> + + <p>For instance, an XMPP connection manager might have this + <code>.manager</code> file:</p> + +<pre>[Protocol jabber] +Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars; +param-account=s required +param-password=s required +SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif; +MinimumAvatarHeight=32 +RecommendedAvatarHeight=64 +MaximumAvatarHeight=96 +MinimumAvatarWidth=32 +RecommendedAvatarWidth=64 +MaximumAvatarWidth=96 +MaximumAvatarBytes=8192 +</pre> + </tp:docstring> + + <property name="SupportedAvatarMIMETypes" + tp:name-for-bindings="Supported_Avatar_MIME_Types" + type="as" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MinimumAvatarHeight" + tp:name-for-bindings="Minimum_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref> + property on connections to this protocol. +</tp:docstring> + </property> + + <property name="MinimumAvatarWidth" + tp:name-for-bindings="Minimum_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="RecommendedAvatarHeight" + tp:name-for-bindings="Recommended_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="RecommendedAvatarWidth" + tp:name-for-bindings="Recommended_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarHeight" + tp:name-for-bindings="Maximum_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarWidth" + tp:name-for-bindings="Maximum_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarBytes" + tp:name-for-bindings="Maximum_Avatar_Bytes" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + </interface> +</node> diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml new file mode 100644 index 0000000..ddff332 --- /dev/null +++ b/spec/Protocol_Interface_Presence.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Presence" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Protocol.Interface.Presence"> + <tp:added version="0.21.3">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols where it might be possible to set the + user's presence, and the supported presence types can be predicted + before connecting.</p> + + <tp:rationale> + <p>This allows UIs to show or hide presence types that aren't + always supported, such as "invisible", while not online.</p> + </tp:rationale> + + <p>The properties on this interface SHOULD be cached in the + <code>.manager</code> file, in the + <code>[Protocol <em>proto</em>]</code> + group. For each status <em>s</em> in + <tp:member-ref>Statuses</tp:member-ref>, that group should + contain a key of the form <code>status-<em>s</em></code> whose value + is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII + decimal integer, followed by a space-separated sequence of tokens + from the following set:</p> + + <dl> + <dt>settable</dt> + <dd>If present, the user can set this status on themselves using + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence" + >SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self + in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd> + + <dt>message</dt> + <dd>If present, the user can set a non-empty message for this status; + this corresponds to Can_Have_Message in the + <tp:type>Simple_Status_Spec</tp:type> struct.</dd> + </dl> + + <p>Unrecognised tokens MUST be ignored.</p> + + <p>For instance, an XMPP connection manager might have this + <code>.manager</code> file:</p> + +<pre>[Protocol jabber] +Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence; +param-account=s required +param-password=s required +status-offline=1 +status-unknown=7 +status-error=8 +status-hidden=5 settable message +status-xa=4 settable message +status-away=3 settable message +status-dnd=6 settable message +status-available=2 settable message +status-chat=2 settable message +</pre> + + <p>which corresponds to these property values (using a Python-like + syntax):</p> + +<pre>Statuses = { + 'offline': (OFFLINE, False, False), + 'unknown': (UNKNOWN, False, False), + 'error': (ERROR, False, False), + 'hidden': (HIDDEN, True, True), + 'xa': (EXTENDED_AWAY, True, True), + 'away': (AWAY, True, True), + 'dnd': (BUSY, True, True), + 'available': (AVAILABLE, True, True), + 'chat': (AVAILABLE, True, True), +} +</pre> + </tp:docstring> + + <property name="Statuses" + tp:name-for-bindings="Statuses" + type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read"> + <tp:docstring> + <p>The statuses that might appear in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.SimplePresence.Statuses</tp:dbus-ref> + property on a connection to this protocol that supports + SimplePresence. This property is immutable.</p> + + <p>Depending on server capabilities, it is possible that not all + of these will actually appear on the Connection.</p> + </tp:docstring> + </property> + + </interface> +</node> diff --git a/spec/all.xml b/spec/all.xml new file mode 100644 index 0000000..3123401 --- /dev/null +++ b/spec/all.xml @@ -0,0 +1,303 @@ +<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.21.8</tp:version> + +<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> +<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> +<tp:copyright>Copyright © 2006 INdT</tp:copyright> + +<tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> +</tp:license> + +<tp:section name="Connection Managers"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Connection Manager is a factory for connections. + </p> + </tp:docstring> + <xi:include href="Connection_Manager.xml"/> + <xi:include href="Protocol.xml"/> + <xi:include href="Protocol_Interface_Addressing.xml"/> + <xi:include href="Protocol_Interface_Avatars.xml"/> + <xi:include href="Protocol_Interface_Presence.xml"/> + + <tp:section name="Connection Object"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Connections represent active protocol sessions. There are a number of core + interfaces which all connections should implement, and a number of optional + interfaces which provide various functionality related to contacts and to + the connection itself. + </p> + </tp:docstring> + <xi:include href="Connection.xml"/> + <xi:include href="Connection_Future.xml"/> + <xi:include href="Connection_Interface_Contacts.xml"/> + <xi:include href="Connection_Interface_Requests.xml"/> + + <tp:section name="Contact list interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + On protocols that support contact lists, these interface expose the user's + contact lists, along with presence subscription information and contact + list groups (if supported). + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Contact_List.xml"/> + <xi:include href="Connection_Interface_Contact_Groups.xml"/> + </tp:section> + + <tp:section name="Contact metadata interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + These optional Connection interfaces expose metadata about contacts on + this connection—from their current presence through to the type of client + they're connected with—and allow the local user to publish such metadata + back to their contacts. + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Aliasing.xml"/> + <xi:include href="Connection_Interface_Avatars.xml"/> + <xi:include href="Connection_Interface_Capabilities.xml"/> + <xi:include href="Connection_Interface_Client_Types.xml"/> + <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> + <xi:include href="Connection_Interface_Contact_Info.xml"/> + <xi:include href="Connection_Interface_Location.xml"/> + <xi:include href="Connection_Interface_Presence.xml"/> + <xi:include href="Connection_Interface_Renaming.xml"/> + <xi:include href="Connection_Interface_Resources.xml"/> + <xi:include href="Connection_Interface_Simple_Presence.xml"/> + </tp:section> + + <tp:section name="Connection feature interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + These optional Connection interfaces expose protocol-specific features, + and allow configuring the running connection. + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Addressing.xml"/> + <xi:include href="Connection_Interface_Anonymity.xml"/> + <xi:include href="Connection_Interface_Balance.xml"/> + <xi:include href="Connection_Interface_Cellular.xml"/> + <xi:include href="Connection_Interface_Communication_Policy.xml"/> + <xi:include href="Connection_Interface_Forwarding.xml"/> + <xi:include href="Connection_Interface_Keepalive.xml"/> + <xi:include href="Connection_Interface_Mail_Notification.xml"/> + <xi:include href="Connection_Interface_Power_Saving.xml"/> + <xi:include href="Connection_Interface_Service_Point.xml"/> + </tp:section> + </tp:section> + + <xi:include href="Channel_Bundle.xml"/> + + <tp:section name="Channel Object"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Channel is used by Telepathy to exchange data between local + applications and remote servers. A given connection will have many + channels, each one represented by a D-Bus object. + </p> + <p> + Each Channel has a type, represented by a D-Bus interface, and may + implement one or more additional interfaces from the list of channel + interfaces below. + </p> + </tp:docstring> + <xi:include href="Channel.xml"/> + <xi:include href="Channel_Future.xml"/> + + <tp:section name="Channel Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Each Channel implements one of the following types: + </p> + </tp:docstring> + <xi:include href="Channel_Type_Call.xml"/> + <xi:include href="Channel_Type_Contact_List.xml"/> + <xi:include href="Channel_Type_Contact_Search.xml"/> + <xi:include href="Channel_Type_DBus_Tube.xml"/> + <xi:include href="Channel_Type_File_Transfer.xml"/> + <xi:include href="Channel_Type_Room_List.xml"/> + <xi:include href="Channel_Type_Server_Authentication.xml"/> + <xi:include href="Channel_Type_Server_TLS_Connection.xml"/> + <xi:include href="Channel_Type_Stream_Tube.xml"/> + <xi:include href="Channel_Type_Streamed_Media.xml"/> + <xi:include href="Channel_Type_Text.xml"/> + <xi:include href="Channel_Type_Tubes.xml"/> + </tp:section> + + <tp:section name="Channel Interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A Channel may also implement one or more of the following interfaces, + depending on its type. Some interfaces are only applicable to particular + channel types, while others may (in principle) appear on any type of + channel. + </p> + </tp:docstring> + + <xi:include href="Channel_Interface_Addressing.xml"/> + <xi:include href="Channel_Interface_Anonymity.xml"/> + <xi:include href="Channel_Interface_Destroyable.xml"/> + <xi:include href="Channel_Interface_Group.xml"/> + <xi:include href="Channel_Interface_Password.xml"/> + <xi:include href="Channel_Interface_Room.xml"/> + <xi:include href="Channel_Interface_SASL_Authentication.xml"/> + <xi:include href="Channel_Interface_Securable.xml"/> + <xi:include href="Channel_Interface_Service_Point.xml"/> + <xi:include href="Channel_Interface_Tube.xml"/> + + <tp:section name="Text-specific interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>These interfaces may only appear on channels of type <tp:dbus-ref + namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</p> + </tp:docstring> + + <xi:include href="Channel_Interface_Chat_State.xml"/> + <xi:include href="Channel_Interface_HTML.xml"/> + <xi:include href="Channel_Interface_Messages.xml"/> + <xi:include href="Channel_Interface_SMS.xml"/> + </tp:section> + + <tp:section name="Streamed Media-related interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>These interfaces are only applicable to channels of type <tp:dbus-ref + namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref>, with the + exception of the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Hold</tp:dbus-ref> interface, which + may also appear on <tp:dbus-ref + namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels.</p> + </tp:docstring> + + <xi:include href="Channel_Interface_Call_State.xml"/> + <xi:include href="Channel_Interface_DTMF.xml"/> + <xi:include href="Channel_Interface_Hold.xml"/> + <xi:include href="Channel_Interface_Media_Signalling.xml"/> + </tp:section> + + <tp:section name="Conference-related interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>These interfaces provide functionality for ad-hoc conference calls and + chat rooms. They are primarily intended for <tp:dbus-ref + namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>, <tp:dbus-ref + namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> and + <tp:dbus-ref namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> + channels, but may also appear on other types of channel.</p> + </tp:docstring> + + <xi:include href="Channel_Interface_Conference.xml"/> + <xi:include href="Channel_Interface_Splittable.xml"/> + <xi:include href="Channel_Interface_Mergeable_Conference.xml"/> + </tp:section> + </tp:section> + </tp:section> + + <tp:section name="Authentication Objects"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A set of objects to be used for authentication purposes, such + as TLS certificates or handshakes for negotiating end-to-end + security. + </p> + </tp:docstring> + <xi:include href="Authentication_TLS_Certificate.xml"/> + </tp:section> + + <tp:section name="Media"> + <xi:include href="Media_Session_Handler.xml"/> + <xi:include href="Media_Stream_Handler.xml"/> + </tp:section> + + <tp:section name="Calls"> + <xi:include href="Call_Content.xml"/> + <xi:include href="Call_Content_Interface_Media.xml"/> + <xi:include href="Call_Content_Interface_Mute.xml"/> + <xi:include href="Call_Content_Codec_Offer.xml"/> + <xi:include href="Call_Stream.xml"/> + <xi:include href="Call_Stream_Interface_Media.xml"/> + <xi:include href="Call_Stream_Endpoint.xml"/> + </tp:section> + + <tp:section name="Debugging"> + <xi:include href="Debug.xml"/> + </tp:section> +</tp:section> + +<tp:section name="The Account Manager"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The Account Manager is a desktop service that provides account configuration + and can manage the connection managers. In general, clients will use the + account manager to find out about instant messaging accounts and their + associated connections. + </p> + </tp:docstring> + <xi:include href="Account_Manager.xml"/> + <xi:include href="Account.xml"/> + <xi:include href="Account_Interface_Addressing.xml"/> + <xi:include href="Account_Interface_Avatar.xml"/> + <xi:include href="Account_Interface_Storage.xml"/> +</tp:section> + +<tp:section name="The Channel Dispatcher"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The Channel Dispatcher is a desktop service whose purpose is to dispatch + incoming Telepathy Channels to the appropriate client (e.g. incoming text + chat, file transfer, tubes, etc.). + </p> + </tp:docstring> + <xi:include href="Channel_Dispatcher.xml"/> + <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> + <xi:include href="Channel_Dispatch_Operation.xml"/> + <xi:include href="Channel_Request.xml"/> +</tp:section> + +<tp:section name="Clients"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Clients should implement one or more of these interfaces to be able to + handle channels coming in from the Channel Dispatcher. + </p> + </tp:docstring> + <xi:include href="Client.xml"/> + <xi:include href="Client_Observer.xml"/> + <xi:include href="Client_Approver.xml"/> + <xi:include href="Client_Handler.xml"/> + <xi:include href="Client_Handler_Future.xml"/> + <xi:include href="Client_Interface_Requests.xml"/> + + <xi:include href="Channel_Handler.xml"/> +</tp:section> + +<xi:include href="Properties_Interface.xml"/> + +<xi:include href="errors.xml"/> +<xi:include href="generic-types.xml"/> + +<!-- Never implemented, vague +<xi:include href="Connection_Interface_Privacy.xml"/> --> +<!-- Causes havoc, never implemented, unclear requirements +<xi:include href="Channel_Interface_Transfer.xml"/> --> + +</tp:spec> diff --git a/spec/errors.xml b/spec/errors.xml new file mode 100644 index 0000000..eccbd09 --- /dev/null +++ b/spec/errors.xml @@ -0,0 +1,564 @@ +<?xml version="1.0" ?> +<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The D-Bus errors used in Telepathy all start with + <code>org.freedesktop.Telepathy.Error.</code>. They are used in + D-Bus messages of type ERROR, and also as plain strings annotated with + the <tp:type>DBus_Error_Name</tp:type> type.</p> + + <p>In principle, any method can raise any error (this is a general fact + of IPC). For instance, generic D-Bus errors starting with + <code>org.freedesktop.DBus.Error.</code> will occur in some + situations.</p> + + <p>Telepathy methods can also raise implementation-specific errors to + indicate specialized failure conditions. For better interoperability, + if a suitable Telepathy error exists, it should be preferred.</p> + + <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code> + is reserved for use by the D-Bus client implementation in telepathy-qt4, + which uses it to represent certain error situations that did not involve + a D-Bus ERROR message. These errors are defined and documented as part of + telepathy-qt4's C++ API, and should not be used on D-Bus.</p> + </tp:docstring> + + <tp:error name="Network Error"> + <tp:docstring> + Raised when there is an error reading from or writing to the network. + </tp:docstring> + </tp:error> + + <tp:error name="Not Implemented"> + <tp:docstring> + Raised when the requested method, channel, etc is not available on this connection. + </tp:docstring> + </tp:error> + + <tp:error name="Invalid Argument"> + <tp:docstring> + Raised when one of the provided arguments is invalid. + </tp:docstring> + </tp:error> + + <tp:error name="Not Available"> + <tp:docstring> + Raised when the requested functionality is temporarily unavailable. + </tp:docstring> + </tp:error> + + <tp:error name="Permission Denied"> + <tp:docstring> + The user is not permitted to perform the requested operation. + </tp:docstring> + </tp:error> + + <tp:error name="Disconnected"> + <tp:docstring> + The connection is not currently connected and cannot be used. + This error may also be raised when operations are performed on a + Connection for which + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref> + has signalled status Disconnected for reason None. + + <tp:rationale> + The second usage corresponds to None in the + <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason + is available, the corresponding error should be used instead. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Invalid Handle"> + <tp:docstring> + The handle specified is unknown on this channel or connection. + </tp:docstring> + </tp:error> + + <tp:error name="Channel.Banned"> + <tp:docstring> + You are banned from the channel. + </tp:docstring> + </tp:error> + + <tp:error name="Channel.Full"> + <tp:docstring> + The channel is full. + </tp:docstring> + </tp:error> + + <tp:error name="Channel.Invite Only"> + <tp:docstring> + The requested channel is invite-only. + </tp:docstring> + </tp:error> + + <tp:error name="Not Yours"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requested channel or other resource already exists, and another + user interface in this session is responsible for it.</p> + + <p>User interfaces SHOULD handle this error unobtrusively, since it + indicates that some other user interface is already processing the + channel.</p> + </tp:docstring> + </tp:error> + + <tp:error name="Cancelled"> + <tp:docstring> + Raised by an ongoing request if it is cancelled by user request before + it has completed, or when operations are performed on an object which + the user has asked to close (for instance, a Connection where the user + has called Disconnect, or a Channel where the user has called Close). + + <tp:rationale> + The second form can be used to correspond to the Requested member in + the <tp:type>Connection_Status_Reason</tp:type> enum, or to + to represent the situation where disconnecting a Connection, + closing a Channel, etc. has been requested by the user but this + request has not yet been acted on, for instance because the + service will only act on the request when it has finished processing + an event queue. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Authentication Failed"> + <tp:docstring> + Raised when authentication with a service was unsuccessful. + <tp:rationale> + This corresponds to Authentication_Failed in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Encryption Not Available"> + <tp:docstring> + Raised if a user request insisted that encryption should be used, + but encryption was not actually available. + + <tp:rationale> + This corresponds to part of Encryption_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated + into a distinct error here because the two concepts that were part + of EncryptionError seem to be things that could reasonably appear + differently in the UI. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Encryption Error"> + <tp:docstring> + Raised if encryption appears to be available, but could not actually be + used (for instance if SSL/TLS negotiation fails). + <tp:rationale> + This corresponds to part of Encryption_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Not Provided"> + <tp:docstring> + Raised if the server did not provide a SSL/TLS certificate. This error + MUST NOT be used to represent the absence of a client certificate + provided by the Telepathy connection manager. + <tp:rationale> + This corresponds to Cert_Not_Provided in the + <tp:type>Connection_Status_Reason</tp:type> enum. That error + explicitly applied only to server SSL certificates, so this one + is similarly limited; having the CM present a client certificate + is a possible future feature, but it should have its own error + handling. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Untrusted"> + <tp:docstring> + Raised if the server provided a SSL/TLS certificate signed by an + untrusted certifying authority. This error SHOULD NOT be used to + represent a self-signed certificate: see the Self Signed error for that. + <tp:rationale> + This corresponds to Cert_Untrusted in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Untrusted in the + <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum, with a clarification + to avoid ambiguity. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Expired"> + <tp:docstring> + Raised if the server provided an expired SSL/TLS certificate. + <tp:rationale> + This corresponds to Cert_Expired in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Expired in + the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Not Activated"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that will become + valid at some point in the future. + <tp:rationale> + This corresponds to Cert_Not_Activated in the + <tp:type>Connection_Status_Reason</tp:type> enum and to + Not_Activated in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Fingerprint Mismatch"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that did not have + the expected fingerprint. + <tp:rationale> + This corresponds to Cert_Fingerprint_Mismatch in the + <tp:type>Connection_Status_Reason</tp:type> enum and to + Fingerprint_Mismatch in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Hostname Mismatch"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Raised if the server provided an SSL/TLS certificate that did not match + its hostname.</p> + <p>You MAY be able to get more details about the expected and certified + hostnames by looking up the 'expected-hostname' and 'certificate-hostname' + keys in the details map that came together with this error.</p> + <tp:rationale> + This corresponds to Cert_Hostname_Mismatch in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Hostname_Mismatch + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Self Signed"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that is self-signed + and untrusted. + <tp:rationale> + This corresponds to Cert_Self_Signed in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Self_Signed + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Revoked"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that has been + revoked. + <tp:rationale> + This corresponds to Cert_Revoked in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Revoked + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Insecure"> + <tp:added version="0.19.11"/> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that uses an + insecure cipher algorithm or is cryptographically weak. + <tp:rationale> + This corresponds to Cert_Insecure in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Insecure + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Invalid"> + <tp:added version="0.19.11"/> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that is + unacceptable in some way that does not have a more specific error. + <tp:rationale> + This corresponds to Cert_Other_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Unknown + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Limit Exceeded"> + <tp:added version="0.19.11"/> + <tp:docstring> + Raised if the length in bytes of the server certificate, or the depth of the + server certificate chain exceeds the limits imposed by the crypto + library. + <tp:rationale> + This corresponds to Cert_Limit_Exceeded in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Limit_Exceeded + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Not Capable"> + <tp:docstring> + Raised when requested functionality is unavailable due to contact + not having required capabilities. + </tp:docstring> + </tp:error> + + <tp:error name="Offline"> + <tp:docstring> + Raised when requested functionality is unavailable because a contact is + offline. + + <tp:rationale> + This corresponds to Offline in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Channel.Kicked"> + <tp:docstring> + Used to represent a user being ejected from a channel by another user, + for instance being kicked from a chatroom. + + <tp:rationale> + This corresponds to Kicked in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Busy"> + <tp:docstring> + Used to represent a user being removed from a channel because of a + "busy" indication. This error SHOULD NOT be used to represent a server + or other infrastructure being too busy to process a request - for that, + see ServerBusy. + + <tp:rationale> + This corresponds to Busy in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="No Answer"> + <tp:docstring> + Used to represent a user being removed from a channel because they did + not respond, e.g. to a StreamedMedia call. + + <tp:rationale> + This corresponds to No_Answer in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Does Not Exist"> + <tp:docstring> + Raised when the requested user does not, in fact, exist. + + <tp:rationale> + This corresponds to Invalid_Contact in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be + used to represent other things not existing (like chatrooms, perhaps). + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Terminated"> + <tp:docstring> + Raised when a channel is terminated for an unspecified reason. In + particular, this error SHOULD be used whenever normal termination of + a 1-1 StreamedMedia call by the remote user is represented as a D-Bus + error name. + + <tp:rationale> + This corresponds to None in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Connection Refused"> + <tp:docstring> + Raised when a connection is refused. + </tp:docstring> + </tp:error> + + <tp:error name="Connection Failed"> + <tp:docstring> + Raised when a connection can't be established. + </tp:docstring> + </tp:error> + + <tp:error name="Connection Lost"> + <tp:docstring> + Raised when a connection is broken. + </tp:docstring> + </tp:error> + + <tp:error name="Already Connected"> + <tp:docstring> + Raised when the user attempts to connect to an account but they are + already connected (perhaps from another client or computer), and the + protocol or account settings do not allow this. + + <tp:rationale> + XMPP can have this behaviour if the user chooses the same resource + in both clients (it is server-dependent whether the result is + AlreadyConnected on the new connection, ConnectionReplaced on the + old connection, or two successful connections). + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Connection Replaced"> + <tp:docstring> + Raised by an existing connection to an account if it is replaced by + a new connection (perhaps from another client or computer). + + <tp:rationale> + In MSNP, when connecting twice with the same Passport, the new + connection "wins" and the old one is automatically disconnected. + XMPP can also have this behaviour if the user chooses the same + resource in two clients (it is server-dependent whether the result is + AlreadyConnected on the new connection, ConnectionReplaced on the + old connection, or two successful connections). + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Registration Exists"> + <tp:docstring> + Raised during in-band registration if the server indicates that the + requested account already exists. + </tp:docstring> + </tp:error> + + <tp:error name="Service Busy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Raised if a server or some other piece of infrastructure cannot process + the request, e.g. due to resource limitations. Clients MAY try again + later. + + <tp:rationale> + This is not the same error as Busy, which indicates that a + <em>user</em> is busy. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Resource Unavailable"> + <tp:docstring> + Raised if a request cannot be satisfied because a process local to the + user has insufficient resources. Clients MAY try again + later. + + <tp:rationale> + For instance, the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> + might raise this error for some or all channel requests if it has + detected that there is not enough free memory. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Would Break Anonymity"> + <tp:added version="0.19.7"/> + <tp:docstring> + Raised if a request cannot be satisfied without violating an earlier + request for anonymity, and the earlier request specified that raising + an error is preferable to disclosing the user's identity (for instance + via <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref>). + </tp:docstring> + </tp:error> + + <tp:error name="Not Yet"> + <tp:added version="0.19.12"/> + <tp:docstring> + Raised when the requested functionality is not yet available, but is + likely to become available after some time has passed. + </tp:docstring> + </tp:error> + + <tp:error name="Rejected"> + <tp:added version="0.21.2"/> + <tp:docstring> + Raised when an incoming or outgoing <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is + rejected by the the receiver. + </tp:docstring> + </tp:error> + + <tp:error name="Picked Up Elsewhere"> + <tp:added version="0.21.3"/> + <tp:docstring> + Raised when a call was terminated as a result of the local user + picking up the call on a different resource. + </tp:docstring> + </tp:error> + + <tp:error name="Service Confused"> + <tp:added version="0.21.5"/> + <tp:docstring> + Raised when a server or other piece of infrastructure indicates an + internal error, or when a message that makes no sense is received from + a server or other piece of infrastructure. + + <tp:rationale> + For instance, this is appropriate for XMPP's + <code>internal-server-error</code>, and is also appropriate if + you receive sufficiently inconsistent information from a server that + you cannot continue. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Confused"> + <tp:added version="0.21.5"/> + <tp:docstring> + Raised if a server rejects protocol messages from a connection manager + claiming that they do not make sense, two local processes fail to + understand each other, or an apparently impossible situation is + reached. + + <tp:rationale> + For instance, this would be an appropriate mapping for XMPP's + errors bad-format, invalid-xml, etc., which can't happen unless + the local (or remote) XMPP implementation is faulty. This is + also analogous to + <tp:type>Media_Stream_Error</tp:type>_Invalid_CM_Behavior, + <code>TP_DBUS_ERROR_INCONSISTENT</code> in telepathy-glib, and + <code>TELEPATHY_QT4_ERROR_INCONSISTENT</code> in telepathy-qt4. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> +</tp:errors> diff --git a/spec/generic-types.xml b/spec/generic-types.xml new file mode 100644 index 0000000..014f8ad --- /dev/null +++ b/spec/generic-types.xml @@ -0,0 +1,215 @@ +<tp:generic-types + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:simple-type name="Unix_Timestamp" type="u"> + <tp:docstring>An unsigned 32-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z)</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Unix_Timestamp64" type="x"> + <tp:docstring>An signed 64-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z); negative for times before the epoch</tp:docstring> + + <tp:rationale>The Text interface is the only user of Unix_Timestamp so + far, and we'd like to be Y2038 compatible in future + interfaces.</tp:rationale> + </tp:simple-type> + + <tp:simple-type name="DBus_Bus_Name" type="s" + array-name="DBus_Bus_Name_List"> + <tp:docstring>A string representing a D-Bus bus name - either a well-known + name like "org.freedesktop.Telepathy.MissionControl" or a unique name + like ":1.123"</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Well_Known_Name" type="s" + array-name="DBus_Well_Known_Name_List"> + <tp:docstring>A string representing a D-Bus well-known + name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Unique_Name" type="s" + array-name="DBus_Unique_Name_List"> + <tp:docstring>A string representing a D-Bus unique name, such as + ":1.123"</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Interface" type="s" + array-name="DBus_Interface_List"> + <tp:docstring>An ASCII string representing a D-Bus interface - two or more + elements separated by dots, where each element is a non-empty + string of ASCII letters, digits and underscores, not starting with + a digit. The maximum total length is 255 characters. For example, + "org.freedesktop.DBus.Peer".</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Error_Name" type="s"> + <tp:docstring>An ASCII string representing a D-Bus error. This is + syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the + meaning is different.</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Signature" type="s"> + <tp:docstring>A string representing a D-Bus signature + (the 'g' type isn't used because of poor interoperability, particularly + with dbus-glib)</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Member" type="s"> + <tp:docstring>An ASCII string representing a D-Bus method, signal + or property name - a non-empty string of ASCII letters, digits and + underscores, not starting with a digit, with a maximum length of 255 + characters. For example, "Ping".</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Qualified_Member" type="s" + array-name="DBus_Qualified_Member_List"> + <tp:docstring>A string representing the full name of a D-Bus method, + signal or property, consisting of a DBus_Interface, followed by + a dot, followed by a DBus_Member. For example, + "org.freedesktop.DBus.Peer.Ping".</tp:docstring> + </tp:simple-type> + + <tp:mapping name="Qualified_Property_Value_Map" + array-name="Qualified_Property_Value_Map_List"> + <tp:docstring>A mapping from strings representing D-Bus + properties (by their namespaced names) to their values.</tp:docstring> + <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> + <tp:docstring> + A D-Bus interface name, followed by a dot and a D-Bus property name. + </tp:docstring> + </tp:member> + <tp:member type="v" name="Value"> + <tp:docstring> + The value of the property. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="String_Variant_Map" array-name="String_Variant_Map_List"> + <tp:docstring>A mapping from strings to variants representing extra + key-value pairs.</tp:docstring> + <tp:member type="s" name="Key"/> + <tp:member type="v" name="Value"/> + </tp:mapping> + + <tp:mapping name="String_String_Map" array-name="String_String_Map_List"> + <tp:docstring>A mapping from strings to strings representing extra + key-value pairs.</tp:docstring> + <tp:member type="s" name="Key"/> + <tp:member type="s" name="Value"/> + </tp:mapping> + + <tp:struct name="Socket_Address_IP" array-name="Socket_Address_IP_List"> + <tp:docstring>An IP address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>Either a dotted-quad IPv4 address literal as for + <tp:type>Socket_Address_IPv4</tp:type>, or an RFC2373 IPv6 address + as for <tp:type>Socket_Address_IPv6</tp:type>. + </tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv4"> + <tp:docstring>An IPv4 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv6"> + <tp:docstring>An IPv6 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv4"> + <tp:docstring>An IPv4 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv6"> + <tp:docstring>An IPv6 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:simple-type name="User_Action_Timestamp" type="x"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which an user action occurred. This type has the 2 + following special values:</p> + + <p>0: the action doesn't involve any user action. Clients + SHOULD avoid stealing focus when presenting the channel.</p> + + <p>MAX_INT64: clients SHOULD behave as though the user action happened + at the current time, e.g. a client MAY request that its window gains + focus. + </p> + + <tp:rationale> + <p>This can be used by clients that can't know the X server time like + command line applications for example.</p> + </tp:rationale> + + <p>For all the other values it corresponds to the time of the user + action. Clients SHOULD use this for focus-stealing prevention, + if applicable. + Note that the time is dependant on the local + environment and so is not necessarily a wall-clock time. + For example in an X environment it's expected to be the X timestamp + of events. + This corresponds to the _NET_WM_USER_TIME property in + <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> + </tp:docstring> + </tp:simple-type> + + <tp:mapping name="Object_Immutable_Properties_Map" + array-name="Object_Immutable_Properties_Map_List"> + <tp:added version="0.19.12"/> + <tp:docstring>A mapping from object path to the immutable properties of + the object.</tp:docstring> + <tp:member type="o" name="Path"> + <tp:docstring> + The object path of an object + </tp:docstring> + </tp:member> + <tp:member type="a{sv}" name="Immutable_Properties" tp:type="Qualified_Property_Value_Map"> + <tp:docstring> + The immutable properties of the object + </tp:docstring> + </tp:member> + </tp:mapping> + +</tp:generic-types> diff --git a/spec/template.xml b/spec/template.xml new file mode 100644 index 0000000..7264720 --- /dev/null +++ b/spec/template.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" ?> +<node name="/Foo" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Foo.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.21.UNRELEASED">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Foo.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |