diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-05-25 15:45:24 +0100 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-05-25 16:01:09 +0100 |
| commit | 2948ab95e843a969840d9e2696103e9b63282c92 (patch) | |
| tree | 0d7461643c8a39671c3b2062b5e6f5dd856b80ef /spec | |
| parent | fc4cf185b4528a582c5f2eb2efeb0cc60509371a (diff) | |
| download | telepathy-glib-2948ab95e843a969840d9e2696103e9b63282c92.tar.gz | |
Update to spec 0.19.6
Diffstat (limited to 'spec')
28 files changed, 2628 insertions, 106 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index 4b112cb4d..f315c15d9 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -480,6 +480,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, a change to the presence of this account is + in progress.</p> + + <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on + an account that could go online, or whenever an account with a + non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes + able to go online (for instance because + <tp:member-ref>Enabled</tp:member-ref> or + <tp:member-ref>Valid</tp:member-ref> changes to True), + ChangingPresence MUST change to True, and the two property changes MUST + be emitted in the same + <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the + Set method returns.</p> + + <p>When the account manager succeeds or fails in changing the presence, + or the connection disconnects due to an error, ChangingPresence MUST + change to False as part of the same + <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p> + + <tp:rationale> + <p>This allows UIs to indicate that a presence change is in progress + or has finished, even if the change was initiated by a different + UI.</p> + + <p>For instance, Maemo 5 and Empathy indicate a presence change by + having the presence indicator alternate between the + <tp:member-ref>RequestedPresence</tp:member-ref> + and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should + start blinking when ChangingPresence becomes true, and stop when it + becomes false.</p> + </tp:rationale> + + </tp:docstring> + </property> + <method name="Reconnect" tp:name-for-bindings="Reconnect"> <tp:added version="0.17.24"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 2b3eb65d5..8b9a17c84 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -61,7 +61,7 @@ </tp:docstring> </tp:member> - <tp:member name="Parameters" type="a{ss}"> + <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Extra parameters for this codec </tp:docstring> diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml new file mode 100644 index 000000000..eea724f59 --- /dev/null +++ b/spec/Call_Content_Interface_Mute.xml @@ -0,0 +1,83 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for calls which may be muted. This only makes sense + for channels where audio or video is streaming between members.</p> + + <p>Muting a call content indicates that the user does not wish to send + outgoing audio or video.</p> + + <p>Although it's client's responsibility to actually mute the microphone + or turn off the camera, using this interface the client can also + inform the CM and other clients of that fact.</p> + <tp:rationale> + <p>For some protocols, the fact that the content is muted needs to be + transmitted to the peer; for others, the notification to the peer is + only informational (eg. XMPP), and some protocols may have no notion + of muting at all.</p> + </tp:rationale> + </tp:docstring> + + <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> + <tp:docstring> + Emitted to indicate that the mute state has changed for this call content. + This may occur as a consequence of the client calling + <tp:member-ref>Muted</tp:member-ref>, or as an indication that another + client has (un)muted the content. + </tp:docstring> + + <arg name="MuteState" type="b"> + <tp:docstring> + True if the content is now muted. + </tp:docstring> + </arg> + </signal> + + <property name="MuteState" type="b" + access="read" tp:name-for-bindings="Mute_State"> + <tp:docstring> + True if the content is muted. + </tp:docstring> + </property> + + <method name="Muted" tp:name-for-bindings="Muted"> + <arg direction="in" name="Muted" type="b"> + <tp:docstring> + True if the client has muted the content. + </tp:docstring> + </arg> + + <tp:docstring> + <p>Inform the CM that the call content has been muted or unmuted by + che client.</p> + + <p>It is the client's responsibility to actually mute or unmute the + microphone or camera used for the content. However, the client + MUST call this whenever it mutes or unmutes the content.</p> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 26d9b579f..6ec69a67b 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -370,6 +370,72 @@ </tp:possible-errors> </method> + <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time"> + <tp:added version="0.19.6"> + At the time of writing, no released implementation of the + Channel Dispatcher implements this method; clients should fall + back to calling <tp:member-ref>HandleWith</tp:member-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the + approver to pass an user action time. This timestamp will be passed + to the Handler when <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + is called.</p> + </tp:docstring> + + <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the channel + handler that should handle the channel, or the empty string + if the client has no preferred channel handler.</p> + </tp:docstring> + </arg> + + <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The selected handler is non-empty, but is not a syntactically + correct <tp:type>DBus_Bus_Name</tp:type> or does not start with + "<code>org.freedesktop.Telepathy.Client.</code>". + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The selected handler is temporarily unable to handle these + channels. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <signal name="Finished" tp:name-for-bindings="Finished"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when this dispatch operation finishes. The dispatch diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index daee24c9c..474c809f2 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -164,7 +164,7 @@ </arg> <arg direction="in" name="User_Action_Time" type="x" - tp:type="Unix_Timestamp64"> + tp:type="User_Action_Timestamp"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. @@ -305,7 +305,7 @@ </arg> <arg direction="in" name="User_Action_Time" type="x" - tp:type="Unix_Timestamp64"> + tp:type="User_Action_Timestamp"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.</p> diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml new file mode 100644 index 000000000..7477f9637 --- /dev/null +++ b/spec/Channel_Interface_Anonymity.xml @@ -0,0 +1,68 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Anonymity" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for requesting the anonymity modes of a channel + (as defined in Connection.Interface.Anonymity.DRAFT).</p> + </tp:docstring> + + <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" + access="read" tp:name-for-bindings="Anonymity_Modes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The list of initially requested anonymity modes on the channel. This + MUST NOT change, and is Requestable. + </tp:docstring> + </property> + + <property name="AnonymityMandatory" type="b" access="read" + tp:name-for-bindings="Anonymity_Mandatory"> + <tp:docstring> + Whether or not the anonymity settings are required for this channel. + This MUST NOT change, and is Requestable. + </tp:docstring> + </property> + + <property name="AnonymousID" type="s" access="read" + tp:name-for-bindings="Anonymous_ID"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This is the ID that the remote user of the channel MAY see + (assuming there's a single ID). For example, for SIP connections + where the From address has been scrambled by the CM, the scrambled + address would be available here for the client to see. This is + completely optional, and MAY be an empty string ("") in + cases where anonymity modes are not set, or the CM doesn't know + what the remote contact will see, or any other case where this + doesn't make sense.</p> + + <p>This MAY change over the lifetime of the channel, and SHOULD NOT + be used with the Request interface.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index 7545ff6f3..bd20f6ed3 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright> - <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -21,31 +21,57 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF"> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An interface that gives a Channel the ability to send DTMF events over + audio streams which have been established using the StreamedMedia channel + type. The event codes used are in common with those defined in <a + href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are + listed in the <tp:type>DTMF_Event</tp:type> enumeration. + </tp:docstring> + <method name="StartTone" tp:name-for-bindings="Start_Tone"> <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> - <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> + <tp:docstring>A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the tone SHOULD be sent to all + eligible streams in the channel.</tp:docstring> </arg> <arg direction="in" name="Event" type="y" tp:type="DTMF_Event"> <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring> </arg> + <tp:docstring> - Start sending a DTMF tone on this stream. Where possible, the tone - will continue until <tp:member-ref>StopTone</tp:member-ref> is called. - On certain protocols, it may - only be possible to send events with a predetermined length. In this - case, the implementation may emit a fixed-length tone, and the StopTone - method call should return NotAvailable. + <p>Start sending a DTMF tone to all eligible streams in the channel. + Where possible, the tone will continue until + <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols, + it may only be possible to send events with a predetermined length. In + this case, the implementation MAY emit a fixed-length tone, and the + StopTone method call SHOULD return NotAvailable.</p> + <tp:rationale> + The client may wish to control the exact duration and timing of the + tones sent as a result of user's interaction with the dialpad, thus + starting and stopping the tone sending explicitly. + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> - The given stream ID was invalid. + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - The requested event is not available on this stream. + There are no eligible audio streams. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. </tp:docstring> </tp:error> </tp:possible-errors> @@ -53,28 +79,136 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="StopTone" tp:name-for-bindings="Stop_Tone"> <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID"> - <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring> + <tp:docstring>A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the sending SHOULD be stoped in + all eligible streams in the channel.</tp:docstring> + </arg> + + <tp:docstring> + Stop sending any DTMF tones which have been started using the + <tp:member-ref>StartTone</tp:member-ref> or + <tp:member-ref>MultipleTones</tp:member-ref> methods. + If there is no current tone, this method will do nothing. + If MultipleTones was used, the client should not assume the + sending has stopped immediately; instead, the client should wait + for the StoppedTones signal. + <tp:rationale> + On some protocols it might be impossible to cancel queued tones + immediately. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Continuous tones are not supported by this stream. Deprecated, + since stream IDs are ignored. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones"> + <tp:added version="0.19.6" /> + <arg direction="in" name="Tones" type="s"> + <tp:docstring>A string representation of one or more DTMF + events.</tp:docstring> </arg> <tp:docstring> - Stop sending any DTMF tone which has been started using the - <tp:member-ref>StartTone</tp:member-ref> - method. If there is no current tone, this method will do nothing. + <p>Send multiple DTMF events to all eligible streams in the channel. + Each character in the Tones string must be a valid DTMF event + (as defined by + <a href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>). + Each tone will be played for a pre-defined number of milliseconds, + followed by a pause before the next tone is played. The + duration/pause is defined by the protocol or connection manager.</p> + <tp:rationale> + In cases where the client knows in advance the tone sequence it wants + to send, it's easier to use this method than manually start and stop + each tone in the sequence. + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> - The given stream ID was invalid. + The supplied Tones string was invalid. </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - Continuous tones are not supported by this stream. + There are no eligible audio streams. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. </tp:docstring> </tp:error> </tp:possible-errors> </method> + <property name="CurrentlySendingTones" + tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read"> + <tp:added version="0.19.6" /> + <tp:docstring> + Indicates whether there are DTMF tones currently being sent in the + channel. If so, the client should wait for + <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to + send more tones. + </tp:docstring> + </property> + + <property name="InitialTones" tp:name-for-bindings="Initial_Tones" + type="s" access="read"> + <tp:added version="0.19.6" /> + <tp:docstring> + <p>If non-empty in a channel request that will create a new channel, + the connection manager should send the tones immediately after + at least one eligible audio stream has been created in the + channel.</p> + + <p>This property is immutable (cannot change).</p> + </tp:docstring> + </property> + + <signal name="SendingTones" tp:name-for-bindings="Sending_Tones"> + <tp:added version="0.19.6" /> + <arg name="Tones" type="s"> + <tp:docstring>DTMF string (one or more events) that is to be played. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tone(s)are being sent to all eligible streams in the channel. + The signal is provided to indicating the fact that the streams are + currently being used to send one or more DTMF tones, so any other + media input is not getting through to the audio stream. It also + serves as a cue for the + <tp:member-ref>StopTone</tp:member-ref> method.</p> + </tp:docstring> + </signal> + + <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones"> + <tp:added version="0.19.6" /> + <arg name="Cancelled" type="b"> + <tp:docstring>True if the DTMF tones were actively cancelled via + <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tones have finished playing on streams in this channel.</p> + </tp:docstring> + </signal> + <tp:enum name="DTMF_Event" type="y"> <tp:enumvalue suffix="Digit_0" value="0"> <tp:docstring>0</tp:docstring> @@ -125,15 +259,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring>D</tp:docstring> </tp:enumvalue> </tp:enum> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An interface that gives a Channel the ability to send DTMF events over - audio streams which have been established using the StreamedMedia channel - type. The event codes used are in common with those defined in <a - href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are - listed in the <tp:type>DTMF_Event</tp:type> enumeration. - </tp:docstring> - </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 566e1166d..b33633543 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -314,6 +314,10 @@ USA.</p> <dd>The contact who sent the message. If 0 or omitted, the contact who sent the message could not be determined.</dd> + <dt>sender-nickname (s)</dt> + <dd>The nickname chosen by the sender of the message, which can be + different for each message in a conversation.</dd> + <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>) </dt> <dd>The type of message; if omitted, diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml new file mode 100644 index 000000000..5a0d540e5 --- /dev/null +++ b/spec/Channel_Interface_Service_Point.xml @@ -0,0 +1,85 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for channels + that can indicate when/if they are connected to some form + of service point. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.</p> + + <p>Note that while the majority of examples given in this + documentation are for GSM calls, they could just as easily be + SIP calls, GSM SMS's, etc.</p> + </tp:docstring> + + <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point" + type="(us)" tp:type="Service_Point" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This property is used to indicate that the channel target is a + well-known service point. Please note that the CM (or lower layers + of the stack or network) may forward the connection to other other + service points, which the CM SHOULD indicate via + <tp:member-ref>ServicePointChanged</tp:member-ref> + signal.</p> + + <p>This property SHOULD be set for channel requests that are + specifically targeting service points.</p> + </tp:docstring> + </property> + + <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point" + type="(us)" tp:type="Service_Point" access="read"> + <tp:docstring> + The service point that the channel is connected to. If the channel is + not connected to any service points, the CM MUST set the + <tp:type>Service_Point_Type</tp:type> field to None. + </tp:docstring> + </property> + + <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed"> + <tp:docstring> + <p>Emitted when a channel changes the service point that it's connected to. This + might be a new call being connected to a service, a call connected to + a service being routed to a different service + (ie, an emergency call being routed from a generic emergency PSAP to + a poison control PSAP), or any number of other things.</p> + + <p>Note that this should be emitted as soon as the CM has been notified + of the switch, and has updated its internal state. The CM MAY still + be in the process of connecting to the new service point.</p> + </tp:docstring> + + <arg name="ServicePoint" type="(us)" tp:type="Service_Point"> + <tp:docstring> + The new service point that is being used. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 4de78b400..1d59eb874 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -55,14 +55,11 @@ </property> <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" - type="x" tp:type="Unix_Timestamp64" access="read"> + type="x" tp:type="User_Action_Timestamp" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.</p> - <p>This corresponds to the _NET_WM_USER_TIME property in - <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> - <p>This property is set when the channel request is created, and can never change.</p> </tp:docstring> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index dacf906b1..f1d0f0e06 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -381,6 +381,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:rationale> </tp:docstring> </tp:flag> + + <tp:flag suffix="Muted" value="64"> + <tp:docstring> + The call has been muted by the local user, e.g. using the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content.Interface" + >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only be set if + there is at least one Content, and all Contents are locally muted; + it makes sense on calls in state Call_State_Pending_Receiver or + Call_State_Accepted. + </tp:docstring> + </tp:flag> </tp:flags> <property name="CallStateDetails" @@ -477,6 +488,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. rejected as busy, kicked from a conference by a moderator, etc.).</p> </tp:docstring> </tp:enumvalue> + + <tp:enumvalue suffix="Forwarded" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The call was forwarded. If known, the handle of the contact + the call was forwarded to will be indicated by the Actor member + of a <tp:type>Call_State_Reason</tp:type> struct.</p> + </tp:docstring> + </tp:enumvalue> </tp:enum> <tp:struct name="Call_State_Reason"> @@ -557,7 +576,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </arg> - <arg name="Call_State_Reason" type="(uus)"> + <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason"> <tp:docstring> The new value of the <tp:member-ref>CallStateReason</tp:member-ref> property. diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index c6edf3376..10a16bd69 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -106,6 +106,14 @@ matches closely related Text channels by their Bundle property. (This is use-case dis5)</p> </tp:rationale> + + <p>For service-activatable handlers, this property should be specified + in the handler's <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Handler] +BypassApproval=true +</pre> </tp:docstring> </property> @@ -264,6 +272,8 @@ org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true is to be handled for some reason not involving user action. Handlers SHOULD use this for focus-stealing prevention, if applicable. + This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> + but is unsigned for historical reasons. </tp:docstring> </arg> diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index f777a2a96..f4c11087d 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -119,9 +119,11 @@ properties as possible, given that constraint.</p> <p>In particular, the properties <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref> - and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref> MUST be included.</p> </tp:docstring> </arg> diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index a2256a753..912edaf4f 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -194,9 +194,17 @@ org.freedesktop.Telepathy.Channel.Requested b=true its <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p> - <p>When activatable client having this property disappears from the bus - and there are channels matching its ObserverChannelFilter, - ObserveChannels will be called immediately to reactivate it again.</p> + <p>When an activatable client having this property disappears from the + bus and there are channels matching its ObserverChannelFilter, + ObserveChannels will be called immediately to reactivate it + again. Such clients should specify this property in their + <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Observer] +Recover=true +</pre> + <tp:rationale> <p>This means that if an activatable Observer crashes, it will be restarted as soon as possible; while there is an unavoidable @@ -212,8 +220,8 @@ org.freedesktop.Telepathy.Channel.Requested b=true </tp:rationale> <p>When the ObserveChannels method is called due to observer recovery, - the "Observer_Info" dictionary will contain one extra item with key - "recovering" and boolean value of True.</p> + the <var>Observer_Info</var> dictionary will contain one extra item + mapping the key <code>"recovering"</code> to <code>True</code>.</p> </tp:docstring> </property> @@ -336,8 +344,11 @@ org.freedesktop.Telepathy.Channel.Requested b=true <dl> <dt><code>recovering</code> - b</dt> - <dd>True if ObserveChannels was called on existing channel due to - observer recovery, otherwise False. + <dd><code>True</code> if ObserveChannels was called for an existing + channel (due to the <tp:member-ref>Recover</tp:member-ref> + property being <code>True</code>); <code>False</code> or omitted + otherwise. + <tp:rationale> This allows observers to distinguish between new channels (the normal case), and existing channels that were given to the observer in order diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml new file mode 100644 index 000000000..5426b5d50 --- /dev/null +++ b/spec/Connection_Interface_Anonymity.xml @@ -0,0 +1,170 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Anonymity" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface to support anonymity settings on a per-connection basis. + This defines what personal identifying information a remote contact + may or may not see. For example, GSM might use this for CLIR, while + SIP might use this for privacy service requests.</p> + </tp:docstring> + + <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u"> + <tp:docstring> + <p>Flags for the various types of anonymity modes. These modes are solely to + inform the CM of the desired anonymous settings. It is up to the + CM to determine whether the anonymity modes should be handled within + the CM itself, or whether the network that a CM might be talking to + should be enforcing anonymity.</p> + + <p>CMs MAY support only a subset of these modes, and specific + connections MAY support none at all.</p> + </tp:docstring> + + <tp:flag value="1" suffix="Client_Info"> + <tp:docstring> + <p>Obscure any information that provides user identification, + user-agent identification or personal details. Examples of this + information might be GSM CallerID, SIP from address, various + informational email headers, etc.</p> + + <p>The CM should scrub/replace any of this information before + passing messages or data onto the network. Note that a CM which + has the option of obscuring the information at the CM or privacy + service level would choose both (anonymity services are opaque + to clients of this interface).</p> + + <p>Clients SHOULD NOT set both Client_Info and ShowClient_Info modes. + If they are set, the CM MUST respect Client_Info and ignore + Show_Client_Info.</p> + </tp:docstring> + </tp:flag> + + <tp:flag value="2" suffix="Show_Client_Info"> + <tp:docstring> + <p>Explicitly request showing of client information. In connection + context, this can be used to override service default. In channel + context, this overrides connection anonymity modes.</p> + <tp:rationale> + In GSM, it's possible to have CLIR enabled by default, and + explicitly suppress CLIR for a single phone call. + </tp:rationale> + + <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. + If they are set, the CM MUST respect Client_Info and ignore + ShowClientInfo. The CM MAY set both Client_Info and Show_Client_Info + in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate + its support for explicitly hiding and publicising client information. + </p> + </tp:docstring> + </tp:flag> + + <tp:flag value="4" suffix="Network_Info"> + <tp:docstring> + <p>Obscure any originating IP address information, contact URIs, + and anonymize all traffic involved with sending/receiving any + media streams or call content. + Examples of this include the "headers" portions of + <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as + well as the History-Info (described in + <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>) + for a SIP CM.</p> + + <p>This SHOULD have the effect of hiding address information from + the remote contact (ie, the contact cannot know what IP address + the session is originated from). Obviously the network still needs + to be able to route information between contacts, so this provides + no guarantees of what can be seen by intermediaries.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + + <property name="SupportedAnonymityModes" type="u" access="read" + tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes"> + <tp:docstring> + The anonymity modes supported by the CM for this connection. Once + Connection.Status has moved to Connected, this property MUST NOT change. + </tp:docstring> + </property> + + <property name="Mandatory" type="b" access="readwrite" + tp:name-for-bindings="Mandatory"> + <tp:docstring> + <p>This specifies whether or not the anonymity settings MUST be respected + by the CM and any intermediaries between the local and remote contacts. + If this is set to true but anonymity settings cannot be followed, then + the session MUST be denied with a + <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> error. + Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref> + SHOULD also set this property first (rather than accepting the CM's + default value).</p> + + <p>This property can also be set using a connection parameter in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, + see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p> + </tp:docstring> + </property> + + <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" + access="readwrite" tp:name-for-bindings="Anonymity_Modes"> + <tp:docstring> + <p>The currently enabled anonymity modes for the connection. Setting + has the effect of requesting new modes for the connection, and may + raise an error if the unsupported modes are set. Successfully changing + the modes will result in emmision of + <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p> + + <p>This property can also be set using a connection parameter in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, + see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + An unsupported mode was supplied. Supported modes are specified + in the SupportedAnonymityModes property, and this should be + checked prior to setting AnonymityModes. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </property> + + <signal name="AnonymityModesChanged" + tp:name-for-bindings="Anonymity_Modes_Changed"> + <tp:docstring> + Emitted when the anonymity mode has changed. + </tp:docstring> + + <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags"> + <tp:docstring> + The new anonymity modes for this connection. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index 10d8102f9..56f923170 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -231,7 +231,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <tp:contact-attribute name="caps" - type="a(usuu)" tp:type="Contact_Capability"> + type="a(usuu)" tp:type="Contact_Capability[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The same structs that would be returned by <tp:member-ref>GetCapabilities</tp:member-ref> diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml new file mode 100644 index 000000000..c2a25503a --- /dev/null +++ b/spec/Connection_Interface_Cellular.xml @@ -0,0 +1,82 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Cellular" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface is for various cellular things (GSM and/or CDMA) things that + aren't really applicable to other protocols.</p> + </tp:docstring> + + <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period" + type="u" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Define how long should the service centre try message delivery before + giving up, failing delivery and deleting the message. A value of 0 means + to use the service centre's default period.</p> + <p>The value specified is in seconds. Note that various protocols or + implementations may round the value up (eg. to a minute or hour + precision). The maximum validity period may vary depending on + protocol or provider.</p> + </tp:docstring> + </property> + + <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre" + type="s" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Address for the messaging service centre. Typically (as is the case + for GSM's SMSC), it's the ISDN / telephony address (ie. a phone number). + </tp:docstring> + </property> + + <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The International Mobile Subscriber Identifier, if it exists. This + would originate from a SIM card. If the IMSI is unknown, this will + contain an empty string ("").</p> + </tp:docstring> + </property> + + <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed"> + <tp:docstring> + Emitted when the IMSI for the connection changes. This sort of thing + is rare, but could happen on cellular phones that allow hot-swapping + of SIM cards. In the case of SIM swapping, this signal would be + emitted twice; the first time while the SIM is being ejected (with an + empty string), and the second time after a new SIM has been inserted + (assuming that the IMSI can be determined from the new SIM). + </tp:docstring> + + <arg name="IMSI" type="s"> + <tp:docstring> + The new IMSI value. This may be an empty string in the case where + the IMSI is being reset or removed. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml new file mode 100644 index 000000000..35465a76f --- /dev/null +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -0,0 +1,412 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"/> + <tp:added version="0.19.6">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections in which contacts can be placed in + user-defined groups.</p> + </tp:docstring> + + <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups" + access="read" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if each contact can be in at most one group; false if each + contact can be in many groups.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <property name="GroupStorage" tp:name-for-bindings="Group_Storage" + type="u" tp:type="Contact_Metadata_Storage_Type" access="read"> + <tp:docstring> + <p>Indicates the extent to which contacts' groups can be set and + stored.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <tp:contact-attribute name="groups" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The names of groups of which a contact is a member.</p> + + <p>Change notification is via + <tp:member-ref>GroupsChanged</tp:member-ref>, + <tp:member-ref>GroupRenamed</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> + </tp:docstring> + </tp:contact-attribute> + + <property name="Groups" type="as" access="read" + tp:name-for-bindings="Groups"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The names of all groups that currently exist. This may be a + larger set than the union of all contacts' <code>groups</code> + contact attributes, if the connection allows groups to be + empty.</p> + + <p>Change notification is via + <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupRenamed</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref>.</p> + </tp:docstring> + </property> + + <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created"> + <tp:docstring> + Emitted when new, empty groups are created. This will often be + followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that + add some members. + </tp:docstring> + + <arg name="Names" type="as"> + <tp:docstring>The names of the new groups.</tp:docstring> + </arg> + </signal> + + <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a group is renamed. If the group was not empty, + immediately after this signal is emitted, + <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal + that the members of that group were removed from the old name + and added to the new name.</p> + + <p>On connection managers where groups behave like tags, this signal + will probably only be emitted when + <tp:member-ref>RenameGroup</tp:member-ref> is called, and renaming a + group from another client MAY be signalled as a + <tp:member-ref>GroupsChanged</tp:member-ref> signal instead.</p> + + <tp:rationale> + <p>On protocols like XMPP, another resource "renaming a group" is + indistinguishable from changing contacts' groups individually.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Old_Name" type="s"> + <tp:docstring>The old name of the group.</tp:docstring> + </arg> + + <arg name="New_Name" type="s"> + <tp:docstring>The new name of the group.</tp:docstring> + </arg> + </signal> + + <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed"> + <tp:docstring> + Emitted when one or more groups are removed. If they had members at + the time that they were removed, then immediately after this signal is + emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal + that their members were removed. + </tp:docstring> + + <arg name="Names" type="as"> + <tp:docstring>The names of the groups.</tp:docstring> + </arg> + </signal> + + <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed"> + <tp:docstring> + Emitted when contacts' groups change. + </tp:docstring> + + <arg name="Contact" type="au" tp:type="Contact_Handle"> + <tp:docstring>The relevant contacts.</tp:docstring> + </arg> + + <arg name="Added" type="as"> + <tp:docstring>The names of groups to which the contacts were + added.</tp:docstring> + </arg> + + <arg name="Removed" type="as"> + <tp:docstring>The names of groups from which the contacts were + removed.</tp:docstring> + </arg> + </signal> + + <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given contact to the given groups (creating new groups + if necessary), and remove them from all other groups.</p> + + <tp:rationale> + <p>This is the easiest and most correct way to implement user + interfaces that display a single contact with a list of groups, + resulting in a user expectation that when they apply the changes, + the contact's set of groups will become exactly what was + displayed.</p> + </tp:rationale> + + <p>If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.</p> + + <tp:rationale> + <p>In protocols like XMPP where groups behave like tags, a group + with no members has no protocol representation.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> + <tp:docstring>The contact to alter.</tp:docstring> + </arg> + + <arg name="Groups" type="as" direction="in"> + <tp:docstring>The set of groups which the contact should be + in.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref> + is true and the list of groups has more than one + member.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given members to the given group (creating it if necessary), + and remove all other members.</p> + + <tp:rationale> + <p>This is the easiest and most correct way to implement user + interfaces that display a single group with a list of contacts, + resulting in a user expectation that when they apply the changes, + the groups's set of members will become exactly what was + displayed.</p> + </tp:rationale> + + <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, + this will also remove each member from their previous group.</p> + + <p>If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.</p> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members for the group. If this set is + empty, this method MAY remove the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="AddToGroup" tp:name-for-bindings="Add_To_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Add the given members to the given group, creating it if + necessary.</p> + + <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true, + this will also remove each member from their previous group.</p> + + <tp:rationale> + <p>This is good for user interfaces in which you can edit groups + via drag-and-drop.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsChanged</tp:member-ref> and + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members to include in the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove the given members from the given group.</p> + + <tp:rationale> + <p>This is good for user interfaces in which you can edit groups + via drag-and-drop.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to alter. If it does not exist, then it has + no members by definition, so this method SHOULD return + successfully.</tp:docstring> + </arg> + + <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in"> + <tp:docstring>The set of members to remove from the group. It is not + an error to remove members who are already not in the group. + If there are no members left in the group afterwards, the group MAY + itself be removed.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RemoveGroup" tp:name-for-bindings="Remove_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove all members from the given group, then remove the group + itself. If the group already does not exist, this method SHOULD + return successfully.</p> + + <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Group" type="s" direction="in"> + <tp:docstring>The group to remove.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RenameGroup" tp:name-for-bindings="Rename_Group"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Rename the given group.</p> + + <p>On protocols where groups behave like tags, this is an API + short-cut for adding all of the group's members to a group with + the new name, then removing the old group.</p> + + <tp:rationale> + <p>Otherwise, clients can't perform this operation atomically, even + if the connection could.</p> + </tp:rationale> + + <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or + <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from + this method call MUST be emitted before the method returns.</p> + </tp:docstring> + + <arg name="Old_Name" type="s" direction="in"> + <tp:docstring>The group to rename.</tp:docstring> + </arg> + + <arg name="New_Name" type="s" direction="in"> + <tp:docstring>The new name for the group.</tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Raised if <tp:member-ref>GroupStorage</tp:member-ref> + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist"> + <tp:docstring>Raised if there is no group with that + name.</tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring>Raised if there is already a group with the new + name.</tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index 91a948e6c..ce77a56af 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -504,6 +504,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ network traffic.</p> </tp:rationale> </tp:docstring> + + <tp:contact-attribute name="info" + type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same value that would be returned by + <tp:member-ref>GetContactInfo</tp:member-ref> for this contact. + Omitted from the result if the contact's info + is not known.</p> + </tp:docstring> + </tp:contact-attribute> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml new file mode 100644 index 000000000..3ded87083 --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,837 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.19.6">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections that have any concept of a list of + known contacts (roster, buddy list, friends list etc.)</p> + + <tp:rationale> + <p>On many protocols, there's a server-side roster (as in XMPP), + or a set of server-side lists that can be combined to form a + roster (as in MSN).</p> + + <p>In some protocols (like link-local XMPP), while there might not be + any server or roster, it's possible to list "nearby" contacts.</p> + + <p>In Telepathy 0.18 and older, we represented contact lists as a + collection of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >ContactList</tp:dbus-ref> channels. This is remarkably difficult to + work with in practice - every client that cares about contact lists + has to take the union of some hard-to-define set of these + channels - and conflicts with the idea that channels that cannot + be dispatched to a handler should be closed.</p> + </tp:rationale> + + <p>The list of contacts is not exposed as a D-Bus property; it can be + fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>. + </p> + + <tp:rationale> + <p>In some protocols, such as XMPP, the contact list may not be + available immediately. The + <tp:member-ref>GetContactListAttributes</tp:member-ref> method + will wait until the contact list is available before returning. + Using a method also allows extra attributes to be retrieved at + the same time.</p> + </tp:rationale> + </tp:docstring> + + <method name="GetContactListAttributes" + tp:name-for-bindings="Get_Contact_List_Attributes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return some contact attributes for a list of contacts somehow + associated with the user.</p> + + <p>This definition is deliberately vague: in practice, most user + interfaces should display some subset of this list, by filtering it + by some contact attributes (for instance, displaying all contacts + whose "subscribe" attribute is Yes is expected to be a common case). + This list MAY contain any contacts whatsoever, but MUST contain + at least the following:</p> + + <ul> + <li>all contacts whose "subscribe" attribute is Ask or Yes</li> + <li>all contacts whose "publish" attribute is Ask or Yes</li> + <li>all contacts with a persistently-stored stored alias, if + supported</li> + <li>all contacts in user-defined contact groups, if supported</li> + </ul> + + <p>This list does not need to contain every visible contact: for + instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear + here. Blocked contacts SHOULD NOT appear here either, unless they + are still stored in a persistent roster/contact list as well as + being blocked.</p> + + <tp:rationale> + <p>This is basically the union of the historical <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >ContactList</tp:dbus-ref> subscribe, publish and stored + channels.</p> + + <p>For example, XMPP, it's the roster; on link-local XMPP, it's the + set of visible users on the local network; on MSN, it's the union + of the forward and reverse buddy lists.</p> + + <p>An easy way for an application to display a contact list is to + call this method with at least this interface in the Interfaces + argument, then check which subset of contacts should be displayed + (perhaps based on their subscribe attribute, for instance) and display + them. Any additional information required to display the contact + list, like aliases or presence, can be retrieved at the same + time.</p> + + <p>In practice, most user interfaces for the contact list will + usually display a large proportion of this list + (for instance, most contacts on the contact list will usually + have subscribe=Yes in practice, so contact lists that display + subscribe=Yes contacts need to display almost the entire list), + so the overhead of returning information about too many contacts + is small.</p> + </tp:rationale> + + <p>This method SHOULD NOT return before the contact list has been + retrieved, on protocols where this is possible. As a result, + clients SHOULD use a longer-than-default timeout for this method + call, since retrieving the contact list can take a significant + time on some servers.</p> + + <tp:rationale> + <p>This makes it possible for clients to wait for the contact list. + For instance, on XMPP this method shouldn't return until the + roster has been retrieved, which is an asynchronous process. + However, on link-local XMPP you can't know when you have the + complete list, so this method would have to return immediately.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. Equivalent to the corresponding argument + to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Hold" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Whether to hold the handles on behalf of the calling process. + Equivalent to the corresponding argument to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + + <p><em>FIXME: if we do distributed refcounting, we should probably + rename this to 'Reference' and implement handle-refcounting + semantics first? On the other hand, if we make handles persist + for the lifetime of the connection, we can just remove this + parameter.</em></p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes, + equivalent to the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <tp:enum name="Presence_State" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A tristate indicating whether presence subscription is denied, + denied but pending permission, or allowed. The exact semantics + vary according to where this type is used.</p> + </tp:docstring> + + <tp:enumvalue suffix="No" value="0"> + <tp:docstring>Presence information cannot be seen.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Ask" value="1"> + <tp:docstring>Presence information cannot be seen, but permission + to see presence information has been requested.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Yes" value="2"> + <tp:docstring>Presence information can be seen.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:contact-attribute name="subscribe" + type="u" tp:type="Presence_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, this connection can + expect to receive their presence, along with any other information + that has the same access control.</p> + + <tp:rationale> + <p>This is subscription="from" or subscription="both" in XMPP, + the "forward list" on MSN, or the contact being "added to + the local user's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is No or Ask, the local user cannot generally + expect to receive presence from this contact. Their presence status + as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref> + is likely to be (Unknown, "unknown", ""), unless the local user + can temporarily see their presence for some other reason (for + instance, on XMPP, contacts seen in chatrooms will temporarily + have available presence).</p> + + <p>If this attribute is Ask, this indicates that the local user has + asked to receive the contact's presence at some time. It is + implementation-dependent whether contacts' subscribe attributes + can remain set to Ask, or are reset to No, when the connection + disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that we wishes to see a contact's + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have been + asked during the current session will ever have Ask status.</p> + </tp:rationale> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish" + type="u" tp:type="Presence_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, the local user's presence + is published to that contact, along with any other information that + shares an access-control mechanism with presence (depending on + protocol, server configuration and/or user configuration, this may + include avatars, "rich presence" such as location, etc.).</p> + + <tp:rationale> + <p>This is subscription="to" or subscription="both" in XMPP, + the "reverse list" on MSN, or the state of "being added to + the contact's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is No or Ask, the + local user's presence is not published to that contact; however, + if it is Ask, the contact has requested that the local user's + presence is made available to them.</p> + + <p>It is implementation-dependent whether contacts' publish + attributes can remain set to Ask, or are reset to No, when the + connection disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that a contact wishes to see our + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have asked + during the current session will ever have Ask status.</p> + </tp:rationale> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish-request" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the "publish" attribute is Ask, an optional message that was + sent by the contact asking to receive the local user's presence; + omitted if none was given.</p> + + <tp:rationale> + <p>If the contact asking to receive our presence is also using + Telepathy, this is the message they supplied as the Message + argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p> + </tp:rationale> + + <p>Otherwise, this SHOULD be omitted.</p> + </tp:docstring> + </tp:contact-attribute> + + <property name="SubscriptionsPersist" + tp:name-for-bindings="Subscriptions_Persist" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscriptions (in both directions) on this + connection are stored by the server or other infrastructure.</p> + + <tp:rationale> + <p>XMPP, MSN, ICQ, etc. all behave like this.</p> + </tp:rationale> + + <p>If false, presence subscriptions on this connection are not + stored.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record + of subscriptions, as described below. In link-local XMPP, + subscriptions are implicit (everyone on the local network receives + presence from everyone else) so nothing is ever stored.</p> + </tp:rationale> + + <p>If <tp:member-ref>CanChangeSubscriptions</tp:member-ref> + is true, Telepathy clients (e.g. user interfaces or address books) + MAY keep a record of permission to publish and requests to subscribe + locally, and attempt to restore it for each Connection. If + SubscriptionsPersist is false, clients MAY do this for all contacts; + if SubscriptionsPersist is true, clients SHOULD NOT change the state + of contacts that were not changed locally.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), SubscriptionsPersist is false, but + CanChangeSubscriptions is true. Presence will not be received + unless clients renew any subscriptions they have for each + connection, in the way described. There is no server-side storage, + so clients have no alternative but to maintain independent contact + lists.</p> + + <p>In protocols like XMPP and MSN, it may be useful for clients to + queue up subscription requests or removals made while offline and + process them next time the connection is online. However, clients + should only replay the changes, rather than resetting the contact + list to match a stored copy, to avoid overwriting changes that + were made on the server.</p> + </tp:rationale> + + <p>Clients that replay requests like this SHOULD do so by calling + AuthorizePublication to pre-approve publication of presence to the + appropriate contacts, followed by RequestSubscription to request the + appropriate contacts' presences.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <tp:enum name="Contact_Metadata_Storage_Type" type="u"> + <tp:docstring> + Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This connection cannot store this type of metadata at all, and + attempting to do so will fail with NotImplemented.</p> + + <tp:rationale> + <p>Link-local XMPP can't store aliases or group memberships at + all, and subscription and presence states are implicit (all + contacts on the local network have subscribe = publish = Yes + and no other contacts exist).</p> + + <p>As of April 2010, the XMPP server for Facebook Chat provides a + read-only view of the user's Facebook contacts, so it could also + usefully have this storage type.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed_Or_Pending" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Ask or Yes.</p> + + <tp:rationale> + <p>Contact aliases and groups on MSN have this behaviour.</p> + </tp:rationale> + + <p>If this type of metadata is set on a contact with subscribe=No, + the Connection MUST cache it until disconnected, and return it + if requested. If subscription to the contact's presence is + subsequently requested, making it possible to store this metadata, + the Connection MUST store the cached value at that time.</p> + + <tp:rationale> + <p>This supports the recommended calling pattern for adding a + new contact, in which alias and groups are set (without + necessarily waiting for a reply) before requesting the + contact's presence. Until the subscription request is + processed by the server, the alias and groups will be cached + in memory; when the subscription request has been processed, + the connection manager will store the metadata on the server.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Yes.</p> + + <tp:rationale> + <p>No service with this behaviour is currently known, but it's a + stricter form of Subscribed_Or_Pending.</p> + </tp:rationale> + + <p>If this type of metadata is set on a contact with subscribe != Yes, + the Connection MUST cache it until disconnected, and return it + if requested. If subscription to the contact's presence is + subsequently allowed, making it possible to store this metadata, + the Connection MUST store the cached value at that time.</p> + + <tp:rationale> + <p>The same rationale applies as for Subscribed_Or_Pending, + except that metadata must be stored until the subscription + request is not only processed by the server, but also allowed + by the remote user.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Anyone" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user can set this metadata for any valid contact identifier, + whether or not they have any presence subscription relationship + to it, and it will be stored on their contact list.</p> + + <tp:rationale> + <p>Contact aliases and groups on XMPP have this behaviour; it + is possible to put a contact in a group, or assign an alias + to them, without requesting that presence be shared.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Contact_Subscriptions" array-name=""> + <tp:docstring> + A single contact's subscribe, publish and publish-request attributes. + </tp:docstring> + + <tp:member name="Subscribe" type="u" tp:type="Presence_State"> + <tp:docstring> + The new value of the contact's "subscribe" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish" type="u" tp:type="Presence_State"> + <tp:docstring> + The new value of the contact's "publish" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish_Request" type="s"> + <tp:docstring> + The new value of the contact's "publish-request" attribute, + or the empty string if that attribute would be omitted. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Subscription_Map" array-name=""> + <tp:docstring> + A map from contacts to their subscribe, publish and publish-request + attributes. + </tp:docstring> + + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact's handle. + </tp:docstring> + </tp:member> + + <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions"> + <tp:docstring> + The contact's subscribe, publish and publish-request attributes. + </tp:docstring> + </tp:member> + </tp:mapping> + + <signal name="ContactsChanged" + tp:name-for-bindings="Contacts_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the contact list becomes available, when contacts' + basic stored properties change, when new contacts are added to the + list that would be returned by + <tp:member-ref>GetContactListAttributes</tp:member-ref>, + or when contact are removed from that list.</p> + + <tp:rationale> + <p>This provides change notification for that list, and for + contacts' "subscribe", "publish" and + "publish-request" attributes.</p> + </tp:rationale> + </tp:docstring> + + <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> + <tp:docstring> + The new subscribe, publish and publish-request attributes of all the + contacts that have been added, and all the contacts for which those + attributes have changed. + </tp:docstring> + </arg> + + <arg name="Removals" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts that have been removed from the list that would be + returned by + <tp:member-ref>GetContactListAttributes</tp:member-ref>. + This also implies that they have subscribe = No and publish = No; + contacts MUST NOT be listed both here and in Changes. + </tp:docstring> + </arg> + </signal> + + <property name="CanChangeSubscriptions" type="b" access="read" + tp:name-for-bindings="Can_Change_Subscriptions"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscription and publication can be changed + using the + <tp:member-ref>RequestSubscription</tp:member-ref>, + <tp:member-ref>AuthorizePublication</tp:member-ref> and + <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p> + + <p>If false, all of those methods will always fail; they SHOULD raise + the error org.freedesktop.Telepathy.Error.NotImplemented.</p> + + <tp:rationale> + <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is + implicitly published to everyone in the local subnet, so the user + cannot control their presence publication.</p> + </tp:rationale> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given contacts allow the local user to + subscribe to their presence, i.e. that their subscribe attribute + becomes Yes.</p> + + <p>Before calling this method on a connection where <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag, + user interfaces SHOULD obtain, from the user, an alias to + identify the contact in future, and store it using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >SetAliases</tp:dbus-ref>. + + The user MAY be + prompted using the contact's current self-assigned nickname, or + something derived from the contact's (presumably self-assigned) + identifier, as a default, but these names chosen by the contact + SHOULD NOT be used without user approval.</p> + + <tp:rationale> + <p>This is a generalization of + <a href="http://xmpp.org/extensions/xep-0165.html" + >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>) + to protocols other than XMPP. A reasonable user interface for + this, as used in many XMPP clients, is to have a text entry + for the alias adjacent to the text entry for the identifier + to add.</p> + </tp:rationale> + + <p>For contacts with subscribe=Yes, this method has no effect. + It MUST return successfully if all contacts are in this state.</p> + + <p>For contacts with subscribe=Ask, this method SHOULD send a new + request, with the given message, if allowed by the underlying + protocol.</p> + + <p>For contacts with subscribe=No, this method SHOULD request that + the contact allows the local user to subscribe to their presence; + in general, this will change their publish attribute from No + to Ask (although it could change directly from No to Yes in some + situations).</p> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + + <p>If the remote contact accepts the request, their subscribe + attribute will later change from Ask to Yes; if they explicitly + reject the request (in protocols that allow this), their subscribe + attribute will later change from Ask to No.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to whom requests are to be sent.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An optional plain-text message from the user, to send to those + contacts with the subscription request. The + <tp:member-ref>RequestUsesMessage</tp:member-ref> property + indicates whether this message will be used or ignored.</p> + + <p>Clients SHOULD NOT send a non-empty message without first giving + the user an opportunity to edit it.</p> + + <tp:rationale> + <p>These messages are typically presented to the remote contact + as if the user had typed them, so as a minimum, the user should be + allowed to see what the UI will be saying on their behalf.</p> + </tp:rationale> + + <p>Connections where this message is not useful MUST still allow it to + be non-empty.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="RequestUsesMessage" type="b" access="read" + tp:name-for-bindings="Request_Uses_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the Message parameter to + <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be + significant, and user interfaces SHOULD prompt the user for a + message to send with the request; a message such as "I would like + to add you to my contact list", translated into the local user's + language, might make a suitable default.</p> + + <tp:rationale> + <p>This matches user expectations in XMPP and ICQ, for instance.</p> + </tp:rationale> + + <p>If false, the parameter is ignored; user interfaces SHOULD avoid + prompting the user, and SHOULD pass an empty string to + RequestSubscription.</p> + + <tp:rationale> + <p><em>FIXME: is there any such protocol?</em></p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="AuthorizePublication" + tp:name-for-bindings="Authorize_Publication"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For each of the given contacts, request that the local user's + presence is sent to that contact, i.e. that their publish attribute + becomes Yes.</p> + + <p>For contacts with publish=Yes, this method has no effect; it + MUST return successfully if all contacts given have this state.</p> + + <p>For contacts with publish=Ask, this method accepts the + contact's request to see the local user's presence, changing + their publish attribute from Ask to Yes.</p> + + <p>For contacts with publish=No, if the protocol allows it, this + method allows the contacts to see the local user's presence even + though they have not requested it, changing their publish attribute + from No to Yes. Otherwise, it merely records the fact that + presence publication to those contacts is allowed; if any of + those contacts ask to receive the local user's presence + later in the lifetime of the connection, the connection SHOULD + immediately allow them to do so, changing their publish + attribute directly from No to Yes.</p> + + <tp:rationale> + <p>This makes it easy to implement the common UI policy that if + the user attempts to subscribe to a contact's presence, requests + for reciprocal subscription are automatically approved.</p> + </tp:rationale> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to authorize.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove the given contacts from the contact list entirely. It is + protocol-dependent whether this works, and under which + circumstances.</p> + + <p>If possible, this method SHOULD set the contacts' subscribe and + publish attributes to No, remove any stored aliases for those + contacts, and remove the contacts from the result of + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> + + <p>This method SHOULD succeed even if it was not possible to carry out + the request entirely or for all contacts (for instance, if there is an + outstanding request to subscribe to the contact's presence, and it's + not possible to cancel such requests). However, all signals that + immediately result from this method call MUST be emitted before it + returns, so that clients can interpret the result.</p> + + <tp:rationale> + <p>User interfaces removing a contact from the contact list are + unlikely to want spurious failure notifications resulting from + limitations of a particular protocol. However, emitting the + signals first means that if a client does want to check exactly + what happened, it can wait for the method to return (while + applying change-notification signals to its local cache of the + contact list's state), then consult its local cache of the + contact list's state to see whether the contact is still there.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' subscribe attribute to No, + i.e. stop receiving their presence.</p> + + <p>For contacts with subscribe=Ask, this attempts to cancel + an earlier request to subscribe to the contact's presence; for + contacts with subscribe=Yes, this attempts to + unsubscribe from the contact's presence.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unpublish" tp:name-for-bindings="Unpublish"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' publish attribute to No, + i.e. stop sending presence to them.</p> + + <p>For contacts with publish=Ask, this method explicitly rejects the + contact's request to subscribe to the user's presence; for + contacts with publish=Yes, this method attempts to prevent the + user's presence from being received by the contact.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index 73051f4b1..4c1c11937 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -1,78 +1,335 @@ <?xml version="1.0" ?> -<node name="/Connection_Interface_Forwarding" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> +<node name="/Connection_Interface_Forwarding" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2006 INdT </tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version.</p> - -<p>This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.</p> - -<p>You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding" - tp:causes-havoc='not well-tested'> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <signal name="ForwardingChanged" tp:name-for-bindings="Forwarding_Changed"> - <arg name="Forward_To" type="u" tp:type="Contact_Handle"> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This connection interface is for protocols that are capable of + signaling to remote contacts that incoming communication channels + should be instead sent to a separate contact. This might apply to + things such as call forwarding, for example.</p> + + <p>In some cases, a CM may register forwarding rules with an external + service; in those cases, it will never see the incoming channel, and + the forwarding will happen automatically.</p> + + <p>In other cases, the CM will handle the forwarding itself. When an + incoming channel is detected, the status of the local user will + determine whether or not a forwarding rule is matched. For some + rules, this MAY happen immediately (ie, if the user is Busy); for + others, there MAY be a timeout (in seconds) that must expire + before the forwarding rule is matched (the timeout is specified + by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p> + + <p>Once a forwarding rule is matched and any necessary timeouts have + expired, the CM can forward the incoming channel to the specified + handle. If for whatever reason the remote handle does not accept + the channel AND the CM supports multiple forwarding entries AND + any necessary timeouts have expired (specified by the next entry + in the list), the CM can forward the incoming channel to the next + handle in the entry list. This continues until the list is + exhausted, or the incoming channel is accepted.</p> + + <p>Note that the rule matches are only for the first entry in the + in the forwarding rule list. Once the incoming channel has been + forwarded, the next entry in the list (assuming one exists and + the contact that the channel has been forwarded to does not respond + after any necessary timeouts) is used regardless of the status of + the forwarded channel. The initial match rule might have been + Busy, whereas the contact that the channel has been forwarded to + might be offline. Even in this case, the Busy list is still + traversed until the channel is handled (or there are no more + forwarding entries in the list).</p> + + <p>For example, assuming the following dict for Forwarding_Rules:</p> + <pre> + ForwardingRules = { + Busy: ( initial-timeout: 30, [ + (handle: 3, timeout: 15), + (handle: 5, timeout: 20) + ]), + NoReply: ( initial-timeout: 15, [ + (handle: 5, timeout: 30), + (handle: 3, timeout: 20) + ]) + }</pre> + + <p>We can imagine a scenario where an incoming channel is detected, + the media stream is available (ie, not Busy), + and the local user is online. While the CM is waiting for the local user to + accept the channel, it looks at NoReply's first timeout value. After 15s if + the local user hasn't accepted, the CM forwards the channel to Handle #5. The + CM then waits 30s for Handle #5 to accept the channel. If after 30s it does + not, the CM forwards the incoming channel to Handle #3, which will have + 20s to accept the channel.</p> + </tp:docstring> + + <tp:enum name="Forwarding_Condition" type="u"> + <tp:docstring> + The various forwarding conditions that are supported by this interface. + In general, the conditions should not overlap; it should be very clear + which rule would be chosen given a CM's behavior with an incoming + channel. The exception to this is Unconditional, + which will override all other rules. + </tp:docstring> + + <tp:enumvalue value="0" suffix="Unconditional"> <tp:docstring> - An integer contact handle to forward communication to + Incoming channels should always be forwarded. Note that setting this + will override any other rules. If not set, other rules will + be checked when an incoming communication channel is detected. </tp:docstring> - </arg> - <tp:docstring> - Emitted when the forwarding contact handle for this connection has been - changed. An zero handle indicates forwarding is disabled. + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Busy"> + <tp:docstring> + <p>The incoming channel should be forwarded if a busy signal is + detected. What defines "Busy" is CM-specific (perhaps a single + resource is already in use, or a user's status is set to Busy + <tp:type>Connection_Presence_Type</tp:type>).</p> + <p>If initial timeout is specified for Busy condition and call + waiting is not supported by the service, the timeout will be + ignored.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="No_Reply"> + <tp:docstring> + The incoming channel should be forwarded if the local user doesn't + accept it within the specified amount of time. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="3" suffix="Not_Reachable"> + <tp:docstring> + The incoming channel should be forwarded if the user is offline. + This could be a manual setting (the user has chosen to set their + presence to offline or invisible) or something specified by the + underlying network (the user is not within range of a cell tower). + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Forwarding_Rule_Entry" + array-name="Forwarding_Rule_Entry_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A forwarding rule entry. These MAY be chained together + for CMs that support chaining of forwards (in other words, + a forwarding rule may have multiple entries; if the contact + in the first entry doesn't respond, the incoming channel + might be forwarded to the contact in the second entry).</p> + + <p>For CMs and protocols that don't support chaining of + entries, only the first entry would be used.</p> </tp:docstring> - </signal> - <method name="GetForwardingHandle" - tp:name-for-bindings="Get_Forwarding_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle"> + + <tp:member type="u" name="Timeout"> <tp:docstring> - An integer contact handle to whom incoming communication is forwarded + <p>The length of time (in seconds) to wait the contact to respond + to the forwarded channel. This MAY be ignored by the CM if it + isn't supported by the underlying network/protocol for the + specific status of the remote contact (for example, a GSM call + that is forwarded may return Not_Reachable immediately without + waiting for the timeout value to expire).</p> + <p>A value of 0 means the condition can match immediately. A + value of MAX_UINT32 means that the CM's default should be + used.</p> </tp:docstring> - </arg> + </tp:member> + + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The contact to forward an incoming channel to. If the handle + doesn't point to anything (e.g. points to a phone number that + doesn't exist), the entry SHOULD be skipped. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Forwarding_Rule_Chain"> <tp:docstring> - Returns the current forwarding contact handle, or zero if none is set. + A chain of forwarding rules and an initial timeout after which + the rules are applied. </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - </tp:possible-errors> - </method> - <method name="SetForwardingHandle" - tp:name-for-bindings="Set_Forwarding_Handle"> - <arg direction="in" name="Forward_To" type="u" tp:type="Contact_Handle"> + + <tp:member type="u" name="InitialTimeout"> + <tp:docstring>Initial timeout for the rule.</tp:docstring> + </tp:member> + + <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring>The forwarding targets (an array of type + <tp:type>Forwarding_Rule_Entry</tp:type>). + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Forwarding_Rule_Map" array-name=""> + <tp:docstring>A dictionary whose keys are forwarding conditions and + whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs. + </tp:docstring> + + <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> + <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain" + name="Rule_Chain" /> + </tp:mapping> + + <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name=""> + <tp:docstring>A dictionary whose keys are forwarding conditions and + whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> + for the condition. + </tp:docstring> + <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" /> + <tp:member type="u" name="Chain_Length" /> + </tp:mapping> + + <property name="SupportedForwardingConditions" type="a{uu}" access="read" + tp:type="Supported_Forwarding_Conditions_Map" + tp:name-for-bindings="Supported_Forwarding_Conditions"> + <tp:docstring> + <p> + A map of forwarding conditions supported on this connection to + maximum number of <tp:type>Forwarding_Rule_Entry</tp:type> + supported for the specific condition. + <tp:rationale> + When forwarding is done by the provider, different providers + might support different chain sizes, or provider and local + implementation chain sizes might differ. + </tp:rationale> + </p> + </tp:docstring> + </property> + + <property name="ForwardingRules" type="a{u(ua(uu))}" access="read" + tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules"> + <tp:docstring> + <p>The current forwarding rules that are enabled for this connection. + Forwarding rules each contain an array of type + <tp:type>Forwarding_Rule_Entry</tp:type>.</p> + </tp:docstring> + </property> + + <signal name="ForwardingRuleChanged" + tp:name-for-bindings="Forwarding_Rule_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p> + + <p>By the time this is emitted, the property MUST have been updated + with the new rules being active. If any protocol/network + requests must be made, they should be completed before the signal + is emitted.</p> + </tp:docstring> + + <arg name="Condition" type="u" tp:type="Forwarding_Condition"> + <tp:docstring> + The condition of the forwarding rule that's been changed. + </tp:docstring> + </arg> + + <arg name="Timeout" type="u"> + <tp:docstring> + The new initial timeout for the rule. + </tp:docstring> + </arg> + + <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> <tp:docstring> - An integer contact handle to forward incoming communications to + The new (and as of the emission of the signal, currently active) + forwards. The order is relevant; those at the lowest array index + are used first. </tp:docstring> </arg> + </signal> + + <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule"> <tp:docstring> - Set a contact handle to forward incoming communications to. A zero - handle disables forwarding. + Update the forwarding rules. </tp:docstring> + + <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition"> + <tp:docstring> + <p>The forwarding rule to override. Note that this SHOULD not affect + other rules; setting a rule that overrides others (such as + Forwarding_Rule_Unconditional) will not modify other rules. This + means that when a client sets Forwarding_Rule_Busy and then + temporarily sets Forwarding_Rule_Unconditional, the + Forwarding_Rule_Busy rule will retain settings after + Forwarding_Rule_Unconditional, has been unset.</p> + + <p>If the CM has no choice but to adjust multiple rules after a call + to this function (ie, due to the network or protocol forcing such + behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref> + signals for each changed rule. The order of the signals is + implementation-dependent, with the only requirement that the + last signal is for the rule that was originally requested to have + been changed (e.g. if Unconditional automatically modifies + Busy and NoReply, three + separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the + last signal being for Forwarding_Rule_Unconditional).</p> + + <p>Each forwarding condition will occur no more than once in + the rule array. Setting a rule will overwrite the old rule + with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring> + The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to + activate for the rule. An empty array will effectively disable the + rule. + </tp:docstring> + </arg> + + <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]"> + <tp:docstring> + The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>). + This is the list of entries that is being replaced with the call to + <tp:member-ref>SetForwardingRule</tp:member-ref>. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The specified Condition is not supported by this connection, + or the number of chained + <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should + be checked prior to calling + <tp:member-ref>SetForwardingRule</tp:member-ref>. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + A Handle that has been supplied is invalid. + </tp:docstring> + </tp:error> </tp:possible-errors> </method> - <tp:docstring> - A connection interface for services which can signal to contacts - that they should instead contact a different user ID, effectively - forwarding all incoming communication channels to another contact on - the service. - </tp:docstring> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml index fdc622ea8..6c69a80c5 100644 --- a/spec/Connection_Interface_Location.xml +++ b/spec/Connection_Interface_Location.xml @@ -365,7 +365,14 @@ 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.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The user's server does not support publishing their own location. + If it is possible to determine this ahead of time, the + <code>Can_Set</code> flag will not be set in + <tp:member-ref>SupportedLocationFeatures</tp:member-ref>. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> </tp:possible-errors> </method> @@ -385,6 +392,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ supported).</tp:docstring> </property> + <property name="SupportedLocationFeatures" + tp:name-for-bindings="Supported_Location_Features" + type="u" tp:type="Location_Features" access="read"> + <tp:added version="0.19.6"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Indicates the Location features supported by this connection. This + property MAY be undefined before <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref> + becomes <code>Connected</code>, but MUST remain constant thereafter. + </tp:docstring> + </property> + + <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature"> + <tp:flag suffix="Can_Set" value="1"> + <tp:docstring> + Indicates that setting your own location with + <tp:member-ref>SetLocation</tp:member-ref> is supported on this + connection. + </tp:docstring> + </tp:flag> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Flags describing the Location features which may be supported on any + given connection. + </tp:docstring> + </tp:flags> + <tp:contact-attribute name="location" type="a{sv}" tp:type="Location"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml index c74dd59f8..cfe67a8f8 100644 --- a/spec/Connection_Interface_Mail_Notification.xml +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -159,9 +159,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:struct> <tp:struct name="Mail_Address" array-name="Mail_Address_List"> - <tp:docstring> - A pair (name, address) representing an e-mail address, - such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A pair (name, address) representing an e-mail address, + such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At + least one of name and address MUST be provided. A missing element will + be represented by the empty string.</p> + <tp:rationale> + <p>The CM should provide as much information as possible, but not all + protocols provide both the displayed name and the address. (If a + protocol doesn't provide either, it should omit the appropriate + field from the <tp:type>Mail</tp:type> entirely.)</p> + </tp:rationale> </tp:docstring> <tp:member type="s" name="Name"> <tp:docstring>The displayed name corresponding to the e-mail diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml new file mode 100644 index 000000000..b0b34b678 --- /dev/null +++ b/spec/Connection_Interface_Service_Point.xml @@ -0,0 +1,135 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections whose channels may be able to indicate + specific they are connected to some form + of service station. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.</p> + </tp:docstring> + + <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List"> + <tp:member type="(us)" tp:type="Service_Point" name="ServicePoint"> + <tp:docstring> + The service point. + </tp:docstring> + </tp:member> + <tp:member type="as" name="ServiceIDs"> + <tp:docstring> + A list of IDs that are mapped to this service. This is provided as + a convenience for the UIs, but the preferred method for + requesting channel to a service is by setting <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT">InitialServicePoint</tp:dbus-ref> + property in channel request. + </tp:docstring> + </tp:member> + <tp:docstring> + <p>Description of a service point and IDs which are mapped to id.</p> + + <p>An example Service Point info for GSM emergency calls (callable through + "911" and "112") could look like:</p> + +<pre> + ServicePointInfo = ( + ServicePoint: ( + ServicePointType: 1 (Emergency), + ServicePoint: "urn:service:sos" + ), + ServiceIDs: [ "911", "112" ] + ) +</pre> + </tp:docstring> + </tp:struct> + + <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points" + type="a((us)as)" tp:type="Service_Point_Info[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The list of all (known) service points. + </tp:docstring> + </property> + + <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed"> + <arg name="ServicePoints" type="a((us)as)" tp:type="Service_Point_Info[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new list of service points.</p> + </tp:docstring> + </arg> + <tp:docstring> + Indicate that the list of known service points (or their IDs) have + changed, presenting the new list. + </tp:docstring> + </signal> + + <tp:struct name="Service_Point"> + <tp:docstring>A service point.</tp:docstring> + <tp:member type="u" name="ServicePointType" tp:type="Service_Point_Type"> + <tp:docstring> + The service type. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Service"> + <tp:docstring> + String representation of the service point. The representation is + service specific; it may be <tp:type>Uniform_Resource_Name</tp:type> + or may be in some other form. Empty, unused or unknown value is + represented by "". + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum name="Service_Point_Type" type="u"> + <tp:docstring> + The various types of service points the channel might connect to. + </tp:docstring> + + <tp:enumvalue value="0" suffix="None"> + <tp:docstring> + The service point is not used/available. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Emergency"> + <tp:docstring> + The service point is a generic emergency point. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Counseling"> + <tp:docstring> + The service point is some kind of counseling service (ie, mental health + or child-services counseling). + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:simple-type name="Uniform_Resource_Name" type="s"> + <tp:docstring>Uniform Resource Name as specified by + <a href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>.</tp:docstring> + </tp:simple-type> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Makefile.am b/spec/Makefile.am index 91f378c3a..a1d08d293 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -5,6 +5,7 @@ EXTRA_DIST = \ all.xml \ Call_Content.xml \ Call_Content_Interface_Media.xml \ + Call_Content_Interface_Mute.xml \ Call_Content_Codec_Offer.xml \ Call_Stream.xml \ Call_Stream_Interface_Media.xml \ @@ -14,6 +15,7 @@ EXTRA_DIST = \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ + Channel_Interface_Anonymity.xml \ Channel_Interface_Call_State.xml \ Channel_Interface_Chat_State.xml \ Channel_Interface_Conference.xml \ @@ -26,6 +28,7 @@ EXTRA_DIST = \ Channel_Interface_Mergeable_Conference.xml \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ + Channel_Interface_Service_Point.xml \ Channel_Interface_Splittable.xml \ Channel_Interface_Transfer.xml \ Channel_Interface_Tube.xml \ @@ -49,11 +52,15 @@ EXTRA_DIST = \ Client_Observer.xml \ Connection_Future.xml \ Connection_Interface_Aliasing.xml \ + Connection_Interface_Anonymity.xml \ Connection_Interface_Avatars.xml \ Connection_Interface_Balance.xml \ Connection_Interface_Capabilities.xml \ + Connection_Interface_Cellular.xml \ Connection_Interface_Contact_Capabilities.xml \ + Connection_Interface_Contact_Groups.xml \ Connection_Interface_Contact_Info.xml \ + Connection_Interface_Contact_List.xml \ Connection_Interface_Contacts.xml \ Connection_Interface_Forwarding.xml \ Connection_Interface_Location.xml \ @@ -62,6 +69,7 @@ EXTRA_DIST = \ Connection_Interface_Privacy.xml \ Connection_Interface_Renaming.xml \ Connection_Interface_Requests.xml \ + Connection_Interface_Service_Point.xml \ Connection_Interface_Simple_Presence.xml \ Connection_Manager.xml \ Connection.xml \ diff --git a/spec/all.xml b/spec/all.xml index a5ea1c4d2..591efb52b 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.19.5</tp:version> +<tp:version>0.19.6</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> @@ -42,13 +42,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection.xml"/> <xi:include href="Connection_Future.xml"/> <xi:include href="Connection_Interface_Aliasing.xml"/> + <xi:include href="Connection_Interface_Anonymity.xml"/> <xi:include href="Connection_Interface_Avatars.xml"/> <xi:include href="Connection_Interface_Balance.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> + <xi:include href="Connection_Interface_Cellular.xml"/> <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> + <xi:include href="Connection_Interface_Contact_Groups.xml"/> <xi:include href="Connection_Interface_Contact_Info.xml"/> + <xi:include href="Connection_Interface_Contact_List.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> + <xi:include href="Connection_Interface_Forwarding.xml"/> <xi:include href="Connection_Interface_Location.xml"/> + <xi:include href="Connection_Interface_Service_Point.xml"/> <xi:include href="Connection_Interface_Mail_Notification.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> <xi:include href="Connection_Interface_Renaming.xml"/> @@ -99,6 +105,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ depending on its type: </p> </tp:docstring> + <xi:include href="Channel_Interface_Anonymity.xml"/> <xi:include href="Channel_Interface_Call_State.xml"/> <xi:include href="Channel_Interface_Chat_State.xml"/> <xi:include href="Channel_Interface_Conference.xml"/> @@ -107,6 +114,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Group.xml"/> <xi:include href="Channel_Interface_Hold.xml"/> <xi:include href="Channel_Interface_HTML.xml"/> + <xi:include href="Channel_Interface_Service_Point.xml"/> <xi:include href="Channel_Interface_Password.xml"/> <xi:include href="Channel_Interface_Media_Signalling.xml"/> <xi:include href="Channel_Interface_Mergeable_Conference.xml"/> @@ -124,6 +132,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:section name="Calls"> <xi:include href="Call_Content.xml"/> <xi:include href="Call_Content_Interface_Media.xml"/> + <xi:include href="Call_Content_Interface_Mute.xml"/> <xi:include href="Call_Content_Codec_Offer.xml"/> <xi:include href="Call_Stream.xml"/> <xi:include href="Call_Stream_Interface_Media.xml"/> @@ -185,8 +194,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> -<!-- Never implemented, insufficient (needs conditions) -<xi:include href="Connection_Interface_Forwarding.xml"/> --> <!-- Never implemented, vague <xi:include href="Connection_Interface_Privacy.xml"/> --> <!-- Causes havoc, never implemented, unclear requirements diff --git a/spec/errors.xml b/spec/errors.xml index 22a629baf..0137e776c 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -1,5 +1,28 @@ <?xml version="1.0" ?> <tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The D-Bus errors used in Telepathy all start with + <code>org.freedesktop.Telepathy.Error.</code>. They are used in + D-Bus messages of type ERROR, and also as plain strings annotated with + the <tp:type>DBus_Error_Name</tp:type> type.</p> + + <p>In principle, any method can raise any error (this is a general fact + of IPC). For instance, generic D-Bus errors starting with + <code>org.freedesktop.DBus.Error.</code> will occur in some + situations.</p> + + <p>Telepathy methods can also raise implementation-specific errors to + indicate specialized failure conditions. For better interoperability, + if a suitable Telepathy error exists, it should be preferred.</p> + + <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code> + is reserved for use by the D-Bus client implementation in telepathy-qt4, + which uses it to represent certain error situations that did not involve + a D-Bus ERROR message. These errors are defined and documented as part of + telepathy-qt4's C++ API, and should not be used on D-Bus.</p> + </tp:docstring> + <tp:error name="Network Error"> <tp:docstring> Raised when there is an error reading from or writing to the network. diff --git a/spec/generic-types.xml b/spec/generic-types.xml index d4dce1552..c017ba595 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -165,4 +165,34 @@ </tp:member> </tp:struct> + <tp:simple-type name="User_Action_Timestamp" type="x"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which an user action occurred. This type has the 2 + following special values:</p> + + <p>0: the action doesn't involve any user action. Clients + SHOULD avoid stealing focus when presenting the channel.</p> + + <p>MAX_INT64: clients SHOULD behave as though the user action happened + at the current time, e.g. a client MAY request that its window gains + focus. + </p> + + <tp:rationale> + <p>This can be used by clients that can't know the X server time like + command line applications for example.</p> + </tp:rationale> + + <p>For all the other values it corresponds to the time of the user + action. Clients SHOULD use this for focus-stealing prevention, + if applicable. + Note that the time is dependant on the local + environment and so is not necessarily a wall-clock time. + For example in an X environment it's expected to be the X timestamp + of events. + This corresponds to the _NET_WM_USER_TIME property in + <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> + </tp:docstring> + </tp:simple-type> + </tp:generic-types> |