diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2008-12-18 12:16:49 +0000 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2009-01-06 14:59:03 +0000 |
| commit | f31355515a3cb0f75ff75657a83c8077c2f68b5f (patch) | |
| tree | c4833e11e11e9e47312f1ebb6d3abaed97142537 /spec | |
| parent | 86b5870182dc43a540de73a268376a5999a54402 (diff) | |
Update to telepathy-spec 0.17.16
Resulting ABI changes in stable interfaces:
- generate Telepathy::Avatar struct
- add optional MembersChangedDetailed signal to the Group interface
- add Messages interface as stable
- add ConnMgrParamFlagDBusProperty
Diffstat (limited to 'spec')
41 files changed, 2246 insertions, 492 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index 5f7b5b7a..cb803214 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -33,8 +33,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. that appears in the connection manager's well-known bus name and object path</li> <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in - ConnectionManager.ListProtocols, but with "-" replaced with "_" - (i.e. the same as in the object-path of a Connection)</li> + <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> @@ -123,9 +126,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. This account has been removed. <tp:rationale> - This is redundant with AccountRemoved, but it's still worth having, + 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 + you whether your Account is valid — ideally, an account-editing UI should only care about a single Account. </tp:rationale> </tp:docstring> @@ -142,7 +147,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <arg name="Properties" type="a{sv}"> <tp:docstring> - A map from property names in this namespace (e.g. Nickname) to + 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> @@ -223,24 +229,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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> + <p>The AccountManager SHOULD allow this property to be set on invalid + accounts, but MUST NOT attempt to put invalid accounts online + even if they become Enabled.</p> - <tp:rationale> - <p>There doesn't seem to be any good reason not to allow this.</p> - </tp:rationale> + <tp:rationale> + <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="as" access="readwrite"> + 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 SetAliases + 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> @@ -258,12 +265,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. type="a{sv}" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A map from connection manager parameter names (as in the - ConnectionManager interface) to their values. This property includes + <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 - UpdateParameters instead.</p> + <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p> <tp:rationale> This avoids NMC being tied to gconf as a matter of API. @@ -272,10 +281,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </property> <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters"> - <tp:docstring> - Change the value of the Parameters property. Any changes will not - take effect until the next time the account is disconnected and - reconnected. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Change the value of the <tp:member-ref>Parameters</tp:member-ref> + property. If any of the changed parameters' + <tp:type>Conn_Mgr_Param_Flags</tp:type> include + <code>DBus_Property</code>, the change will be applied 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. <tp:rationale> Migration tools that twiddle the settings of all accounts shouldn't @@ -284,6 +298,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </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> + <arg name="Set" type="a{sv}" direction="in"> <tp:docstring> A mapping from parameter names to their values. These parameters @@ -330,11 +349,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Connect_Automatically"> <tp:docstring> If true, the account manager SHOULD attempt to put this account - online with the AutomaticPresence whenever possible (in the base + 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 AutomaticPresence if requested by the user (for + 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). @@ -347,9 +368,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <property name="Connection" tp:name-for-bindings="Connection" type="o" access="read"> - <tp:docstring> - Either the object path of the connection to this account, - or the special value '/' if there is no connection. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + 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. <tp:rationale> Object paths aren't nullable, so we can't use an empty string. @@ -360,7 +383,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <property name="ConnectionStatus" type="u" access="read" tp:name-for-bindings="Connection_Status"> <tp:docstring> - If the Connection property is non-empty, the status of that connection. + 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 @@ -380,7 +404,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <property name="ConnectionStatusReason" type="u" access="read" tp:name-for-bindings="Connection_Status_Reason"> <tp:docstring> - The reason for the last change to ConnectionStatus. + 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. @@ -397,7 +422,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> The actual presence. If the connection is not online, this should be (Connection_Presence_Type_Offline, "", ""). - If the connection is online but does not support the Presence + If the connection is online but does not support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref> interface, this should be (Connection_Presence_Type_Unset, "", ""). The account manager is expected to set this by observing signals from the Connection. @@ -412,14 +438,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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 CurrentPresence match RequestedPresence as closely as + 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 AutomaticPresence.</p> + thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p> <tp:rationale> This corresponds to e.g. GetPresence and GetPresenceMessage @@ -432,8 +459,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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 InspectHandle method is called on the - result of GetSelfHandle() for an active connection).</p> + 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> diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml index 9bf31a99..6c85b8e6 100644 --- a/spec/Account_Interface_Avatar.xml +++ b/spec/Account_Interface_Avatar.xml @@ -20,6 +20,8 @@ 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> @@ -35,8 +37,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </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)" access="readwrite"> + 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, @@ -54,7 +64,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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> diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml index b92913e2..39e08b5b 100644 --- a/spec/Account_Manager.xml +++ b/spec/Account_Manager.xml @@ -63,7 +63,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Valid_Accounts"> <tp:docstring> A list of the valid (complete, usable) accounts. Change notification - is via AccountValidityChanged. + is via <tp:member-ref>AccountValidityChanged</tp:member-ref>. <tp:rationale> This split between valid and invalid accounts makes it easy to @@ -78,7 +78,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Invalid_Accounts"> <tp:docstring> A list of incomplete or otherwise unusable accounts. Change - notification is via AccountValidityChanged. + notification is via + <tp:member-ref>AccountValidityChanged</tp:member-ref>. </tp:docstring> </property> @@ -127,9 +128,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="CreateAccount" tp:name-for-bindings="Create_Account"> <tp:docstring> - Request the creation of a new account. The account manager SHOULD NOT - allow invalid accounts to be created. Accounts created through this - API SHOULD have an empty PresetParameters property. + 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> <arg name="Connection_Manager" direction="in" type="s" @@ -145,7 +146,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </arg> <arg name="Display_Name" direction="in" type="s"> - <tp:docstring>The initial value of the new account's DisplayName + <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 MAY modify this to make it unique, for instance by appending a number or the 'account' parameter.</tp:docstring> @@ -153,11 +155,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <arg name="Parameters" direction="in" type="a{sv}"> <tp:docstring>Initial parameter values, as would be passed to - RequestConnection.</tp:docstring> + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring> </arg> <arg name="Account" direction="out" type="o"> - <tp:docstring>The new account.</tp:docstring> + <tp:docstring>The new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring> </arg> <tp:possible-errors> diff --git a/spec/Channel.xml b/spec/Channel.xml index f560ed8f..0026e04c 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -29,7 +29,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>For compatibility between older connection managers and newer clients, if this is unavailable or is an empty string, - clients MUST use the result of calling GetChannelType.</p> + 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 @@ -56,11 +57,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>For compatibility between older connection managers and newer clients, if this is unavailable, or if this is an empty list and - ChannelType is an empty string, clients MUST use the result of - calling GetInterfaces instead. If this is an empty list but - ChannelType is non-empty, clients SHOULD NOT call GetInterfaces; - this implies that connection managers that implement the - ChannelType property MUST also implement the Interfaces property + <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> @@ -81,7 +83,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type - is given by the TargetHandleType property.</p> + 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 @@ -130,9 +133,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <ul> <li>New channel C is signalled with target handle T</li> - <li>Client calls InspectHandles(CONTACT, [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>InspectHandles(CONTACT, [T]) returns an error</li> + <li><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [T]) returns an error</li> </ul> </tp:rationale> @@ -163,7 +170,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 TargetHandle.</p> + <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> @@ -178,7 +185,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="Close" tp:name-for-bindings="Close"> <tp:docstring> Request that the channel be closed. This is not the case until - the Closed signal has been emitted, and depending on the connection + 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. @@ -216,9 +224,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>The interface name</tp:docstring> </arg> <tp:docstring> - Returns the interface name for the type of this channel. - Clients SHOULD use the ChannelType property instead, falling back - to this method only if necessary. + 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 @@ -244,7 +252,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or zero if it is transient and defined only by its contents. Clients - SHOULD use the TargetHandle and TargetHandleType properties instead, + 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> @@ -264,8 +273,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Get the optional interfaces implemented by the channel. - Clients SHOULD use the Interfaces property instead, falling back - to this method only if necessary. + 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 @@ -356,7 +365,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ it's easy to imagine a protocol where chatroom invitations can be anonymous).</p> - <p>For channels with the Group interface, this SHOULD be the same + <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> @@ -383,9 +394,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <ul> <li>New StreamedMedia channel C is signalled with initiator handle I</li> - <li>Client calls InspectHandles(CONTACT, [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>InspectHandles(CONTACT, [I]) returns an error</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> @@ -401,14 +416,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must be implemented by all channel objects, along with one single channel type, - such as Channel.Type.ContactList which represents a list of people (such - as a buddy list) or a Channel.Type.Text which represents a channel over - which textual messages are sent and received.</p> + 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 a <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 Connection, followed by '/'. There MAY be any number - of additional object-path components, which clients MUST NOT attempt - to parse.</p> + 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 @@ -429,16 +447,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it means that the channel is defined by some other terms, such as it may be a transient group defined only by its members as visible - through the Channel.Interface.Group interface.</p> + through the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> + interface.</p> <p>Other optional interfaces can be implemented to indicate other available - functionality, such as Channel.Interface.Group if the channel contains - a number of contacts, Channel.Interface.Password to indicate - that a channel may have a password set to require entry, and - Properties for extra data about channels which represent chat - rooms or voice calls. The interfaces implemented may not vary after the - channel's creation has been signalled to the bus (with the connection's - NewChannel signal).</p> + 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">Properties</tp:dbus-ref> for + extra data about channels which represent chat rooms or voice calls. The + interfaces implemented may not vary after the channel's creation has been + signalled to the bus (with the connection's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref> + signal).</p> <p>Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index c9f55927..7f61f6f3 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -51,7 +51,11 @@ each containing one channel.)</p> <p>First, the channel dispatcher SHOULD construct a list of all the - channel handlers that could handle all the channels, ordered by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>s + that could handle all the channels (based on their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref> + 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 @@ -62,29 +66,28 @@ channel handlers that are already handling channels from the same bundle.</p> - <p>Processing of a channel dispatch operation proceeds as follows. - If the channels in a channel dispatch operation are in the same - bundle as a channel that is already being handled, and the handler - could also handle the channels being dispatched, the channel - dispatcher SHOULD call the handler's - HandleAdditionalChannels - method to see whether the handler will accept the new channels too. - If the handler takes responsibility for the channels, - processing stops, and no approvers are run.</p> - - <p>(FIXME: this is far too subtle and everyone will get it wrong. - Open issue: how else do we address this use case?)</p> + <p>If a handler with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">BypassApproval</tp:dbus-ref> + <code>= True</code> could handle the channels in the dispatch + operation, then the channel dispatcher SHOULD call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">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 Text channel is added to an existing - bundle containing a StreamedMedia channel, there shouldn't be + 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>If not, the channel dispatcher SHOULD send the channel dispatch + <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 @@ -211,13 +214,16 @@ 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 Claim instead + <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 Handle, this method + <p>If the channel handler raises an error from <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>, + this method MAY respond by raising that same error, even if it is not specifically documented here.</p> </tp:docstring> @@ -330,9 +336,10 @@ in a way that avoids immediate re-use.</p> <tp:rationale> - <p>Otherwise, clients might accidentally call HandleWith or Claim - on a new dispatch operation instead of the one they - intended to handle.</p> + <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> </tp:docstring> </signal> diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index c9b8a2bc..2c07305e 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -197,6 +197,17 @@ on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.</p> </tp:rationale> + + <p>If this is a well-known bus name, the channel dispatcher SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref> + on that Handler after this method has returned.</p> + + <tp:rationale> + <p>This ordering allows a Handler which calls CreateChannel with + itself as the preferred handler to associate the call to + AddRequest with that call.</p> + </tp:rationale> </tp:docstring> </arg> @@ -303,6 +314,17 @@ can recover state if it crashes and is restarted.</p> </tp:rationale> + <p>If this is a well-known bus name, the channel dispatcher SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref> + on that Handler after this method has returned.</p> + + <tp:rationale> + <p>This ordering allows a Handler which calls EnsureChannel with + itself as the preferred handler to associate the call to + AddRequest with that call.</p> + </tp:rationale> + <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) diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml index 40cd86e5..b59ef72a 100644 --- a/spec/Channel_Dispatcher_Interface_Operation_List.xml +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -31,8 +31,9 @@ all the pending dispatch operations, with change notification.</p> <tp:rationale> - <p>The existence of the DispatchOperations property allows a newly - started approver to pick up existing dispatch operations.</p> + <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> @@ -85,8 +86,9 @@ 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 NewDispatch and - DispatchFinished signals.</p> + 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> @@ -122,7 +124,8 @@ <tp:rationale> Strictly speaking this is redundant with ChannelDispatchOperation.Finished, but it provides full - change-notification for the DispatchOperations property. + change-notification for the + <tp:member-ref>DispatchOperations</tp:member-ref> property. </tp:rationale> </tp:docstring> diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml index 235ff2c4..823d8a0d 100644 --- a/spec/Channel_Future.xml +++ b/spec/Channel_Future.xml @@ -23,7 +23,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface contains functionality which we intend to incorporate - into the Channel interface in future. It should be considered to + 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> diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml index e9428391..3a8f6b14 100644 --- a/spec/Channel_Handler.xml +++ b/spec/Channel_Handler.xml @@ -20,7 +20,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface exported by client applications which are able to - handle incoming channels.</p> + handle incoming channels. This + interface is intended to be deprecated in favour of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Client.Handler.DRAFT</tp:dbus-ref> + when that interface comes out of DRAFT; client authors should consider + implementing that interface instead. + </p> </tp:docstring> <tp:added version="0.17.0"/> diff --git a/spec/Channel_Interface_Call_Merging.xml b/spec/Channel_Interface_Call_Merging.xml index a98daf12..72caaae9 100644 --- a/spec/Channel_Interface_Call_Merging.xml +++ b/spec/Channel_Interface_Call_Merging.xml @@ -64,7 +64,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Request that the given contact is removed from this channel, and a new channel is created to communicate with them privately instead. - This is the inverse of Merge. + This is the inverse of <tp:member-ref>Merge</tp:member-ref>. </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> diff --git a/spec/Channel_Interface_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml index aa292367..292e6e1b 100644 --- a/spec/Channel_Interface_Chat_State.xml +++ b/spec/Channel_Interface_Chat_State.xml @@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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: one of the values of ChannelChatState. + The new state. </tp:docstring> </arg> <tp:docstring> @@ -42,7 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <arg name="State" type="u" tp:type="Channel_Chat_State"> <tp:docstring> - The new state of this contact: one of the values of ChannelChatState. + The new state of this contact. </tp:docstring> </arg> <tp:docstring> @@ -77,7 +77,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> </tp:enum> - <tp:docstring> + <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> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index 8abb8dce..7545ff6f 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -30,7 +30,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Start sending a DTMF tone on this stream. Where possible, the tone - will continue until StopTone is called. On certain protocols, it may + 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. @@ -55,7 +56,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> </arg> <tp:docstring> - Stop sending any DTMF tone which has been started using the StartTone + Stop sending any DTMF tone which has been started using the + <tp:member-ref>StartTone</tp:member-ref> method. If there is no current tone, this method will do nothing. </tp:docstring> <tp:possible-errors> @@ -129,7 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ audio streams which have been established using the StreamedMedia channel type. The event codes used are in common with those defined in <a href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are - listed in the DTMF_Event enumeration. + listed in the <tp:type>DTMF_Event</tp:type> enumeration. </tp:docstring> </interface> diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml index 4e69b88d..7aeb6ccc 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -24,7 +24,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List"> <tp:docstring>A structure representing a contact whose attempt to join a group is to be confirmed by the local user using - AddMembers.</tp:docstring> + <tp:member-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 @@ -65,7 +65,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>A message may be provided along with the request, which will be sent to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and - CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this + 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; @@ -118,49 +119,57 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u"> <tp:flag suffix="Can_Add" value="1"> <tp:docstring> - The AddMembers method can be used to add or invite members who are + 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 RemoveMembers method can be used to remove channel members + 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 RemoveMembers method can be used on people on the remote + 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 AddMembers on + 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 RemoveMembers on + 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 AddMembers on + 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 RemoveMembers on + 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 RemoveMembers on + 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> @@ -170,9 +179,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The members of this group have handles which are specific to this channel, and are not valid as general-purpose handles on the connection. Depending on the channel, it may be possible to - call GetHandleOwners to find the owners of these handles, which - should be done if you wish to eg subscribe to the contact's - presence. + 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> @@ -194,12 +204,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> In rooms with channel specific handles (ie Channel_Specific_Handles flag is set), this flag indicates that no handle owners are - available, apart from the owner of the SelfHandle. + 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 HandleOwner - property and HandleOwnerChanged signal. + 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> @@ -209,6 +221,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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. + </tp:docstring> + </tp:flag> </tp:flags> <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags" @@ -217,7 +237,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An integer representing the bitwise-OR of flags on this channel. The user interface can use this to present information about which operations are currently valid. Change notification is via - the GroupFlagsChanged signal. + 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 @@ -231,7 +251,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring> - Returns the value of the GroupFlags property. + 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 @@ -273,7 +293,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ the keys of this mapping is not channel-specific in this channel. Handles which are channel-specific, but for which the owner is unknown, MUST appear in this mapping with 0 as owner. Change - notification is via the HandleOwnersChanged signal. + notification is via the + <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal. </tp:docstring> <tp:added version="0.17.6"/> </property> @@ -281,7 +302,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="HandleOwnersChanged" tp:name-for-bindings="Handle_Owners_Changed"> <tp:docstring> - Emitted whenever the HandleOwners property changes. + 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> @@ -298,7 +320,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> The channel-specific handles that were removed from the keys of the HandleOwners property, as a result of the contact leaving this group - in a previous MembersChanged signal + in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal </tp:docstring> </arg> </signal> @@ -351,7 +373,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="out" type="au" tp:type="Contact_Handle[]"/> <tp:docstring> Returns the To_Be_Added handle (only) for each structure in the - LocalPendingMembers property. + <tp: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> @@ -365,7 +387,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ tp:name-for-bindings="Get_Local_Pending_Members_With_Info"> <tp:added version="0.15.0" /> <tp:docstring> - Returns the LocalPendingMembers property. + 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> @@ -382,7 +404,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </li> <li> The reason for the request: one of the values of - ChannelGroupChangeReason + <tp:type>Channel_Group_Change_Reason</tp:type> </li> <li> A string message containing the reason for the request if any (or @@ -403,7 +425,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> An array of structs containing handles representing contacts requesting channel membership and awaiting local approval with - AddMembers. + <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 @@ -423,7 +445,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetMembers" tp:name-for-bindings="Get_Members"> <arg direction="out" type="au" tp:type="Contact_Handle[]"/> <tp:docstring> - Returns the Members property. + 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> @@ -450,7 +472,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Returns an array of handles representing contacts who have been invited to the channel and are awaiting remote approval. </tp:docstring> - <tp:deprecated version="0.17.6">Use the RemotePendingMembers + <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"/> @@ -460,7 +483,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed"> <tp:docstring> - Emitted whenever the SelfHandle property changes. + 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> @@ -477,9 +501,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> The handle for the user on this channel (which can also be a local or remote pending member), or 0 if the user is not a member at - all (which is likely to be the case, for instance, on ContactList - channels). Note that this is different from the connection - GetSelfHandle on some protocols, so the value of this handle should + 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, @@ -490,7 +517,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> <arg direction="out" type="u" tp:type="Contact_Handle"/> <tp:docstring> - Returns the value of the SelfHandle property. + 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, @@ -513,7 +541,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring> - Emitted when the flags as returned by GetGroupFlags are changed. + 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> @@ -569,9 +598,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> The change is because a contact's unique identifier changed. There must be exactly one handle in the removed set and exactly - one handle in one of the added sets. The Renamed signal on the - Renaming interface will have been emitted for the same handles, - shortly before this MembersChanged signal is emitted. + 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. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Permission_Denied" value="10"> @@ -590,7 +623,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p> If members are added with this reason code, the change is because unconnected parts of the group have rejoined. If this channel - carries messages (e.g. Text or Tubes channels) applications must + 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 @@ -640,8 +677,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason"> <tp:docstring> - A reason for the change: one of the values of - ChannelGroupChangeReason + A reason for the change </tp:docstring> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -651,8 +687,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ which may be displayed to the user if desired.</p> <p>All channel-specific handles that are mentioned in this signal - MUST be represented in the value of the HandleOwners property. - In practice, this will mean that HandleOwnersChanged is + 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 @@ -660,6 +698,90 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> + <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>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> + </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> @@ -678,7 +800,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ with the request, which will be sent to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE, CHANNEL_GROUP_FLAG_MESSAGE_REJECT and - CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this + CHANNEL_GROUP_FLAG_MESSAGE_RESCIND + <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this message should be provided. </tp:docstring> <tp:possible-errors> @@ -705,12 +828,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="in" name="Reason" type="u" tp:type="Channel_Group_Change_Reason"> <tp:docstring> - A reason for the change: one of the values of - ChannelGroupChangeReason + A reason for the change </tp:docstring> </arg> <tp:docstring> - As RemoveMembers, but a reason code may be provided where + 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> @@ -734,17 +857,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ cannot be presumed by the channel's existence (for example, a channel you may request membership of but your request may not be granted).</p> - <p>This interface implements three lists: a list of current members, and two - lists of local pending and remote pending members. Contacts on the remote + <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 MembersChanged signal should be emitted when information + 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>Addition of members to the channel may be requested by using AddMembers. If + <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 @@ -752,7 +884,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ will grant their membership request.</p> <p>Removal of contacts from the channel may be requested by using - RemoveMembers. If a contact is awaiting authorisation on the local pending + <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> diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index 4d3cc4da..835aff92 100644 --- a/spec/Channel_Interface_Hold.xml +++ b/spec/Channel_Interface_Hold.xml @@ -61,7 +61,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Emitted to indicate that the hold state has changed for this channel. This may occur as a consequence of you requesting a change with - RequestHold, or the state changing as a result of a request from + <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a + result of a request from another process. </tp:docstring> @@ -159,7 +160,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>Otherwise, this method SHOULD immediately set the hold state to Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold - (as appropriate), emitting HoldStateChanged if this is a change, + (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 diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml index aa397218..acbe7474 100644 --- a/spec/Channel_Interface_Media_Signalling.xml +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -51,7 +51,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="NewSessionHandler" tp:name-for-bindings="New_Session_Handler"> <arg name="Session_Handler" type="o"> <tp:docstring> - Object path of the new MediaSessionHandler object + 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"> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 7fefabbb..94095353 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -20,10 +20,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> <interface - name="org.freedesktop.Telepathy.Channel.Interface.Messages.DRAFT" - tp:causes-havoc="experimental"> + name="org.freedesktop.Telepathy.Channel.Interface.Messages"> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> - <tp:added version="0.17.5">(draft version, not API-stable)</tp:added> + <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 Text interface to support more general @@ -51,7 +50,9 @@ USA.</p> unfriendly to offer the user controls that may have no effect. </tp:rationale> - <p>This interface also replaces Text.SendError, adding support for + <p>This interface also replaces <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>, + adding support for protocols where the message content is not echoed back to the sender on failure, adding support for receiving positive acknowledgements, and using the Messages queue for state-recovery @@ -59,9 +60,16 @@ USA.</p> currently a process handling them).</p> <p>If this interface is present, clients that support it SHOULD - listen for the MessageSent and MessageReceived signals, and - ignore the Sent, SendError and Received signal on the Text interface - (which are guaranteed to duplicate signals from this interface).</p> + 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> </tp:docstring> <property name="SupportedContentTypes" type="as" access="read" @@ -150,7 +158,8 @@ USA.</p> <tp:flag suffix="One_Attachment" value="1"> <tp:docstring> - SendMessage will accept messages containing a textual message body, + <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 @@ -245,7 +254,8 @@ USA.</p> <dt>message-sent (t - <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</dd> + reasonable approximation is available; SHOULD always be present + on outgoing messages.</dd> <dt>message-received (t - <tp:type>Unix_Timestamp64</tp:type>)</dt> <dd>The time the message was received locally. SHOULD always @@ -521,6 +531,21 @@ USA.</p> Channel_Text_Send_Error_Unknown. </dd> + <dt>delivery-dbus-error (s - DBus_Error_Name)</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} - Message_Part[])</dt> <dd> <p>The message content, as defined by the Messages interface. @@ -704,8 +729,11 @@ USA.</p> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Submit a message to the server for sending. If this method returns successfully, the message has been submitted - to the server and the MessageSent signal is emitted. A corresponding - Sent signal on the Text interface MUST also be emitted.</p> + 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> @@ -785,7 +813,9 @@ USA.</p> <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 Sent signal on the + 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.</p> <tp:rationale> @@ -816,6 +846,14 @@ USA.</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="Sent_Message_Token"> <tp:docstring> An opaque token used to match any incoming delivery or failure @@ -829,9 +867,13 @@ USA.</p> tp:type="Message_Part[][]" tp:name-for-bindings="Pending_Messages"> <tp:docstring> A list of incoming messages that have neither been acknowledged nor - rejected. This list is a superset of the one returned by - ListPendingMessages on the Text interface; its items can be removed - using AcknowledgePendingMessages on that interface. + 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>. </tp:docstring> </property> @@ -839,8 +881,8 @@ USA.</p> tp:name-for-bindings="Pending_Messages_Removed"> <tp:docstring> The messages with the given IDs have been removed from the - PendingMessages list. Clients SHOULD NOT attempt to acknowledge - those messages. + <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 @@ -913,7 +955,9 @@ USA.</p> <tp:docstring> Signals that a message has been received and added to the pending messages queue. This MUST be emitted exactly once per emission of the - Received signal on the Text interface. + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> + signal on the Text interface. <tp:rationale> The double signal-emission provides compatibility with older @@ -930,7 +974,8 @@ USA.</p> </arg> </signal> - <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" type="u"> + <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> @@ -982,6 +1027,20 @@ USA.</p> </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:enum> <tp:flags name="Delivery_Reporting_Support_Flags" diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml index adcd0f84..bfc617ab 100644 --- a/spec/Channel_Interface_Password.xml +++ b/spec/Channel_Interface_Password.xml @@ -25,8 +25,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:flags name="Channel_Password_Flags" value-prefix="Channel_Password_Flag" type="u"> <tp:flag suffix="Provide" value="8"> <tp:docstring> - The ProvidePassword method must be called now for the user to join - the channel + 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> @@ -60,7 +60,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </arg> <tp:docstring> - Emitted when the flags as returned by GetPasswordFlags are changed. + 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> @@ -89,7 +90,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. to provide before being able to join, or may be able to view or change once they have joined the channel.</p> - <p>The GetPasswordFlags method and the associated PasswordFlagsChanged + <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> diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml new file mode 100644 index 00000000..8e1ffab3 --- /dev/null +++ b/spec/Channel_Interface_Tube.xml @@ -0,0 +1,127 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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.DRAFT" + tp:causes-havoc="experimental"> + <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 handles of type + HANDLE_TYPE_CONTACT (for 1-1 communication) or of type + HANDLE_TYPE_ROOM (to communicate with others in the room + simultaneously).</p> + </tp:docstring> + + <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" + access="readwrite" 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. Connection managers + must support the value being a string (D-Bus type 's'), array of bytes + (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus + type 'i') and boolean (D-Bus type 'b').</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>Example of valid parameters for 'smb' Server Message Block over + TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS + SRV (RFC 2782) Service Types + http://www.dns-sd.org/ServiceTypes.html</a>): + <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p> + <p>When requesting a channel with + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, + this property MAY be included in the request. If it is not included in + the request, the connection manager MUST consider the property to be + empty. This property MAY be changed after the channel creation when + the tube is in the state Not_Offered. If the tube is in another + state, changing this property MUST fail without side effects.</p> + </tp:docstring> + </property> + + <property name="Status" type="u" tp:type="Tube_Channel_State" access="read" + tp:name-for-bindings="Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Status of the tube in this channel.</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: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 to offer the tube depend 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. + </tp:docstring> + <arg name="state" type="u" tp:type="Tube_Channel_State"> + <tp:docstring> + The new state of the tube; see the Tube_Channel_State enumeration. + </tp:docstring> + </arg> + </signal> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 08b291f7..956eee1c 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -39,6 +39,15 @@ </tp:rationale> </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="t" tp:type="Unix_Timestamp64" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -127,12 +136,14 @@ 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 Close; otherwise, - the channel dispatcher will ignore it. In either case, + 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 Failed is emitted in response to this method, the error SHOULD be + <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to + this method, the error SHOULD be <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> <p>If the channel has already been dispatched to a handler, then @@ -150,8 +161,11 @@ <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 CreateChannel, or an error generated - to represent failure to establish the Connection.</p> + 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> diff --git a/spec/Channel_Type_Contact_List.xml b/spec/Channel_Type_Contact_List.xml index 9c093514..5a0d3336 100644 --- a/spec/Channel_Type_Contact_List.xml +++ b/spec/Channel_Type_Contact_List.xml @@ -25,7 +25,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for representing a list of people on the server which is not used for communication. This is intended for use with the interface - Channel.Interface.Group for managing buddy lists and privacy lists + <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> @@ -37,8 +39,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ of this channel type should be created by the connection manager at connection time if the list exists on the server, or may be requested by using the appropriate handle. These handles can be obtained using - RequestHandles with a handle type of HANDLE_TYPE_LIST and - one of the following identifiers:</p> + <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> @@ -52,10 +56,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </ul> <p>A contact can be in several server-defined lists. All lists are optional - to implement. If RequestHandles or RequestChannel 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> + 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 @@ -76,11 +83,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>For user-defined contact groups, instances of this channel type should be created by the connection manager at connection time for each group that exists on the server. New, empty groups can be created by calling - RequestHandles with a handle type of - HANDLE_TYPE_GROUP and with the name set to the - human-readable UTF-8 name of the group.</p> + <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 closing the channel, but only if + <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> diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml new file mode 100644 index 00000000..a3b98d7e --- /dev/null +++ b/spec/Channel_Type_DBus_Tube.xml @@ -0,0 +1,183 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/> + <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="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube"> + <tp:docstring> + Offers a D-Bus tube providing the service specified. + </tp:docstring> + <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="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_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="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="GetDBusTubeAddress" + tp:name-for-bindings="Get_DBus_Tube_Address"> + <tp:docstring> + Return a string describing the address of the private bus. + </tp:docstring> + <arg direction="out" type="s"> + <tp:docstring> + The bus address. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The tube is not a D-Bus tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This tube is not in the "open" state. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_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="out" type="a(us)" tp:type="DBus_Tube_Member[]"> + <tp:docstring> + An array of structures, each containing a contact handle and a D-Bus + bus name. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The tube is not a multi-user D-Bus tube. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This tube is not in the "open" state. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="DBusNamesChanged" tp: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. + </tp:docstring> + <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> + + <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 + com.example.ServiceName.</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> + + </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 00000000..a2432f4b --- /dev/null +++ b/spec/Channel_Type_File_Transfer.xml @@ -0,0 +1,513 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright (C) 2008 Collabora Limited + </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.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <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> + </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> + </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="t" 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 index 6636ce0d..d2403bb6 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -65,28 +65,46 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when information about rooms on the server becomes available. The array contains the room handle (as can be passed to the - RequestChannel method with HANDLE_TYPE_ROOM), the channel + <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>s:handle-name</dt><dd>The string name of the room handle (as would be returned by InspectHandles)</dd> - <dt>s:name</dt><dd>The human-readable name of the room if different from the handle</dd> - <dt>s:description</dt><dd>A description of the room's overall purpose</dd> - <dt>s:subject</dt><dd>The current subject of conversation in the room</dd> - <dt>u:members</dt><dd>The number of members of the room</dd> - <dt>b:password</dt><dd>True if the room requires a password to enter</dd> - <dt>b:invite-only</dt><dd>True if you cannot join the room, but must be invited</dd> + <dt>handle-name (s)</dt> + <dd>The string name of the room handle (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</dd> + + <dt>members (u)</dt> + <dd>The number of members of 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> </dl> </tp:docstring> </signal> <method name="ListRooms" tp:name-for-bindings="List_Rooms"> <tp:docstring> - Request the list of rooms from the server. The ListingRooms signal - should be emitted when this request is being processed, GotRooms when - any room information is received, and ListingRooms when the request - is complete. + 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"/> @@ -98,7 +116,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 ListingRooms signal should be emitted when the listing stops. + 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"> @@ -112,16 +131,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for listing named channels available on the server. Once the - ListRooms method is called, it emits signals for rooms present on the - server, until you Close this channel. In some cases, it may not be possible + <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 ListingRooms - signal, or GetListingRooms method, can be used to check this.</p> + 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> diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml new file mode 100644 index 00000000..4a43a007 --- /dev/null +++ b/spec/Channel_Type_Stream_Tube.xml @@ -0,0 +1,198 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/> + <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>OfferStreamTube</tp:member-ref> method. When a + recipient accepts a stream tube using the + <tp:member-ref>AcceptStreamTube</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="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="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> + <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="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="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 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="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="handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the participant who opened the new connection + </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> + + </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 index aebc131b..f4615ab6 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -62,15 +62,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:flag suffix="Local_Send" value="1"> <tp:docstring> The local user has been asked to send media by the remote user. - Call RequestStreamDirection to indicate whether or not this is - acceptable. + 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 StreamDirectionChanged signal will be emitted when the remote - user accepts or rejects this change. + 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> @@ -112,7 +113,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 ListStreams) + An array of stream identifiers (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) </tp:docstring> </arg> <tp:docstring> @@ -129,7 +131,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ tp:name-for-bindings="Request_Stream_Direction"> <arg direction="in" name="Stream_ID" type="u"> <tp:docstring> - The stream identifier (as defined in ListStreams) + 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"> @@ -144,12 +147,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ sent to you.</p> <p>Depending on the protocol, streams which are no longer sending in - either direction should be removed and a StreamRemoved signal emitted. + 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 StreamDirectionChanged signal, and the signal + 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> @@ -196,16 +202,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ indicate to the peer that you would like to receive media, so a send-only stream will be created initially. In the cases where the stream requires remote agreement (eg you wish to receive media from - them), the StreamDirectionChanged signal will be emitted with the + 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> </tp:docstring> <tp:changed version="0.17.2"> <p>It is valid to use a handle which is neither - a current nor pending member in this channel's Group interface. If + 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 CallState interface, if + 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> @@ -223,7 +234,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> <arg name="Stream_ID" type="u"> <tp:docstring> - The stream identifier (as defined in ListStreams) + 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"> @@ -246,7 +258,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ tp:name-for-bindings="Stream_Direction_Changed"> <arg name="Stream_ID" type="u"> <tp:docstring> - The stream identifier (as defined in ListStreams) + 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"> @@ -262,7 +274,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Emitted when the direction or pending flags of a stream are changed. If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has - requested that we begin sending on this stream. RequestStreamDirection + requested that we begin sending on this stream. + <tp:member-ref>RequestStreamDirection</tp:member-ref> should be called to indicate whether or not this change is acceptable. </tp:docstring> </signal> @@ -270,7 +283,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="StreamError" tp:name-for-bindings="Stream_Error"> <arg name="Stream_ID" type="u"> <tp:docstring> - The stream identifier (as defined in ListStreams) + 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"> @@ -291,7 +305,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 ListStreams) + stream_id - the stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) </tp:docstring> </arg> <tp:docstring> @@ -303,7 +318,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ tp:name-for-bindings="Stream_State_Changed"> <arg name="Stream_ID" type="u"> <tp:docstring> - The stream identifier (as defined in ListStreams) + 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"> @@ -322,22 +338,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ signals to indicate when streams have been added, removed and changed status.</p> - <p>Channels of this type are expected to provide the Group interface - and be "anonymous" (have no associated handle). To make a media call - to a contact, clients should request a new, empty streamed media - channel, then call AddMembers to add the contact to the channel. - The local user should be in the group's members, while the contact - should be absent from the channel until a call is made, appear in - "remote pending" from when the call is attempted until the call is - accepted, then move to the group's members.</p> + <p>To make a media call to a contact, clients should call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</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>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact, and one of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + (which should yield a channel with the local user in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">Members</tp:dbus-ref>, + and the remote contact as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + but not in any group members list), then call + <tp:member-ref>RequestStreams</tp:member-ref> to initiate the call (at + which point the contact should appear in the channel's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemotePendingMembers</tp:dbus-ref>).</p> - <p>Similarly, incoming calls should be signalled as having handle type 0 - and handle 0. The remote contact should be in the group's members, - with the local user in the "local pending" members; to accept the - call, AddMembers can be used to move the local user to the - group's members.</p> + <p>Incoming calls should be signalled as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + set to the remote contact, with the local user in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref>; + to accept the call, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> + can be used to move the local user to the group's members.</p> - <p>In general this should be used in conjunction with the MediaSignalling + <p>In the past, several other patterns have been used to place outgoing + calls; see + <tt>http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels</tt> + for the details.</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 @@ -349,7 +387,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u"> <tp:docstring> The channel-type-specific capability flags used for - Channel.Type.StreamedMedia in the Connection.Interface.Capabilities + Channel.Type.StreamedMedia in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref> interface. </tp:docstring> <tp:flag suffix="Audio" value="1"> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 8340305f..f32382d2 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -33,9 +33,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> <tp:docstring>A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) - representing a pending text message, as returned by ListPendingMessages - on the Text channel type. The arguments of the Received signal - also match this struct's signature.</tp:docstring> + 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"/> @@ -81,8 +82,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ tp:name-for-bindings="List_Pending_Messages"> <arg direction="in" name="Clear" type="b"> <tp:docstring> - If true, behave as if AcknowledgePendingMessages had also been - called. + If true, behave as if + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also + been called. </tp:docstring> <tp:deprecated since="0.17.3"> Setting this to true is NOT RECOMMENDED for clients that @@ -153,7 +155,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ and text has been received on this channel. Applications that catch this signal and reliably inform the user of the message should acknowledge that they have dealt with the message with the - AcknowledgePendingMessage method. + <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method. </tp:docstring> </signal> @@ -170,16 +172,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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 Sent - signal will be emitted. If the message cannot be submitted for - delivery, the method returns an error and no signal is emitted.</p> + 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 Messages interface, that - "SHOULD" becomes a "MUST".</p> + <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> @@ -250,8 +254,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ will be one of the values from ChannelTextSendError.</p> <p>This signal should only be emitted for messages for which - Sent has already been emitted and Send has already returned - success.</p> + <tp: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 @@ -276,7 +280,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 Send. + to <tp:member-ref>Send</tp:member-ref>. </tp:docstring> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -337,7 +341,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The incoming message contained non-text content which cannot be represented by this interface, but has been signalled - in the Messages interface.</p> + 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 @@ -367,7 +373,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 Connection, but had not been acknowledged + 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> @@ -463,42 +471,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ formatted text) should also have this type.</p> <p>When a message is received, an identifier is assigned and a - Received signal emitted, and the message placed in a pending queue - which can be inspected with ListPendingMessages. A client which has + <tp:member-ref>Received</tp:member-ref> signal emitted, and the message + placed in a pending queue which can be inspected with + <tp:member-ref>ListPendingMessages</tp:member-ref>. A client which has handled the message by showing it to the user (or equivalent) should - acknowledge the receipt using the AcknowledgePendingMessage method, + acknowledge the receipt 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>Each message has an associated 'type' value, which should be one - of the values allowed by ChannelTextMessageType.</p> + of the values allowed by + <tp:type>Channel_Text_Message_Type</tp:type>.</p> <p>Each message also has a flags value, which is a bitwise OR of the - flags given in ChannelTextMessageFlags.</p> + flags given in <tp:type>Channel_Text_Message_Flags</tp:type>.</p> - <p>Sending messages can be requested using the Send method, which will - return successfully and emit the Sent signal when the message has - been delivered to the server, or return an error with no signal - emission if there is a failure. If a message is sent but delivery - of the message later fails, this is indicated with the SendError - signal.</p> + <p>Sending messages can be requested using the + <tp:member-ref>Send</tp:member-ref> method, which will return + successfully and emit the <tp:member-ref>Sent</tp:member-ref> signal + when the message has been delivered to the server, or return an error + with no signal emission if there is a failure. If a message is sent but + delivery of the message later fails, this is indicated with the + <tp:member-ref>SendError</tp:member-ref> signal.</p> <p>On protocols where additional contacts cannot be invited into a one-to-one chat, or where a one-to-one chat is just a series of individual personal messages rather than being represented by some object on the server (i.e. most protocols), one-to-one chats should be - represented by a Text channel with handle type CONTACT.</p> + represented by a Text channel with <tp:type>Handle_Type</tp:type> + CONTACT.</p> <p>Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text - channels with handle type ROOM and the Group interface; they should - usually also have the Properties interface.</p> + channels with <tp:type>Handle_Type</tp:type> ROOM and the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + interface; they should usually also have the Properties interface.</p> <p>Unnamed, transient chat rooms defined only by their members (e.g. on MSN) are expected to be represented by Text channels with handle type - 0, handle 0, the Group interface, and optionally the Properties - interface.</p> + 0, handle 0, the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + interface, and optionally the Properties interface.</p> <p>On protocols where a conversation with a user is actually just a nameless chat room starting with exactly two members, to which diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml index 68df224a..f28f9b6b 100644 --- a/spec/Channel_Type_Tubes.xml +++ b/spec/Channel_Type_Tubes.xml @@ -116,48 +116,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enum name="Tube_Type" type="u"> <tp:enumvalue suffix="DBus" value="0"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An ordered reliable transport, for transporting D-Bus - traffic.</p> - - <p>For each D-Bus tube, the connection manager listens on a D-Bus - server address, as detailed in the D-Bus specification. On this - address, it emulates a bus upon which each tube participant appears - as an endpoint.</p> - - <p>The objects and interfaces which are expected to exist on the - emulated bus depend on the well-known name; typically, either the - participant who initiated the tube is expected to export the same - objects/interfaces that would be exported by a service of that name - on a bus, or all participants are expected to export those - objects/interfaces.</p> - - <p>In a multi-user context (Handle_Type_Room) the tube behaves - like the D-Bus bus daemon, so participants can send each other - private messages, or can send broadcast messages which are - received by everyone in the tube (including themselves). - Each participant has a D-Bus unique name; connection managers - must prevent participants from sending messages with the wrong - sender unique name, and should attempt to avoid participants - receiving messages not intended for them.</p> - - <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like - a peer-to-peer D-Bus connection - arbitrary D-Bus messages with - any sender and/or destination can be sent by each participant, - and each participant receives all messages sent by the other - participant.</p> + <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>A transport for ordered, reliable data transfer, similar to - SOCK_STREAM sockets.</p> - - <p>When accepting a Stream Unix tube, a new listening local socket is - created. Each time the client connects to this socket, the - connection manager of the initiator of the tube opens a new - connection to its local socket. Both sides can then use this pair - of sockets to communicate together.</p> + <p>The tube is stream tube as described by the + org.freedesktop.Telepathy.Channel.Type.StreamTube interface.</p> </tp:docstring> </tp:enumvalue> </tp:enum> @@ -183,14 +150,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enum name="Socket_Address_Type" type="u"> <tp:enumvalue suffix="Unix" value="0"> <tp:docstring> - A Unix socket. The variant contains a byte-array, signature 'ay', + 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 variant contains a byte-array, + 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> @@ -198,7 +165,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="IPv4" value="2"> <tp:docstring> - An IPv4 socket. The variant contains a Socket_Address_IPv4, + 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 @@ -208,7 +175,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="IPv6" value="3"> <tp:docstring> - An IPv6 socket. The variant contains a Socket_Address_IPv6, + 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 diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 8793f3ec..59c253b2 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -36,7 +36,7 @@ = 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 ChannelHandlers whose + 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 @@ -191,7 +191,15 @@ <tp:docstring> The <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> - object. + object, which MUST have been returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">CreateChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">EnsureChannel</tp:dbus-ref> + before this method is called. + + <tp:rationale> + See those methods for the rationale of this ordering. + </tp:rationale> </tp:docstring> </arg> @@ -203,7 +211,10 @@ values could subsequently change. It SHOULD include as many properties as possible, given that constraint.</p> - <p>In particular, the properties Requests and UserActionTimestamp + <p>In particular, the properties <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">Requests</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> MUST be included.</p> </tp:docstring> </arg> diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 89709e2a..40c71e73 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -198,17 +198,27 @@ org.freedesktop.Telepathy.Channel.Requested b=true <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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.</p> + <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="DispatchOperation" type="o" direction="in"> + <tp:docstring> + The path to the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref> + for these channels, or the special value '/' if there is no + ChannelDispatchOperation (because the channels were requested, not incoming). <tp:rationale> - <p>The ChannelDispatchOperation is <em>not</em> supplied: for - requests, there isn't one, and for incoming channels, it hasn't - been created yet.</p> + This allows an Observer to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref> + a set of channels without having to match up calls to this method + with calls to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>. </tp:rationale> </tp:docstring> </arg> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index ee14fa70..652ed01a 100644 --- a/spec/Connection_Interface_Aliasing.xml +++ b/spec/Connection_Interface_Aliasing.xml @@ -29,8 +29,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:mapping> <tp:struct name="Alias_Pair" array-name="Alias_Pair_List"> - <tp:docstring>A pair (contact handle, alias) as seen in the AliasesChanged - signal.</tp:docstring> + <tp: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> @@ -135,10 +137,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Request that the alias of the given contact be changed. Success will be - indicated by emitting an AliasesChanged signal. On connections where the - CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only - ever succeed if the contact is the user's own handle (as returned by - GetSelfHandle on the Connection interface). + 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"/> @@ -155,9 +158,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ alias is changed or first discovered.</p> <p>On connections where the user is allowed to set aliases for contacts and - store them on the server, the GetAliasFlags method will have the - CONNECTION_ALIAS_FLAG_USER_SET flag set, and the SetAliases method - may be called on contact handles other than the user themselves.</p> + 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> diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml index 76b85f3b..6bd0f36e 100644 --- a/spec/Connection_Interface_Avatars.xml +++ b/spec/Connection_Interface_Avatars.xml @@ -21,11 +21,60 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:simple-type name="Avatar_Token" type="s"> + <tp: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" name="Token"/> + <tp:member type="s" tp:type="Avatar_Token" name="Token"/> </tp:mapping> <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated"> @@ -34,7 +83,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An integer handle for the contact whose avatar has changed </tp:docstring> </arg> - <arg name="New_Avatar_Token" type="s"> + <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s"> <tp:docstring> Unique token for their new avatar </tp:docstring> @@ -43,16 +92,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when the avatar for a contact has been updated, or first discovered on this connection. If the token differs from the token associated with the client's cached avatar for this contact, the new - avatar should be requested with RequestAvatars. + 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" type="s"> + <arg name="Token" tp:type="Avatar_Token" type="s"> <tp:docstring> The token corresponding to the avatar </tp:docstring> @@ -72,6 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when the avatar for a contact has been retrieved. </tp:docstring> </signal> + <method name="GetAvatarRequirements" tp:name-for-bindings="Get_Avatar_Requirements"> <arg direction="out" type="as"> @@ -114,13 +166,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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"> + <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 @@ -130,7 +183,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Get the unique tokens for all of the given contacts' avatars. Using this method in new Telepathy clients is deprecated; use - GetKnownAvatarTokens instead. + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead. </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -140,6 +193,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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[]"> @@ -147,7 +201,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of handles representing contacts </tp:docstring> </arg> - <arg direction="out" type="a{us}" tp:type="Avatar_Token_Map"> + <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. @@ -172,6 +226,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> @@ -205,6 +260,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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[]"> @@ -213,17 +269,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring> - Request avatars for a number of contacts. The AvatarRetrieved signal - is emitted for each avatar retrieved. If the handles are valid but - retrieving an avatar fails (for any reason, including the contact not - having an avatar) the AvatarRetrieved signal is not emitted for that - contact. + 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> @@ -235,14 +292,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A string representing the image MIME type </tp:docstring> </arg> - <arg direction="out" type="s"> + <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 GetAvatarRequirements. + 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"/> @@ -252,6 +310,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> @@ -262,32 +321,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> </tp:possible-errors> </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for requesting avatars for contacts on a given connection, receiving notification when avatars are changed, and publishing your own avatar.</p> - <p>Avatars are identified by a unique (per contact) token which represents a - hash or timestamp (depending on the protocol) of the contacts' avatar data. + <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 GetKnownAvatarTokens to request the tokens for the + <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 RequestAvatars for the contacts. - Clients should bind to the AvatarChanged signal and request a new copy of + 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 SetAvatar to provide an image - which meets the requirements returned by the GetAvatarRequirements + <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 GetKnownAvatarTokens; if the self handle is not in the + 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 @@ -295,8 +364,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 ClearAvatar method. This method can safely be used - even if there is no avatar for this connection.</p> + 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> diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index d5779347..7d0c14a9 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -42,7 +42,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>This interface also provides for user interfaces notifying the connection manager of what capabilities to advertise for the user. This - is done by using the AdvertiseCapabilities method, and deals with the + 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> @@ -64,8 +66,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ value-prefix="Connection_Capability_Flag" type="u"> <tp:flag suffix="Create" value="1"> <tp:docstring> - The given channel type and handle can be given to RequestChannel to - create a new channel of this type. + 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"> @@ -77,7 +80,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:struct name="Capability_Pair" array-name="Capability_Pair_List"> <tp:docstring>A pair (channel type, type-specific flags) as passed to - AdvertiseCapabilities on the Capabilities interface.</tp:docstring> + <tp:member-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> @@ -85,8 +89,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:struct name="Contact_Capability" array-name="Contact_Capability_List"> <tp:docstring>A struct (contact handle, channel type, generic flags, type-specific flags) representing a capability posessed by a contact, - as returned by GetCapabilities on the Capabilities - interface.</tp:docstring> + 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" @@ -98,7 +102,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>A struct (contact handle, channel type, old generic flags, new generic flags, old type-specific flags, new type-specific flags) representing a change to one of a contact's capabilities, as seen in the - CapabilitiesChanged signal on the Capabilities interface.</tp:docstring> + <tp:member-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" @@ -145,9 +150,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ specific flags, the connection manager should simply add the new flags to the set of advertised capabilities.</p> - <p>Upon a successful invocation of this method, the CapabilitiesChanged - signal will be emitted for the user's own handle (as returned by - GetSelfHandle) by the connection manager to indicate the changes + <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 diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml new file mode 100644 index 00000000..13efba66 --- /dev/null +++ b/spec/Connection_Interface_Contact_Capabilities.xml @@ -0,0 +1,165 @@ +<?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.DRAFT"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.16">(as a draft)</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>SetSelfCapabilities</tp:member-ref> method, and deals + with channel property values pertaining to them which are implemented + by available client processes.</p> + + </tp:docstring> + + <method name="SetSelfCapabilities" + tp:name-for-bindings="Set_Self_Capabilities"> + <arg direction="in" name="caps" type="aa{sv}" + tp:type="String_Variant_Map[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of channel classes to replace to the list of what the + connection can handle. If you include optional properties, they + may not get advertised. The given properties are matched to the + mandatory properties. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used by user interfaces to indicate which channel classes they are + able to handle on this connection. It replaces the previous advertised + channel classes by the set given as parameter.</p> + + <p>If a channel class is unknown by the connection manager, it is just + ignored. No error are returned in this case, and other known channel + class are added.</p> + + <p>Upon a successful invocation of this method, the + <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal + will only be emitted for the user's own + handle (as returned by GetSelfHandle) by the connection manager if, in + the given protocol, the given 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> + + </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> + + <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> + <!-- There was a bug in dbus-glib that prevent to use the right type: + Instead of a{ua(a{sv}as)}, we used a(ua{sv}as) as a workaround. + See http://bugs.freedesktop.org/show_bug.cgi?id=17329 + Now there is a fix, so we don't use the workaround anymore. + --> + <arg direction="out" type="a{ua(a{sv}as)}" + tp:type="Contact_Capabilities_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structures containing: + <ul> + <li>a dictionary mapping the channel properties to their values.</li> + <li>an array of additional allowed properties</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of enhanced capabilities for the given contact handles. + </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> + The contact capabilities. + </tp:docstring> + </tp:member> + </tp:mapping> + + </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 index 590c3395..e04ea5f2 100644 --- a/spec/Connection_Interface_Contacts.xml +++ b/spec/Connection_Interface_Contacts.xml @@ -48,7 +48,7 @@ Aliasing interface was requested) </dd> <dt>org.freedesktop.Telepathy.Connection.Interface.Avatars/token - (type s)</dt> + (type s, <tp:type>Avatar_Token</tp:type>)</dt> <dd>The same string that would be returned by <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref> (omitted from the result if the contact's avatar token is not known, @@ -75,6 +75,14 @@ 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.</dd> + <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps + (type a{ua(a{sv}as)}, + <tp:type>Contact_Capabilities_Map</tp:type>)</dt> + <dd>The same structs that would be returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">GetContactCapabilities</tp:dbus-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.</dd> </dl> </tp:docstring> @@ -110,7 +118,8 @@ </tp:mapping> <tp:mapping name="Contact_Attributes_Map"> - <tp:docstring>Mapping returned by GetContactAttributes, representing a + <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"> @@ -177,11 +186,14 @@ 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 AliasesChanged).</p> + 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 Aliasing attributes. + in response to a request for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref> + attributes. </tp:rationale> </tp:docstring> </arg> diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml index 58ad34e6..cfcb856c 100644 --- a/spec/Connection_Interface_Presence.xml +++ b/spec/Connection_Interface_Presence.xml @@ -29,9 +29,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <!-- We hope to simplify these eventually --> <tp:mapping name="Multiple_Status_Map"> - <tp:docstring>Mapping used in Last_Activity_And_Statuses and passed to - SetStatus, representing a collection of statuses. Use of this mapping - with more than one member is deprecated.</tp:docstring> + <tp: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> @@ -44,9 +46,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ name="Statuses"/> </tp:struct> <tp:mapping name="Contact_Presences"> - <tp:docstring>Mapping returned by GetPresence and signalled by - PresenceUpdate, where the keys are contacts and the values represent - their presences.</tp:docstring> + <tp: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"/> @@ -76,8 +79,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Request that a single presence status is published for the user, along - with any desired parameters. Changes will be indicated by PresenceUpdate - signals being emitted. + 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"/> @@ -91,8 +94,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Request that all of a user's presence statuses be removed. Be aware that this request may simply result in the statuses being replaced by a - default available status. Changes will be indicated by PresenceUpdate - signals being emitted. + 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"/> @@ -109,16 +112,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences"> <tp:docstring> - Presence information in the same format as for the PresenceUpdate - signal + 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 PresenceUpdate for the given - contacts. Data is returned in the same structure as the PresenceUpdate - signal. Using this method in favour of RequestPresence has the - advantage that it will not wake up each client connected to the - PresenceUpdate signal. + 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"/> @@ -133,8 +137,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> + <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> @@ -161,8 +167,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has - been changed, or when the presence requested by RequestPresence is available. - + 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"> @@ -173,9 +179,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Request that the given presence status is no longer published for the - user. Changes will be indicated by PresenceUpdate signals being - emitted. As with ClearStatus, removing a status may actually result in - it being replaced by a default available status. + 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"/> @@ -193,11 +200,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring> - Request the presence for contacts on this connection. A PresenceUpdate + 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' Channel.Type.ContactList, and on some protocols presence - information may not be available unless a subscription exists. + '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"/> @@ -241,7 +250,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Request that the user's presence be changed to the given statuses and - desired parameters. Changes will be reflected by PresenceUpdate + desired parameters. Changes will be reflected by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. On certain protocols, this method may be called on a newly-created connection which is still in the DISCONNECTED state, and will sign on with the requested status. @@ -260,22 +270,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface will become deprecated in future versions. New - client implementations MAY use - org.freedesktop.Telepathy.Connection.Interface.SimplePresence - instead; new connection managers SHOULD implement both - Presence and SimplePresence.</p> + client implementations MAY use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + instead; new connection managers SHOULD implement both Presence and + SimplePresence.</p> <p>This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts. Telepathy's definition of presence is based on that used by - <a href="http://www.galago-project.org/">the Galago - project</a>.</p> + <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 GetStatuses - method.</p> + per connection, and a list of them can be obtained with the + <tp:member-ref>GetStatuses</tp:member-ref> method.</p> <p>Each status has an arbitrary string identifier which should have an agreed meaning between the connection manager and any client which is expected to @@ -301,9 +310,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </ul> <p>As well as these well-known status identifiers, every status also has a - numerical type value chosen from ConnectionPresenceType which can be - used by the client to classify even unknown statuses into different - fundamental types.</p> + 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 @@ -315,25 +324,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ that the string (s) argument 'message' be interpreted as an optional message which can be associated with a presence status.</p> - <p>If the connection has a 'subscribe' contact list, PresenceUpdate signals - should be emitted to indicate changes of contacts on this list, and should - also be emitted for changes in your own presence. Depending on the - protocol, the signal may also be emitted for others such as people with - whom you are communicating, and any user interface should be updated - accordingly.</p> + <p>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, RequestPresence may only succeed on contacts on your - 'subscribe' list, and other contacts will cause a PermissionDenied error. - On protocols where there is no 'subscribe' list, and RequestPresence - succeeds, a client may poll the server intermittently to update any display - of presence information.</p> + <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> + <tp:enum name="Connection_Presence_Type" type="u"> <tp:enumvalue suffix="Unset" value="0"> <tp:docstring> An invalid presence type used as a null value. This value MUST NOT - appear in the result of GetStatuses, or in the Statuses property - of the SimplePresence interface. + appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>, + or in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref> + property of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + interface. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Offline" value="1"> diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml index 99811846..c81d7ed4 100644 --- a/spec/Connection_Interface_Renaming.xml +++ b/spec/Connection_Interface_Renaming.xml @@ -50,8 +50,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>If the contact's old handle is in any of the member lists of a channel which has the groups interface, it will be removed from the channel and the new handle will be added. The resulting - MembersChanged signal must be emitted <em>after</em> the Renamed - signal; the reason should be RENAMED. + <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. @@ -69,8 +72,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the user's own identifier is changed on the server. - If successful, a Renamed signal will be emitted for the current - "self handle" as returned by GetSelfHandle.</p> + 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> diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml index 264a3b5d..f8385341 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -117,7 +117,10 @@ <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. Some properties + <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 @@ -192,7 +195,8 @@ <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 TargetID). + (like <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> @@ -263,7 +267,8 @@ <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 CreateChannel returns a channel + 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> @@ -313,7 +318,8 @@ <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 TargetID). + (like <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> @@ -348,8 +354,9 @@ <tp:rationale> <p>Joining a MUC Tube in XMPP requires joining the corresponding - MUC (chatroom), so a Text channel can be created as a - side-effect.</p> + 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 @@ -396,11 +403,13 @@ <tp:added version="0.17.11">(as stable API)</tp:added> <tp:docstring> Emitted when a channel is closed and hence disappears from the - Channels property. + <tp:member-ref>Channels</tp:member-ref> property. <tp:rationale> - This is redundant with the Close signal on the channel itself, but - it does provide full change notification for the Channels property. + 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> diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml index 92614e0a..16f33865 100644 --- a/spec/Connection_Interface_Simple_Presence.xml +++ b/spec/Connection_Interface_Simple_Presence.xml @@ -211,7 +211,8 @@ </tp:docstring> </arg> <tp:docstring> - Get presence previously emitted by PresencesChanged for the given + 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> @@ -353,7 +354,8 @@ </table> <p>As well as these well-known status identifiers, every status also has - a numerical type value chosen from ConnectionPresenceType which can be + 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> @@ -370,7 +372,8 @@ 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, PresencesChanged + <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 diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index e3cfa8d3..9bbe1b7a 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -138,6 +138,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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"> + This parameter is also a D-Bus property on the resulting <tp:dbus-ref + namespace="org.freedesktop.Telepathy">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. + </tp:docstring> + <tp:added version="0.17.16"/> + </tp:flag> </tp:flags> <method name="GetParameters" tp:name-for-bindings="Get_Parameters"> @@ -153,7 +165,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <tp:docstring> Get a list of the parameters which must or may be provided to the - RequestConnection method when connecting to the given protocol, + <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> @@ -193,7 +206,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring> - Emitted when a new Connection object is created. + Emitted when a new <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object + is created. </tp:docstring> </signal> @@ -206,7 +221,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> <tp:docstring> - A dictionary mapping parameter name to the variant boxed value + A dictionary mapping parameter names to values of the appropriate + type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> + and the above well-known list. </tp:docstring> </arg> <arg direction="out" type="s" tp:type="DBus_Bus_Name"> @@ -232,7 +249,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ method.</p> <p>The parameters which must and may be provided in the parameters - dictionary can be discovered with the GetParameters method. These + 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> @@ -242,42 +260,53 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ following well-known names and types should be used where appropriate:</p> <dl> - <dt>s:account</dt> + <dt>account (s)</dt> <dd>The identifier for the user's account on the server</dd> - <dt>s:server</dt><dd>A fully qualified domain name or numeric IPv4 or IPv6 - address. Using the fully-qualified domain name form is recommended - whenever possible. If this parameter is specified and the account - for that protocol also specifies a server, this parameter should - override that in the user id.</dd> - - <dt>q:port</dt><dd>A TCP or UDP port number. If this parameter is specified - and the account for that protocol also specifies a port, this - parameter should override that in the account.</dd> - - <dt>s:password</dt><dd>A password associated with the account.</dd> - - <dt>b:require-encryption</dt><dd>Require encryption for this connection. A - connection should fail to connect if require-encryption is set - and an encrypted connection is not possible.</dd> - - <dt>b:register</dt><dd>This account should be created on the server if it - does not already exist.</dd> - - <dt>s:ident</dt><dd>The local username to report to the server if - necessary, such as in IRC.</dd> - - <dt>s:fullname</dt><dd>The user's full name if the service requires this - when authenticating or registering.</dd> - - <dt>s:stun-server</dt><dd>The IP address or FQDN of a STUN server to use - for NAT traversal, without any ":port" suffix.</dd> - <dt>q:stun-port</dt><dd>The UDP port number on the stun-server to use for - STUN. Only significant if the stun-server is also supplied.</dd> + <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> </dl> <p>Every successful RequestConnection call will cause the emission of a - NewConnection signal for the same newly created connection. The + <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 @@ -350,8 +379,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> <p>Connection managers' capabilities can be determined dynamically by - calling their ListProtocols method, then for each protocol of interest, - calling GetParameters to discover the required and optional parameters. + 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 @@ -392,6 +423,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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> @@ -402,7 +435,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dl> <dt>s (string)</dt> - <dd>The UTF-8 string</dd> + <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> @@ -414,6 +449,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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, @@ -431,6 +470,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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/all.xml b/spec/all.xml index 7b768235..def46f45 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.14</tp:version> +<tp:version>0.17.16</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -30,6 +30,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Aliasing.xml"/> <xi:include href="Connection_Interface_Avatars.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> +<xi:include href="Connection_Interface_Contact_Capabilities.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> <xi:include href="Connection_Interface_Simple_Presence.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> @@ -45,6 +46,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Type_Room_List.xml"/> <xi:include href="Channel_Type_Text.xml"/> <xi:include href="Channel_Type_Tubes.xml"/> +<xi:include href="Channel_Type_Stream_Tube.xml"/> +<xi:include href="Channel_Type_DBus_Tube.xml"/> +<xi:include href="Channel_Type_File_Transfer.xml"/> <xi:include href="Channel_Interface_Call_Merging.xml"/> <xi:include href="Channel_Interface_Call_State.xml"/> @@ -57,6 +61,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Password.xml"/> <xi:include href="Channel_Interface_Media_Signalling.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> +<xi:include href="Channel_Interface_Tube.xml"/> <xi:include href="Media_Session_Handler.xml"/> <xi:include href="Media_Stream_Handler.xml"/> diff --git a/spec/generic-types.xml b/spec/generic-types.xml index 9d8501de..227fde14 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -83,7 +83,7 @@ </tp:member> </tp:mapping> - <tp:mapping name="String_Variant_Map"> + <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"/> |