[telepathy-glib/master] sync with spec 0.17.25
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Wed May 27 03:13:30 PDT 2009
---
spec/Account.xml | 79 +++++++++++--
spec/Account_Manager.xml | 104 ++++++++++++++++-
spec/Channel_Interface_Tube.xml | 198 +++++++++++++++++++++++++-------
spec/Channel_Type_DBus_Tube.xml | 54 +++++++---
spec/Channel_Type_Stream_Tube.xml | 136 ++++++++++++++++++----
spec/Channel_Type_Tubes.xml | 94 ++--------------
spec/Connection_Interface_Requests.xml | 6 +
spec/Debug.xml | 166 ++++++++++++++++++++++++++
spec/Properties_Interface.xml | 2 +-
spec/all.xml | 6 +-
spec/errors.xml | 18 +++
11 files changed, 675 insertions(+), 188 deletions(-)
create mode 100644 spec/Debug.xml
diff --git a/spec/Account.xml b/spec/Account.xml
index b6a2670..4b112cb 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -282,19 +282,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
<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.
+ <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref>
+ property.</p>
+
+ <p>If any of the changed parameters'
+ <tp:type>Conn_Mgr_Param_Flags</tp:type> include
+ <code>DBus_Property</code>, the change will be applied to the
+ corresponding D-Bus Property on the active
+ <tp:member-ref>Connection</tp:member-ref>, if there is one. Changes to
+ other parameters will not take effect until the next time the account
+ is disconnected and reconnected.</p>
<tp:rationale>
- Migration tools that twiddle the settings of all accounts shouldn't
- cause an automatic disconnect and reconnect, probably. I could be
- persuaded otherwise, though. Or we could add a Reconnect() method.
+ <p>In general, reconnecting is a destructive operation that shouldn't
+ happen as a side-effect. In particular, migration tools that
+ twiddle the settings of all accounts shouldn't cause an automatic
+ disconnect and reconnect.</p>
</tp:rationale>
</tp:docstring>
@@ -303,12 +306,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
existing Connections
</tp:changed>
+ <tp:changed version="0.17.24">
+ return an array of the parameters that won't change until the account
+ is reconnected
+ </tp:changed>
+
<arg name="Set" type="a{sv}" direction="in">
<tp:docstring>
A mapping from parameter names to their values. These parameters
should be stored for future use.
</tp:docstring>
</arg>
+
<arg name="Unset" type="as" direction="in">
<tp:docstring>
A list of the names of parameters to be removed from the set of
@@ -319,6 +328,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</arg>
+ <arg name="Reconnect_Required" type="as" direction="out">
+ <tp:docstring>
+ A list of the names of parameters with changes that will not take
+ effect until the account is reconnected (this may be empty, e.g. if
+ all the parameters are D-Bus properties or parameters for which the
+ account manager has specific support). User interfaces that
+ require "instant apply" semantics MAY call
+ <tp:member-ref>Reconnect</tp:member-ref> in response to receiving
+ a non-empty list.
+ </tp:docstring>
+ </arg>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
@@ -459,6 +480,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
+ <method name="Reconnect" tp:name-for-bindings="Reconnect">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Re-connect this account. If the account is currently disconnected
+ and the requested presence is offline, or if the account
+ is not <tp:member-ref>Enabled</tp:member-ref> or not
+ <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p>
+
+ <p>If the account is disconnected and the requested presence is not
+ offline, this forces an attempt to connect with the requested
+ presence immediately.</p>
+
+ <p>If the account is connecting or connected, this is equivalent to
+ remembering the current value of
+ <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value
+ to (OFFLINE, "offline", ""), waiting for the change to take effect,
+ then setting its value to the value that was previously
+ remembered.</p>
+
+ <tp:rationale>
+ <p>Clients desiring "instant apply" semantics for CM parameters MAY
+ call this method to achieve that.</p>
+ </tp:rationale>
+
+ <p>In particular, if the account's
+ <tp:member-ref>Connection</tp:member-ref> is in the Connecting
+ state, calling this method causes the attempt to connect to be
+ aborted and re-tried.</p>
+
+ <tp:rationale>
+ <p>This is necessary to ensure that the new parameters are
+ picked up.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
<property name="NormalizedName" type="s" access="read"
tp:name-for-bindings="Normalized_Name">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
index 6fb9b08..9b54f5f 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -127,12 +127,78 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
</signal>
+ <property name="SupportedAccountProperties"
+ tp:name-for-bindings="Supported_Account_Properties"
+ type="as" tp:type="DBus_Qualified_Member[]" access="read">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the fully qualified names of properties that can be set
+ via the Properties argument to
+ <tp:member-ref>CreateAccount</tp:member-ref> when an account is
+ created.</p>
+
+ <tp:rationale>
+ <p>Examples of good properties to support here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>.
+ </p>
+
+ <p>Examples of properties that would make no sense here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>.
+ </p>
+ </tp:rationale>
+
+ <p>This property MUST NOT include include the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties, which are set using separate arguments.</p>
+
+ <p>This property MAY include the names of properties that, after
+ account creation, will be read-only: this indicates that the property
+ can be set at account creation but not changed later.</p>
+
+ <tp:rationale>
+ <p>For example, an account manager might support migration tools that
+ use this to preserve the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref>
+ property, even though that property is usually read-only.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
<method name="CreateAccount" tp:name-for-bindings="Create_Account">
<tp:docstring>
Request the creation of a new <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The
account manager SHOULD NOT allow invalid accounts to be created.
</tp:docstring>
+ <tp:changed version="0.17.24">added the Properties argument</tp:changed>
<arg name="Connection_Manager" direction="in" type="s"
tp:type="Connection_Manager_Name">
@@ -152,8 +218,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
property. The account manager SHOULD modify this to make it unique if
an Account already exists with the same display name, for instance by
appending a number or the 'account' parameter. Account manager
- implementations SHOULD accept an empty string but account editing user
- interfaces should avoid passing an empty string for this parameter.
+ implementations SHOULD accept an empty string, but account editing
+ user interfaces should avoid passing an empty string for this
+ parameter.
<tp:rationale>
<p>The account creation UI may ask the user for a name for the new
@@ -176,6 +243,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring>
</arg>
+ <arg name="Properties" direction="in" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The values of any other properties to be set immediately on the
+ new Account.</p>
+
+ <p>Only the properties mentioned in
+ <tp:member-ref>SupportedAccountProperties</tp:member-ref> are
+ acceptable here. In particular, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties are never allowed here, since they are set using the other
+ arguments to this method.</p>
+
+ <p>Account manager implementations SHOULD support creating accounts
+ with an empty value for this argument.</p>
+ </tp:docstring>
+ </arg>
+
<arg name="Account" direction="out" type="o">
<tp:docstring>The new <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring>
@@ -183,12 +270,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
- <tp:docstring>The connection manager is not installed or does not
- implement that protocol.</tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Connection_Manager is not installed or does not
+ implement the given Protocol, or one of the properties in the
+ Properties argument is unsupported.</p>
+ </tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- <tp:docstring>The parameters provided omit a required argument
- or provide unsupported arguments.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Parameters provided omit a required parameter
+ or provide unsupported parameter, or the type of one
+ of the Parameters or Properties is inappropriate.</p>
</tp:docstring>
</tp:error>
</tp:possible-errors>
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 5d1eda7..4550673 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -17,8 +17,7 @@ You should have received a copy of the GNU Lesser General Public
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">
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A <i>tube</i> is a mechanism for arbitrary data transfer between
@@ -26,37 +25,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
systems to communicate without having to establish network
connections themselves. Currently, two types of tube exist:
<tp:dbus-ref namespace="org.freedesktop.Telepathy"
- >Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and
+ >Channel.Type.DBusTube</tp:dbus-ref> and
<tp:dbus-ref namespace="org.freedesktop.Telepathy"
- >Channel.Type.StreamTube.DRAFT</tp:dbus-ref>. This interface contains
+ >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>
+ <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type>
+ Contact (for 1-1 communication) or Room (to communicate with others in
+ the room simultaneously).</p>
<p>As an exception to the usual handling of capabilities, connection managers
- for protocols with capability discovery, such as XMPP, SHOULD advertise the
+ for protocols with capability discovery (such as XMPP) SHOULD advertise the
capability representing each Tube type that they support
- (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and/or
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube.DRAFT</tp:dbus-ref>)
+ (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
even if no client has indicated via
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
- that such a tube is supported.</p>
-
- <tp:rationale>
- <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
- if the contact announced to support tubes.</p>
- </tp:rationale>
+ that such a tube is supported. They SHOULD also allow clients to offer tubes with any
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref>
+ to any contact which supports the corresponding tube capability.</p>
+
+ <tp:rationale>
+ <p>This lowers the barrier to entry for those writing new tube
+ applications, and preserves interoperability with older versions of
+ the Telepathy stack which did not support rich capabilities.</p>
+ </tp:rationale>
</tp:docstring>
<property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
@@ -65,26 +65,43 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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>
+ types and values are defined by the service, but connection managers
+ must support the value being a string (D-Bus type <tt>'s'</tt>),
+ array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
+ type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
+ (D-Bus type <tt>'b'</tt>).</p>
+
<p>When the tube is offered, the parameters are transmitted with the
offer and appear as a property of the incoming tube for other
participants.</p>
- <p>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 MUST NOT be included in the request. This property is undefined until the tube is offered
- (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref>
- or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>).
- Once it has been offered, this property MUST NOT change.</p>
+
+ <p>For example, a stream tube for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref>
+ <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
+ use the following properties, as defined in <a
+ href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
+ Service Types</a>:</p>
+
+ <pre>
+{ 'u': 'some-username',
+ 'p': 'top-secret-password',
+ 'path': '/etc/passwd',
+}</pre>
+
+ <p>When requesting a tube with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request; instead, it is set
+ when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref>
+ (as appropriate) is called. Its value is undefined until the tube is
+ offered; once set, its value MUST NOT change.</p>
+
<p>When receiving an incoming tube, this property is immutable and so advertised in the
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
signal.</p>
</tp:docstring>
</property>
@@ -93,8 +110,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="State">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>State of the tube in this channel.</p>
- <p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+
+ <p>When requesting a tube with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request.</p>
</tp:docstring>
</property>
@@ -124,8 +143,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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.
+ state will be Remote_Pending. The method used to offer the tube
+ depends on the tube type.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
@@ -133,15 +152,106 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<signal name="TubeChannelStateChanged"
tp:name-for-bindings="Tube_Channel_State_Changed">
<tp:docstring>
- Emitted when the state of the tube channel changes.
+ Emitted when the state of the tube channel changes. Valid state
+ transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
</tp:docstring>
- <arg name="state" type="u" tp:type="Tube_Channel_State">
+ <arg name="State" type="u" tp:type="Tube_Channel_State">
<tp:docstring>
- The new state of the tube; see the Tube_Channel_State enumeration.
+ The new state of the tube.
</tp:docstring>
</arg>
</signal>
+ <tp:enum name="Socket_Address_Type" type="u">
+ <tp:enumvalue suffix="Unix" value="0">
+ <tp:docstring>
+ A Unix socket. The address variant contains a byte-array, signature 'ay',
+ containing the path of the socket.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Abstract_Unix" value="1">
+ <tp:docstring>
+ An abstract Unix socket. The address variant contains a byte-array,
+ signature 'ay', containing the path of the socket including the
+ leading null byte.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv4" value="2">
+ <tp:docstring>
+ An IPv4 socket. The address variant contains a Socket_Address_IPv4,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv4 dotted-quad address literal
+ (and must not be a DNS name), while the 16-bit unsigned integer is
+ the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv6" value="3">
+ <tp:docstring>
+ An IPv6 socket. The address variant contains a Socket_Address_IPv6,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv6 address literal as specified in
+ RFC2373 (and must not be a DNS name), while the 16-bit unsigned
+ integer is the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ </tp:enum>
+
+ <tp:enum name="Socket_Access_Control" type="u"
+ array-name="Socket_Access_Control_List">
+ <tp:enumvalue suffix="Localhost" value="0">
+ <tp:docstring>
+ The IP or Unix socket can be accessed by any local user (e.g.
+ a Unix socket that accepts all local connections, or an IP socket
+ listening on 127.0.0.1 (or ::1) or rejecting connections not from
+ that address). The associated variant must be ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Port" value="1">
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+ containing the string form of an IP address of the appropriate
+ version, and a port number. The socket can only be accessed if the
+ connecting process has that address and port number; all other
+ connections will be rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Netmask" value="2">
+ <tp:deprecated version="0.17.25">This has never been implemented.
+ If you want to share a service to your whole LAN, Telepathy is
+ not the way to do it.</tp:deprecated>
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+ signature (sy), containing the string form of an
+ IP address of the appropriate version, and a prefix length "n".
+ The socket can only be accessed if the first n bits of the
+ connecting address match the first n bits of the given address.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Credentials" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>May only be used on UNIX sockets.
+ The connecting process must send a byte when
+ it first connects, which is not considered to be part of the data
+ stream. If the operating system uses sendmsg() with SCM_CREDS or
+ SCM_CREDENTIALS to pass credentials over sockets, the connecting
+ process must do so if possible; if not, it must still send the
+ byte.</p>
+
+ <p>The listening process will disconnect the connection unless it
+ can determine by OS-specific means that the connecting process
+ has the same user ID as the listening process.</p>
+
+ <p>The associated variant must be ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
</interface>
</node>
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
index 513d77c..9615763 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -17,10 +17,9 @@ You should have received a copy of the GNU Lesser General Public
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">
+ <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus
traffic.</p>
@@ -54,7 +53,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
+ <method name="Offer" tp:name-for-bindings="Offer">
<tp:docstring>
Offers a D-Bus tube providing the service specified.
</tp:docstring>
@@ -62,14 +61,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:type="String_Variant_Map">
<tp:docstring>
The dictionary of arbitrary
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
to send with the tube offer.
</tp:docstring>
</arg>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the connection manager applies to the D-Bus socket.
+ </tp:docstring>
+ </arg>
<arg direction="out" name="address" type="s">
<tp:docstring>
The string describing the address of the private bus. The client
- SHOULD not attempt to connect to the address until the tube is open.
+ SHOULD NOT attempt to connect to the address until the tube is open.
</tp:docstring>
</arg>
<tp:possible-errors>
@@ -83,17 +87,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
+ <method name="Accept" tp:name-for-bindings="Accept">
<tp:docstring>
Accept a D-Bus tube that's in the "local pending" state. The
connection manager will attempt to open the tube. The tube remains in
- the "local pending" state until the TubeStateChanged signal is
- emitted.
+ the "local pending" state until the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
+ signal is emitted.
</tp:docstring>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the connection manager applies to the D-Bus socket.
+ </tp:docstring>
+ </arg>
<arg direction="out" name="address" type="s">
<tp:docstring>
The string describing the address of the private bus. The client
- SHOULD not attempt to connect to the address until the tube is open.
+ SHOULD NOT attempt to connect to the address until the tube is open.
</tp:docstring>
</arg>
</method>
@@ -104,12 +114,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
participant opens or closes the tube. This provides change
notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
</tp:docstring>
- <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants">
+ <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants">
<tp:docstring>
Array of handles and D-Bus names of new participants.
</tp:docstring>
</arg>
- <arg name="removed" type="au" tp:type="Contact_Handle[]">
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
Array of handles of former participants.
</tp:docstring>
@@ -121,11 +131,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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>
+ <tt>com.example.ServiceName</tt>.</p>
<p>When the tube is offered, the service name is transmitted to the
other end.</p>
<p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ <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>
@@ -157,6 +168,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:member>
</tp:mapping>
+ <property name="SupportedAccessControls" type="au"
+ tp:type="Socket_Access_Control[]" access="read"
+ tp:name-for-bindings="Supported_Access_Controls">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the access control types that are supported with this channel.
+ Note that only Socket_Access_Control_Localhost and
+ Socket_Access_Control_Credentials can be used with D-Bus tubes.</p>
+
+ <p>When requesting a channel with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request.</p>
+
+ </tp:docstring>
+ </property>
+
</interface>
</node>
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index 060cd0b..63e7b2f 100644
--- a/spec/Channel_Type_Stream_Tube.xml
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -17,19 +17,18 @@ You should have received a copy of the GNU Lesser General Public
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">
+ <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A stream tube is a transport for ordered, reliable data transfer,
similar to SOCK_STREAM sockets.</p>
<p>When offering a stream tube, the initiating client creates a local
listening socket and offers it to the recipient client using the
- <tp:member-ref>OfferStreamTube</tp:member-ref> method. When a
+ <tp:member-ref>Offer</tp:member-ref> method. When a
recipient accepts a stream tube using the
- <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the
+ <tp:member-ref>Accept</tp:member-ref> method, the
recipient's connection manager creates a new local listening socket.
Each time the recipient's client connects to this socket, the
initiator's connection manager proxies this connection to the
@@ -37,7 +36,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
+ <method name="Offer" tp:name-for-bindings="Offer">
<tp:docstring>
Offer a stream tube exporting the local socket specified.
</tp:docstring>
@@ -60,17 +59,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
when it connects.
</tp:docstring>
</arg>
- <arg direction="in" name="access_control_param" type="v">
- <tp:docstring>
- A parameter for the access control type, to be interpreted as
- specified in the documentation for the Socket_Access_Control enum.
- </tp:docstring>
- </arg>
<arg direction="in" name="parameters" type="a{sv}"
tp:type="String_Variant_Map">
<tp:docstring>
The dictionary of arbitrary
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
to send with the tube offer.
</tp:docstring>
</arg>
@@ -91,12 +84,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
+ <method name="Accept" tp:name-for-bindings="Accept">
<tp:docstring>
Accept a stream tube that's in the "local pending" state. The
connection manager will attempt to open the tube. The tube remains in
- the "local pending" state until the TubeStateChanged signal is
- emitted.
+ the "local pending" state until the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
+ signal is emitted.
</tp:docstring>
<arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
<tp:docstring>
@@ -104,9 +98,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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 xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of access control the connection manager should apply to
+ the socket.</p>
+
+ <p>Note that if you plan to establish more than one connection
+ through the tube, the Socket_Access_Control_Port access control
+ can't be used as you can't connect more than once from the same
+ port.</p>
</tp:docstring>
</arg>
<arg direction="in" name="access_control_param" type="v">
@@ -137,17 +136,94 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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.
+ <signal name="NewRemoteConnection"
+ tp:name-for-bindings="New_Remote_Connection">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted each time a participant opens a new connection to its
+ socket.</p>
+
+ <p>This signal is only fired on the offering side.</p>
</tp:docstring>
- <arg name="handle" type="u" tp:type="Contact_Handle">
+ <arg name="Handle" type="u" tp:type="Contact_Handle">
<tp:docstring>
The handle of the participant who opened the new connection
</tp:docstring>
</arg>
+ <arg name="Connection_Param" type="v">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A parameter which can be used by the listening process to identify
+ the connection. Note that this parameter has a meaningful value
+ only in the Socket_Access_Control_Port and
+ Socket_Access_Control_Credentials cases. If a different
+ Socket_Access_Control has been chosen when offering the tube, this
+ parameter should be ignored.</p>
+
+ <p>In the Socket_Access_Control_Port case, the variant
+ contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+ containing the address from which the CM is connected to the client
+ application.</p>
+
+ <p>In the Socket_Access_Control_Credentials case, the variant
+ contains the byte (D-Bus signature 'y') that has been sent with
+ the credentials.</p>
+ </tp:docstring>
+ </arg>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The unique ID associated with this connection. This ID will be used
+ to identifiy the connection when reporting errors with
+ <tp:member-ref>ConnectionClosed</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="NewLocalConnection"
+ tp:name-for-bindings="New_Local_Connection">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the tube application connects to the CM's socket.</p>
+
+ <p>This signal is only fired on the accepting side.</p>
+ </tp:docstring>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The unique ID associated with this connection. This ID will be used
+ to identifiy the connection when reporting errors with
+ <tp:member-ref>ConnectionClosed</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ConnectionClosed"
+ tp:name-for-bindings="Connection_Closed"
+ tp:type="Stream_Tube_Connection_Closed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a connection has been closed.</p>
+ </tp:docstring>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The ID of the connection.
+ </tp:docstring>
+ </arg>
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error describing the error that occurred.</p>
+
+ <p>The following errors can be used:</p>
+ <ul>
+ <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>:
+ user closed the socket or the tube.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>:
+ the bytestream relaying connection's data has been broken.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>:
+ the tube offer refused the connection.</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A debug message.
+ </tp:docstring>
+ </arg>
</signal>
<property name="Service" type="s" access="read"
@@ -200,6 +276,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
+ <tp:simple-type name="Stream_Tube_Connection_ID" type="u">
+ <tp:docstring>An identifier for a stream tube connection.
+ These are defined with the
+ <tp:member-ref>NewLocalConnection</tp:member-ref> or
+ <tp:member-ref>NewRemoteConnection</tp:member-ref> signals
+ and are used by <tp:member-ref>ConnectionClosed</tp:member-ref>
+ to identify the closed connection.
+ </tp:docstring>
+ </tp:simple-type>
+
</interface>
</node>
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index 2cc0131..c0a973f 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -19,6 +19,14 @@ License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:license>
<interface name="org.freedesktop.Telepathy.Channel.Type.Tubes">
+
+ <tp:deprecated version="0.17.25">Client implementations
+ SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref>
+ instead.</tp:deprecated>
+
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A "tube" is a mechanism for arbitrary data transfer. Two types of
@@ -105,92 +113,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:enumvalue>
</tp:enum>
- <tp:enum name="Socket_Address_Type" type="u">
- <tp:enumvalue suffix="Unix" value="0">
- <tp:docstring>
- A Unix socket. The address variant contains a byte-array, signature 'ay',
- containing the path of the socket.
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="Abstract_Unix" value="1">
- <tp:docstring>
- An abstract Unix socket. The address variant contains a byte-array,
- signature 'ay', containing the path of the socket including the
- leading null byte.
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="IPv4" value="2">
- <tp:docstring>
- An IPv4 socket. The address variant contains a Socket_Address_IPv4,
- i.e. a structure with signature (sq)
- in which the string is an IPv4 dotted-quad address literal
- (and must not be a DNS name), while the 16-bit unsigned integer is
- the port number.
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="IPv6" value="3">
- <tp:docstring>
- An IPv6 socket. The address variant contains a Socket_Address_IPv6,
- i.e. a structure with signature (sq)
- in which the string is an IPv6 address literal as specified in
- RFC2373 (and must not be a DNS name), while the 16-bit unsigned
- integer is the port number.
- </tp:docstring>
- </tp:enumvalue>
-
- </tp:enum>
-
- <tp:enum name="Socket_Access_Control" type="u"
- array-name="Socket_Access_Control_List">
- <tp:enumvalue suffix="Localhost" value="0">
- <tp:docstring>
- The IP or Unix socket can be accessed by any local user (e.g.
- a Unix socket that accepts all local connections, or an IP socket
- listening on 127.0.0.1 (or ::1) or rejecting connections not from
- that address). The associated variant must be ignored.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Port" value="1">
- <tp:docstring>
- May only be used on IP sockets. The associated variant must contain
- a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
- containing the string form of an IP address of the appropriate
- version, and a port number. The socket can only be accessed if the
- connecting process has that address and port number; all other
- connections will be rejected.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Netmask" value="2">
- <tp:docstring>
- May only be used on IP sockets. The associated variant must contain
- a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
- signature (sy), containing the string form of an
- IP address of the appropriate version, and a prefix length "n".
- The socket can only be accessed if the first n bits of the
- connecting address match the first n bits of the given address.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Credentials" value="3">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The connecting process must send a single zero (NUL) byte when
- it first connects, which is not considered to be part of the data
- stream. If the operating system uses sendmsg() with SCM_CREDS or
- SCM_CREDENTIALS to pass credentials over sockets, the connecting
- process must do so if possible; if not, it must still send the
- byte.</p>
-
- <p>The listening process will disconnect the connection unless it
- can determine by OS-specific means that the connecting process
- has the same user ID as the listening process.</p>
-
- <p>The associated variant must be ignored.</p>
- </tp:docstring>
- </tp:enumvalue>
- </tp:enum>
-
<tp:mapping name="Supported_Socket_Map">
<tp:docstring>The supported socket address and access-control types
for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index b63aa5b..5c56db3 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -30,6 +30,12 @@
represent bundles of channels that should be dispatched together, and
does not assume any particular properties by which channels are
uniquely identifiable.</p>
+
+ <p>If this interface is implemented on a connection, then
+ <tp:member-ref>NewChannels</tp:member-ref> MUST be emitted for
+ all new channels, even those created with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection"
+ >RequestChannel</tp:dbus-ref>.</p>
</tp:docstring>
<tp:struct name="Channel_Details" array-name="Channel_Details_List">
diff --git a/spec/Debug.xml b/spec/Debug.xml
new file mode 100644
index 0000000..a21d9db
--- /dev/null
+++ b/spec/Debug.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" ?>
+<node name="/Debug"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2009 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Debug.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.24"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for providing debug messages.</p>
+
+ <p>This interface is primarily provided by one object per
+ service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.</p>
+ </tp:docstring>
+
+ <property name="Enabled" type="b" access="readwrite"
+ tp:name-for-bindings="Enabled">
+ <tp:docstring>
+ TRUE if the <tp:member-ref>NewDebugMessage</tp:member-ref> signal
+ should be emitted when a new debug message is generated.
+ </tp:docstring>
+ </property>
+
+ <method name="GetMessages" tp:name-for-bindings="Get_Messages">
+ <tp:docstring>
+ Retrieve buffered debug messages. An implementation could have a
+ limit on how many message it keeps and so the array returned from
+ this method should not be assumed to be all of the messages in
+ the lifetime of the service.
+ </tp:docstring>
+
+ <arg direction="out" name="Messages" type="a(dsus)"
+ tp:type="Debug_Message[]">
+ <tp:docstring>
+ A list of debug messages.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="NewDebugMessage" tp:name-for-bindings="New_Debug_Message">
+ <tp:docstring>
+ Emitted when a debug messages is generated if the
+ <tp:member-ref>Enabled</tp:member-ref> property is set to TRUE.
+ </tp:docstring>
+
+ <arg name="time" type="d">
+ <tp:docstring>
+ Timestamp of the debug message.
+ </tp:docstring>
+ </arg>
+ <arg name="domain" type="s">
+ <tp:docstring>
+ Domain of the debug message, as described in the Debug_Message struct.
+ </tp:docstring>
+ </arg>
+ <arg name="level" type="u" tp:type="Debug_Level">
+ <tp:docstring>
+ Level of the debug message.
+ </tp:docstring>
+ </arg>
+ <arg name="message" type="s">
+ <tp:docstring>
+ The text of the debug message.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Debug_Level" type="u">
+ <tp:enumvalue suffix="Error" value="0">
+ <tp:docstring>
+ Log level for errors. Error messages are always fatal, resulting
+ in the service terminating after something completely
+ unexpected occurred.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Critical" value="1">
+ <tp:docstring>
+ Log level for critical messages. Critical messages are messages
+ that the service might predict and it is up to the service itself
+ to decide whether to terminate following a critical message.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Warning" value="2">
+ <tp:docstring>
+ Log level for warnings.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Message" value="3">
+ <tp:docstring>
+ Log level for messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Info" value="4">
+ <tp:docstring>
+ Log level for information messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Debug" value="5">
+ <tp:docstring>
+ Log level for debug messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Debug_Message" array-name="Debug_Message_List">
+ <tp:docstring>
+ A struct representing a debug message, as returned by
+ <tp:member-ref>GetMessages</tp:member-ref>.
+ </tp:docstring>
+
+ <tp:member type="d" name="Timestamp">
+ <tp:docstring>
+ Timestamp of the debug message. This is a double to allow
+ more accuracy in the time the message was logged.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="s" name="Domain">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Domain of the debug message. This is used to identify
+ the source of debug messages. For example, debug messages
+ from a connection manager could have this Domain struct
+ member be the name of the connection manager, and logs
+ from any helper library could have the name of the helper
+ library.</p>
+
+ <p>The domain could also contain a category as to where
+ the log message originated separated by a forward-slash.
+ For example, if a debug message was output in a connection
+ manager called "dummy", in the file-transfer code, this
+ Domain struct member might be <tt>dummy/file-transfer</tt>.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" tp:type="Debug_Level" name="Level">
+ <tp:docstring>
+ Level of the debug message. This states the severity of the
+ debug message.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="s" name="Message">
+ <tp:docstring>
+ The text of the debug message.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
index aaa4602..bc9c8b2 100644
--- a/spec/Properties_Interface.xml
+++ b/spec/Properties_Interface.xml
@@ -158,7 +158,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
tp:type="Property_Value[]">
<!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
<tp:docstring>
- A dictionary mapping integer identifiers to boxed values
+ An array mapping integer property identifiers to boxed values
</tp:docstring>
</arg>
<tp:possible-errors>
diff --git a/spec/all.xml b/spec/all.xml
index 93ce925..ed74cb8 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.23</tp:version>
+<tp:version>0.17.25</tp:version>
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
@@ -116,6 +116,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Media_Session_Handler.xml"/>
<xi:include href="Media_Stream_Handler.xml"/>
</tp:section>
+
+ <tp:section name="Debugging">
+ <xi:include href="Debug.xml"/>
+ </tp:section>
</tp:section>
<tp:section name="The Account Manager">
diff --git a/spec/errors.xml b/spec/errors.xml
index f82c532..4ab86d5 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -307,6 +307,24 @@
</tp:docstring>
</tp:error>
+ <tp:error name="ConnectionRefused">
+ <tp:docstring>
+ Raised when a connection is refused.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="ConnectionFailed">
+ <tp:docstring>
+ Raised when a connection can't be established.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="ConnectionLost">
+ <tp:docstring>
+ Raised when a connection is broken.
+ </tp:docstring>
+ </tp:error>
+
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
--
1.5.6.5
More information about the telepathy-commits
mailing list