diff options
| -rw-r--r-- | spec/Channel.xml | 5 | ||||
| -rw-r--r-- | spec/Channel_Interface_Hold.xml | 9 | ||||
| -rw-r--r-- | spec/Channel_Interface_Media_Signalling.xml | 26 | ||||
| -rw-r--r-- | spec/Channel_Type_Contact_Search.xml | 32 | ||||
| -rw-r--r-- | spec/Channel_Type_Streamed_Media.xml | 57 | ||||
| -rw-r--r-- | spec/Channel_Type_Text.xml | 37 | ||||
| -rw-r--r-- | spec/Channel_Type_Tubes.xml | 10 | ||||
| -rw-r--r-- | spec/Connection.xml | 52 | ||||
| -rw-r--r-- | spec/Connection_Interface_Avatars.xml | 7 | ||||
| -rw-r--r-- | spec/Connection_Interface_Privacy.xml | 2 | ||||
| -rw-r--r-- | spec/Connection_Manager.xml | 53 | ||||
| -rw-r--r-- | spec/Media_Stream_Handler.xml | 6 | ||||
| -rw-r--r-- | spec/Properties_Interface.xml | 10 | ||||
| -rw-r--r-- | spec/all.xml | 12 |
14 files changed, 243 insertions, 75 deletions
diff --git a/spec/Channel.xml b/spec/Channel.xml index 5e8678c6c..621702939 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -43,6 +43,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <signal name="Closed"> <tp:docstring> Emitted when the channel has been closed. Method calls on the @@ -51,6 +52,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ at any point. </tp:docstring> </signal> + <method name="GetChannelType"> <arg direction="out" type="s" tp:type="DBus_Interface"> <tp:docstring>The interface name</tp:docstring> @@ -59,6 +61,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Returns the interface name for the type of this channel. </tp:docstring> </method> + <method name="GetHandle"> <arg direction="out" type="u" tp:type="Handle_Type"> <tp:docstring> @@ -78,6 +81,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ zero if it is transient and defined only by its contents. </tp:docstring> </method> + <method name="GetInterfaces"> <arg direction="out" type="as" tp:type="DBus_Interface[]"> <tp:docstring> @@ -88,6 +92,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Get the optional interfaces implemented by the channel. </tp:docstring> </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index 91e72ff48..6e04ffb3a 100644 --- a/spec/Channel_Interface_Hold.xml +++ b/spec/Channel_Interface_Hold.xml @@ -114,8 +114,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested hold state cannot be achieved; for example, + if only a limited number of channels can be in the "not on hold" + state, attempts to exceed this number will raise NotAvailable. + </tp:docstring> + </tp:error> </tp:possible-errors> </method> diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml index 6aed7a114..cc7a7a956 100644 --- a/spec/Channel_Interface_Media_Signalling.xml +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -21,20 +21,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:simple-type name="Media_Session_Type" type="s"> + <tp:docstring>The type of a media session. Currently, the only supported + value is "rtp".</tp:docstring> + </tp:simple-type> + + <tp:struct name="Media_Session_Handler_Info" + array-name="Media_Session_Handler_Info_List"> + <tp:docstring>A struct representing a active session handler.</tp:docstring> + <tp:member type="o" name="Session_Handler"> + <tp:docstring>The object path of the session handler, which is on the + same bus name as the channel.</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type"> + <tp:docstring>The media session's type</tp:docstring> + </tp:member> + </tp:struct> + <method name="GetSessionHandlers"> - <arg direction="out" type="a(os)"/> + <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"/> <tp:docstring> Returns all currently active session handlers on this channel as a list of (session_handler_path, type). </tp:docstring> </method> + <signal name="NewSessionHandler"> - <arg name="session_handler" type="o"> + <arg name="Session_Handler" type="o"> <tp:docstring> Object path of the new MediaSessionHandler object </tp:docstring> </arg> - <arg name="type" type="s"> + <arg name="Session_Type" tp:type="Media_Session_Type" type="s"> <tp:docstring> String indicating type of session, eg "rtp" </tp:docstring> @@ -81,6 +100,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ server. </tp:docstring> </tp:property> + <tp:docstring> An interface for signalling a channel containing synchronised media sessions which can contain an arbitrary number of streams. The negotiation diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index f3c7fd64d..0213ca70d 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -21,19 +21,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch" tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Search_Key_Info"> + <tp:docstring>A struct representing details on search strings.</tp:docstring> + <tp:member type="b" name="Is_Mandatory"> + <tp:docstring>Booleans indicating if the search key is mandatory. + </tp:docstring> + </tp:member> + <tp:member type="g" name="Type_Signature"> + <tp:docstring>The type signature of the value for this search key. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Search_Key_Info_Map"> + <tp:docstring>A dictionary mapping string search key names to its search details. + </tp:docstring> + <tp:member type="s" name="Term"/> + <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/> + </tp:mapping> + <method name="GetSearchKeys"> <arg direction="out" type="s"> <tp:docstring> A string with any instructions from the server </tp:docstring> </arg> - <arg direction="out" type="a{s(bg)}"> + <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A dictionary mapping string search key names to an array of: - <ul> - <li>booleans indicating if the search key is mandatory</li> - <li>type signature of the value for this search key</li> - </ul> + A dictionary mapping string search key names to its search details. </tp:docstring> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -75,7 +91,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <method name="Search"> - <arg direction="in" name="terms" type="a{sv}"> + <arg direction="in" name="terms" type="a{sv}" tp:type="String_Variant_Map"> <tp:docstring> A dictionary mapping search key names to the desired values </tp:docstring> @@ -95,7 +111,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg name="contact" type="u" tp:type="Contact_Handle"> <tp:docstring>An integer handle for the contact</tp:docstring> </arg> - <arg name="values" type="a{sv}"> + <arg name="values" type="a{sv}" tp:type="String_Variant_Map"> <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring> </arg> <tp:docstring> diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index d24f37fc9..665e2d0ff 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or @@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + <tp:enum name="Media_Stream_Type" type="u"> <tp:enumvalue suffix="Audio" value="0"> <tp:docstring>An audio stream</tp:docstring> @@ -29,6 +30,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>A video stream</tp:docstring> </tp:enumvalue> </tp:enum> + <tp:enum name="Media_Stream_State" type="u"> <tp:enumvalue suffix="Disconnected" value="0"> <tp:docstring>The stream is disconnected.</tp:docstring> @@ -40,6 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>The stream is connected.</tp:docstring> </tp:enumvalue> </tp:enum> + <tp:enum name="Media_Stream_Direction" type="u"> <tp:enumvalue suffix="None" value="0"> <tp:docstring>Media are not being sent or received</tp:docstring> @@ -54,6 +57,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>Media are being sent and received</tp:docstring> </tp:enumvalue> </tp:enum> + <tp:flags name="Media_Stream_Pending_Send" value-prefix="Media_Stream_Pending" type="u"> <tp:flag suffix="Local_Send" value="1"> <tp:docstring> @@ -70,6 +74,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:flag> </tp:flags> + + <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> + <tp:member type="u" tp:type="Stream_ID" name="Identifier"/> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> + <tp:member type="u" tp:type="Media_Stream_State" name="State"/> + <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> + <tp:member type="u" tp:type="Media_Stream_Pending_Send" + name="Pending_Send_Flags"/> + </tp:struct> + + <tp:simple-type name="Stream_ID" type="u"/> + <method name="ListStreams"> <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -91,8 +108,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ which is unique for each stream within the channel. </tp:docstring> </method> + <method name="RemoveStreams"> - <arg direction="in" name="streams" type="au"> + <arg direction="in" name="streams" type="au" tp:type="Stream_ID[]"> <tp:docstring> An array of stream identifiers (as defined in ListStreams) </tp:docstring> @@ -106,6 +124,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <method name="RequestStreamDirection"> <arg direction="in" name="stream_id" type="u"> <tp:docstring> @@ -142,13 +161,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <method name="RequestStreams"> <arg direction="in" name="contact_handle" type="u" tp:type="Contact_Handle"> <tp:docstring> A contact handle with whom to establish the streams </tp:docstring> </arg> - <arg direction="in" name="types" type="au"> + <arg direction="in" name="types" type="au" tp:type="Media_Stream_Type[]"> <tp:docstring> An array of stream types (values of MediaStreamType) </tp:docstring> @@ -178,6 +198,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ them), the StreamDirectionChanged signal will be emitted with the MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied.</p> + + <p>As of version 0.17.2, it is valid to use a handle which is neither + a current nor pending member in this channel's Group interface. If + so, that handle will be added to the remote-pending set only when + an attempt has actually been made to contact them. For further + call-state notification, use the CallState interface, if + supported.</p> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> @@ -189,6 +216,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <signal name="StreamAdded"> <arg name="stream_id" type="u"> <tp:docstring> @@ -210,6 +238,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when a new stream has been added to this channel. </tp:docstring> </signal> + <signal name="StreamDirectionChanged"> <arg name="stream_id" type="u"> <tp:docstring> @@ -233,6 +262,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ should be called to indicate whether or not this change is acceptable. </tp:docstring> </signal> + <signal name="StreamError"> <arg name="stream_id" type="u"> <tp:docstring> @@ -253,6 +283,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when a stream encounters an error. </tp:docstring> </signal> + <signal name="StreamRemoved"> <arg name="stream_id" type="u"> <tp:docstring> @@ -263,6 +294,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when a stream has been removed from this channel. </tp:docstring> </signal> + <signal name="StreamStateChanged"> <arg name="stream_id" type="u"> <tp:docstring> @@ -278,6 +310,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Emitted when a member's stream's state changes. </tp:docstring> </signal> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel that can send and receive streamed media such as audio or video. Provides a number of methods for listing and requesting new streams, and @@ -289,8 +322,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 in "remote pending" until the call is accepted, then - move to the group's members.</p> + should be absent from the channel until a call is made, appear in + "remote pending" from when the call is attempted until the call is + accepted, then move to the group's members.</p> <p>Similarly, incoming calls should be signalled as having handle type 0 and handle 0. The remote contact should be in the group's members, @@ -306,6 +340,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ connection manager), the signalling interface can be omitted and this channel type used simply to control the streams.</p> </tp:docstring> + <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u"> <tp:docstring> The channel-type-specific capability flags used for @@ -335,16 +370,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> </tp:flags> - <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> - <tp:member type="u" name="Identifier"/> - <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> - <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> - <tp:member type="u" tp:type="Media_Stream_State" name="State"/> - <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> - <tp:member type="u" tp:type="Media_Stream_Pending_Send" - name="Pending_Send_Flags"/> - </tp:struct> - </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index b2e0c65f2..6fec0b1f2 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -21,13 +21,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:simple-type name="Message_ID" type="u"/> + <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> <tp:docstring>A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) representing a pending text message, as returned by ListPendingMessages on the Text channel type. The arguments of the Received signal also match this struct's signature.</tp:docstring> - <tp:member type="u" name="Message_ID"/> + <tp:member type="u" tp:type="Message_ID" name="Identifier"/> <tp:member type="u" name="Unix_Timestamp"/> <tp:member type="u" tp:type="Contact_Handle" name="Sender"/> <tp:member type="u" tp:type="Channel_Text_Message_Type" @@ -37,7 +39,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:struct> <method name="AcknowledgePendingMessages"> - <arg direction="in" name="ids" type="au"> + <arg direction="in" name="ids" type="au" tp:type="Message_ID[]"> <tp:docstring> The IDs of the messages to acknowledge </tp:docstring> @@ -344,26 +346,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:property> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for sending and receiving messages in plain text, with no - formatting.</p> + <p>A channel type for sending and receiving messages in plain text, + with no formatting.</p> - <p>When a message is received, an identifier is assigned and a Received signal - emitted, and the message placed in a pending queue which can be inspected - with ListPendingMessages. A client which has handled the message by showing - it to the user (or equivalent) should acknowledge the receipt using the - AcknowledgePendingMessage method, and the message will then be removed from - the pending queue. Numeric identifiers for received messages may be reused - over the lifetime of the channel.</p> + <p>When a message is received, an identifier is assigned and a + Received signal emitted, and the message placed in a pending queue + which can be inspected with ListPendingMessages. A client which has + handled the message by showing it to the user (or equivalent) should + acknowledge the receipt using the AcknowledgePendingMessage method, + and the message will then be removed from the pending queue. Numeric + identifiers for received messages may be reused over the lifetime of + the channel.</p> - <p>Each message has an associated 'type' value, which should be one of the - values allowed by ChannelTextMessageType.</p> + <p>Each message has an associated 'type' value, which should be one + of the values allowed by ChannelTextMessageType.</p> <p>Each message also has a flags value, which is a bitwise OR of the - flags given in ChannelTextMessageFlags.</p> + flags given in ChannelTextMessageFlags.</p> - <p>Sending messages can be requested using the Send method, which will return - and cause the Sent signal to be emitted when the message has been delivered - to the server, or SendError if there is a failure.</p> + <p>Sending messages can be requested using the Send method, which will + return and cause the Sent signal to be emitted when the message has + been delivered to the server, or SendError if there is a failure.</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 diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml index c0be6190f..b187c03e1 100644 --- a/spec/Channel_Type_Tubes.xml +++ b/spec/Channel_Type_Tubes.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> - Copyright (C) 2007 Collabora Limited + Copyright (C) 2007-2008 Collabora Limited </tp:copyright> <tp:license> This library is free software; you can redistribute it and/or @@ -47,7 +47,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring>A struct (tube ID, initiator handle, tube type, service name, parameters, state) representing a tube, as returned by ListTubes on the Tubes channel type.</tp:docstring> - <tp:member type="u" name="Tube_ID"/> + <tp:member type="u" tp:type="Tube_ID" name="Identifier"/> <tp:member type="u" tp:type="Contact_Handle" name="Initiator"/> <tp:member type="u" tp:type="Tube_Type" name="Type"/> <tp:member type="s" name="Service"/> @@ -350,7 +350,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. D-Bus type, or a byte array 'ay'. </tp:docstring> </arg> - <arg direction="out" type="u"> + <arg direction="out" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the new tube. </tp:docstring> @@ -380,6 +380,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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". @@ -421,7 +423,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> - <arg direction="out" type="u"> + <arg direction="out" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the new tube. </tp:docstring> diff --git a/spec/Connection.xml b/spec/Connection.xml index d703ec329..9deb61277 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -48,12 +48,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ asynchronously and errors will be returned by emitting StatusChanged signals. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> The connection is already connecting or connected </tp:error> </tp:possible-errors> </method> + <method name="Disconnect"> <tp:docstring> Request that the connection be closed. This closes the connection if @@ -61,66 +63,79 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ object. </tp:docstring> </method> + <method name="GetInterfaces"> <arg direction="out" type="as" tp:type="DBus_Interface[]"> <tp:docstring> An array of D-Bus interface names </tp:docstring> </arg> + <tp:docstring> Get the optional interfaces supported by this connection. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> </tp:possible-errors> </method> + <method name="GetProtocol"> <arg direction="out" type="s"> <tp:docstring> A string identifier for the protocol </tp:docstring> </arg> + <tp:docstring> Get the protocol this connection is using. </tp:docstring> </method> + <method name="GetSelfHandle"> <arg direction="out" type="u"> <tp:docstring> An integer handle representing the user </tp:docstring> </arg> + <tp:docstring> Get the handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the Renamed signal on the Renaming interface (if present). This is always a CONTACT type handle. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> </tp:possible-errors> </method> + <method name="GetStatus"> <arg direction="out" type="u" tp:type="Connection_Status"> <tp:docstring> An integer representing the current status </tp:docstring> </arg> + <tp:docstring> Get the current status as defined in the StatusChanged signal. </tp:docstring> </method> + <method name="HoldHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> The type of handle to be held </tp:docstring> </arg> + <arg direction="in" name="handles" type="au" tp:type="Handle[]"> <tp:docstring> A array of integer handles to hold </tp:docstring> </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or @@ -138,6 +153,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ ReleaseHandles when none of the cooperating components need the handle any longer.</p> </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> @@ -148,26 +164,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <method name="InspectHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> The type of handle to be inspected </tp:docstring> </arg> + <arg direction="in" name="handles" type="au" tp:type="Handle[]"> <tp:docstring> An array of integer handles of this type </tp:docstring> </arg> + <arg direction="out" type="as"> <tp:docstring> An array of handle names in the same order as the given numbers </tp:docstring> </arg> + <tp:docstring> Return a string representation for a number of handles of a given type. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> @@ -178,45 +199,54 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <method name="ListChannels"> <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"> <tp:docstring> An array of structs representing channels. </tp:docstring> </arg> + <tp:docstring> List all the channels which currently exist on this connection. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> </tp:possible-errors> </method> + <signal name="NewChannel"> <arg name="object_path" type="o"> <tp:docstring> A D-Bus object path for the channel object on this service </tp:docstring> </arg> + <arg name="channel_type" type="s" tp:type="DBus_Interface"> <tp:docstring> A D-Bus interface name representing the channel type </tp:docstring> </arg> + <arg name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> An integer representing the type of handle this channel communicates with, which is zero if no handle is specified </tp:docstring> </arg> + <arg name="handle" type="u" tp:type="Handle"> <tp:docstring> A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel </tp:docstring> </arg> + <arg name="suppress_handler" type="b"> <tp:docstring> A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched </tp:docstring> </arg> + <tp:docstring> Emitted when a new Channel object is created, either through user request or incoming information from the service. The suppress_handler @@ -224,23 +254,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ or is an incoming communication and needs to have a handler launched. </tp:docstring> </signal> + <method name="ReleaseHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> An integer handle type (as defined in RequestHandle) </tp:docstring> </arg> + <arg direction="in" name="handles" type="au" tp:type="Handle[]"> <tp:docstring> An array of integer handles being held by the client </tp:docstring> </arg> + <tp:docstring> Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See HoldHandles for notes. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> @@ -254,23 +288,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <method name="RequestChannel"> <arg direction="in" name="type" type="s" tp:type="DBus_Interface"> <tp:docstring> A D-Bus interface name representing base channel type </tp:docstring> </arg> + <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> An integer representing the handle type, or zero if no handle is being specified </tp:docstring> </arg> + <arg direction="in" name="handle" type="u" tp:type="Handle"> <tp:docstring> A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is zero </tp:docstring> </arg> + <arg direction="in" name="suppress_handler" type="b"> <tp:docstring> If true, the requesting client intends to take responsibility for @@ -278,11 +316,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ be launched </tp:docstring> </arg> + <arg direction="out" type="o"> <tp:docstring> The D-Bus object path for the channel created or retrieved </tp:docstring> </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given @@ -312,6 +352,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>If the request cannot be satisfied, an error is raised and no channel is created.</p> </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> @@ -335,6 +376,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> </tp:possible-errors> </method> + <tp:enum name="Handle_Type" type="u"> <tp:enumvalue suffix="None" value="0"> <tp:docstring> @@ -364,22 +406,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> </tp:enum> + <method name="RequestHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> The type of handle required </tp:docstring> </arg> + <arg direction="in" name="names" type="as"> <tp:docstring> An array of names of entities to request handles for </tp:docstring> </arg> + <arg direction="out" type="au" tp:type="Handle[]"> <tp:docstring> An array of integer handle numbers in the same order as the given strings </tp:docstring> </arg> + <tp:docstring> Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The @@ -390,6 +436,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager. </tp:docstring> + <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> @@ -400,6 +447,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> </tp:possible-errors> </method> + <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u"> <tp:enumvalue suffix="Connected" value="0"> <tp:docstring> @@ -496,24 +544,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> </tp:enum> + <signal name="StatusChanged"> <arg name="status" type="u" tp:type="Connection_Status"> <tp:docstring> An integer indicating the new status, as defined by ConnectionStatus </tp:docstring> </arg> + <arg name="reason" type="u" tp:type="Connection_Status_Reason"> <tp:docstring> An integer indicating the reason for the status change, as defined by ConnectionStatusReason </tp:docstring> </arg> + <tp:docstring> Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason. </tp:docstring> </signal> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml index 33f6f6856..9395a6efd 100644 --- a/spec/Connection_Interface_Avatars.xml +++ b/spec/Connection_Interface_Avatars.xml @@ -21,7 +21,7 @@ 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:mapping name="Avatar_Token_Map" array-name=""> + <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"/> @@ -43,7 +43,7 @@ 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 RequestAvatar. + avatar should be requested with RequestAvatars. </tp:docstring> </signal> <signal name="AvatarRetrieved"> @@ -156,8 +156,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ can be persisted across connections, and should be used by the client to check whether the avatars have been updated. A CM must always have the tokens for the self handle if one is set (even if it is set to no - avatar). Otherwise, only tokens that are already known or that can be - discovered without retrieving the complete avatar are returned. An + avatar). Otherwise, only tokens that are already known are returned. An empty token means the given contact has no avatar. </tp:docstring> <tp:possible-errors> diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml index 4ada36918..865473632 100644 --- a/spec/Connection_Interface_Privacy.xml +++ b/spec/Connection_Interface_Privacy.xml @@ -42,7 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of valid privacy modes for this connection </tp:docstring> </arg> - <tp:docstring> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Returns the privacy modes available on this connection. The following well-known names should be used where appropriate: <dl> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 5d3aef395..4d3bfade2 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -20,6 +20,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.ConnectionManager"> + <tp:simple-type name="Connection_Manager_Name" type="s"> + <tp:docstring> + The name of a connection manager, found in its well-known + bus name and object path. This must be a non-empty string of + ASCII letters, digits and underscores, starting with a letter. + This is typically the name of the executable with any "telepathy-" + prefix removed, and any hyphen/minus signs replaced by + underscores. + </tp:docstring> + </tp:simple-type> + <tp:simple-type name="Protocol" type="s"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An instant messaging protocol. It must consist only of ASCII @@ -88,6 +99,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ providing the default. </tp:docstring> </tp:flag> + <tp:flag suffix="Secret" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This parameter should be considered private or secret; for + instance, clients should store it in a "password safe" like + gnome-keyring or kwallet, omit it from debug logs, and use a + text input widget that hides the value of the parameter.</p> + + <p>(Clients that support older connection managers may also treat + any parameter whose name contains "password" as though it had this + flag.)</p> + </tp:docstring> + </tp:flag> </tp:flags> <method name="GetParameters"> <arg direction="in" name="proto" type="s" tp:type="Protocol"> @@ -271,10 +294,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ processes are intended to be started by D-Bus service activation.</p> <p>For service discovery, each Telepathy connection manager must have - a <em>connection manager name</em>, which is a non-empty string of - ASCII letters, digits and underscores, starting with a letter. This - is typically the name of the executable with any "telepathy-" prefix - removed.</p> + a <em>connection manager name</em> (see Connection_Manager_Name for + syntax).</p> <p>The connection manager must then provide a well-known bus name of <code>org.freedesktop.Telepathy.ConnectionManager.<em>cmname</em></code> @@ -313,7 +334,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <code>telepathy/managers/<em>cmname</em>.manager</code> that can be read without error. This file has the same syntax as a <a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p> - + + <p>Clients must still support connection managers for which no + <code>.manager</code> file can be found, which they can do by activating + the connection manager and calling its methods; the + <code>.manager</code> file is merely an optimization. Connection managers + whose list of protocols can change at any time (for instance, via + a plugin architecture) should not install a <code>.manager</code> + file.</p> + <p>For each protocol name <em>proto</em> that would be returned by ListProtocols, the .manager file contains a group headed <code>[Protocol <em>proto</em>]</code>. For each parameter @@ -321,10 +350,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ .manager file contains a key <code>param-<em>p</em></code> with a value consisting of a D-Bus signature (a single complete type), optionally followed by a space and a space-separated list of flags. The supported - flags are <code>required</code>, corresponding to - Conn_Mgr_Param_Flag_Required, and <code>register</code>, corresponding - to Conn_Mgr_Param_Flag_Register. - </p> + flags are:</p> + + <ul> + <li><code>required</code>, corresponding to + Conn_Mgr_Param_Flag_Required</li> + <li><code>register</code>, corresponding + to Conn_Mgr_Param_Flag_Register</li> + <li><code>secret</code>, corresponding + to Conn_Mgr_Param_Flag_Secret</li> + </ul> <p>The group may also contain a key <code>default-<em>p</em></code> whose value is a string form of the default value for the parameter. diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index 92be1f2f7..affaff66a 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -181,7 +181,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enumvalue> </tp:enum> <method name="Ready"> - <arg direction="in" name="codecs" type="a(usuuua{ss})"> + <arg direction="in" name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> <tp:docstring> As for SupportedCodecs. </tp:docstring> @@ -193,7 +194,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <method name="SetLocalCodecs"> - <arg name="codecs" type="a(usuuua{ss})" direction="in"> + <arg name="codecs" type="a(usuuua{ss})" direction="in" + tp:type="Media_Stream_Handler_Codec[]"> <tp:docstring>Codecs in the same format as for SupportedCodecs, which have the same semantics as the local codecs passed to Ready</tp:docstring> diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml index a028913d8..fa78f20a0 100644 --- a/spec/Properties_Interface.xml +++ b/spec/Properties_Interface.xml @@ -39,12 +39,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member type="u" name="New_Flags"/> </tp:struct> + <tp:simple-type name="Property_ID" type="u"> + <tp:docstring> + An unsigned integer used to represent a Telepathy property. + </tp:docstring> + </tp:simple-type> + <tp:struct name="Property_Value" array-name="Property_Value_List"> <tp:docstring>A struct (property ID, value) representing a property's value, as seen in the PropertiesChanged signal on the Properties interface, returned by the GetProperties method and passed to the SetProperties method.</tp:docstring> - <tp:member type="u" name="Property_ID"/> + <tp:member type="u" tp:type="Property_ID" name="Identifier"/> <tp:member type="v" name="Value"/> </tp:struct> @@ -53,7 +59,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Returns an array of (identifier, value) pairs containing the current values of the given properties. </tp:docstring> - <arg direction="in" name="properties" type="au"> + <arg direction="in" name="properties" type="au" tp:type="Property_ID[]"> <tp:docstring>An array of property identifiers</tp:docstring> </arg> <arg direction="out" type="a(uv)" tp:type="Property_Value[]"> diff --git a/spec/all.xml b/spec/all.xml index 1fb517c6a..c11bcbf03 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.1</tp:version> +<tp:version>0.17.2</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -45,6 +45,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Type_Tubes.xml"/> <xi:include href="Channel_Interface_Call_Merging.xml"/> +<xi:include href="Channel_Interface_Call_State.xml"/> <xi:include href="Channel_Interface_Chat_State.xml"/> <xi:include href="Channel_Interface_DTMF.xml"/> <xi:include href="Channel_Interface_Group.xml"/> @@ -58,15 +59,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Properties_Interface.xml"/> +<xi:include href="Account_Manager.xml"/> +<xi:include href="Account.xml"/> + <xi:include href="Channel_Handler.xml"/> <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> -<xi:include href="extensions.xml"> - <xi:fallback> - <!-- absence of non-spec extensions is OK --> - </xi:fallback> -</xi:include> - </tp:spec> |