From 4209eecdb536dc92f831020ad3504537103f7a7f Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Thu, 15 Apr 2010 21:53:21 +0100 Subject: Update to spec 0.19.4 (Observer.Recover) --- spec/Channel_Interface_Conference.xml | 2 +- spec/Channel_Type_Contact_Search.xml | 4 +- spec/Client_Observer.xml | 58 ++++++++- spec/Connection_Interface_Contact_Info.xml | 152 +++++++++++++++++++----- spec/Connection_Interface_Mail_Notification.xml | 23 +++- spec/all.xml | 2 +- 6 files changed, 198 insertions(+), 43 deletions(-) (limited to 'spec') diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml index 2441a7d9e..92d962d69 100644 --- a/spec/Channel_Interface_Conference.xml +++ b/spec/Channel_Interface_Conference.xml @@ -270,7 +270,7 @@ invited into the new channel, as if they had been added with Group.AddMembers(InitialInviteeHandles, - InvitationMessage immediately after + InvitationMessage) immediately after the channel was created.

diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 5f5bd4bf1..195d97be7 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -388,9 +388,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

An array of fields representing information about this contact, in the same format used in the ContactInfo.DRAFT + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo interface. It is possible that a separate call to RequestContactInfo + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo would return more information than this signal provides.

This array SHOULD include the x-telepathy-identifier diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 35e6d91d5..a2256a753 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -180,6 +180,43 @@ org.freedesktop.Telepathy.Channel.Requested b=true + + + When using telepathy-mission-control, version 5.4.0 or later is + needed for this property to be useful. + + + +

If true, upon the startup of this observer, ObserveChannels + will be called for every already existing channel matching + its ObserverChannelFilter

+ +

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.

+ +

This means that if an activatable Observer crashes, it will + be restarted as soon as possible; while there is an unavoidable + possibility that it will miss some events during this process + (particularly Text + messages), this window of event loss is kept to a minimum.

+ +

Non-activatable observers can't take advantage of this + mechanism, but setting this property on a non-activatable + observer does allow it to "catch up" on channels that are + currently active at the time that it starts up.

+ + +

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.

+ + +

Called by the channel dispatcher when channels in which the @@ -294,10 +331,23 @@ org.freedesktop.Telepathy.Channel.Requested b=true -

Additional information about these channels. No keys are - currently defined.

- -

If keys are defined for this dictionary, all will be optional; +

Additional information about these channels. Currently defined + keys are:

+ +
+
recovering - b
+
True if ObserveChannels was called on existing channel due to + observer recovery, otherwise False. + + This allows observers to distinguish between new channels (the normal + case), and existing channels that were given to the observer in order + to catch up on previous events (perhaps after a previous instance of + the same observer crashed). + +
+
+ +

All defined keys for this dictionary are optional; observers MAY safely ignore any entry in this dictionary.

 diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index d08545466..b77293514 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -17,9 +17,8 @@ Lesser General Public License for more details.

License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

- - (as a draft) + + (as stable API) @@ -110,6 +109,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +
label
+
A free-form street address for the contact, formatted as a + single value (with embedded newlines where necessary) suitable for + printing on an address label
+
tel
A telephone number for the contact.
@@ -124,9 +128,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + An integer handle for the contact whose info has changed. @@ -197,10 +209,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Request information on several contacts at once. This SHOULD only return cached information, omitting handles for which no information is - cached from the returned map. For contacts without cached information, - the information SHOULD be requested from the network, with the result - signalled later by ContactInfoChanged. + cached from the returned map. + + + + + + + Integer handles for contacts. + + + + Retrieve information for the given contact, requesting it from the + network if an up-to-date version is not cached locally. This method + SHOULD return immediately, emitting + ContactInfoChanged when the contacts' + updated contact information is returned. + + + This method allows a client with cached contact information to + update its cache after a number of days. + + + + + Retrieve information for a contact, requesting it from the network if it is not cached locally. + + + This method is appropriate for an explicit user request to show + a contact's information; it allows a UI to wait for the contact + info to be returned. + + + + The contact's information could not be retrieved. @@ -262,7 +306,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - Flags defining the behaviour of contact information on this protocol. @@ -282,8 +326,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Indicates that the protocol pushes all contacts' information to the connection manager without prompting. If set, - RequestContactInfo will not cause a - network roundtrip and ContactInfoChanged will be emitted whenever contacts' information changes. @@ -309,10 +351,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - An integer representing the bitwise-OR of flags on this connection. - This property should be constant over the lifetime of a connection. + tp:type="Contact_Info_Flags" tp:name-for-bindings="Contact_Info_Flags"> + +

An integer representing the bitwise-OR of flags on this + connection.

+ +

This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.

+ + +

Some XMPP servers, like Facebook Chat, do not allow the vCard to + be changed (and so would not have the Can_Set flag). Whether the + user's server is one of these cannot necessarily be detected until + quite late in the connection process.

+ + @@ -328,8 +382,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The set of vCard type parameters which may be set on this field. If this list is empty and the - Contact_Info_Field_Flag_Parameters_Mandatory - flag is unset, any vCard type parameters may be used. + Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type + parameters may be used. @@ -352,10 +406,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.ContactInfoFlags does not contain the - Can_Set Contact_Info_Flag.

+ Can_Set flag.

-

For example, an implementation of XEP-0054, which defines a mapping - of vCards to XML for use over XMPP, would set this property to the +

For example, a protocol in which arbitrary vCards were stored + as-is would set this property to the empty list. A protocol whose notion of contact information is one each of personal phone number, mobile phone number, location, email address and date of birth, with no attributes allowed on each piece @@ -364,22 +418,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. [ - ('tel', ['home'], Parameters_Mandatory, 1), - ('tel', ['cell'], Parameters_Mandatory, 1), - ('adr', [], Parameters_Mandatory, 1), - ('bday', [], Parameters_Mandatory, 1), - ('email', ['internet'], Parameters_Mandatory, 1), + ('tel', ['type=home'], Parameters_Exact, 1), + ('tel', ['type=cell'], Parameters_Exact, 1), + ('adr', [], Parameters_Exact, 1), + ('bday', [], Parameters_Exact, 1), + ('email', ['type=internet'], Parameters_Exact, 1), ]

A protocol which allows users to specify up to four phone numbers, which may be labelled as personal and/or mobile, would set this - property to [ ('tel', ['home', 'cell'], 0, 4), ].

+ property to + [ ('tel', ['type=home', 'type=cell'], 0, 4), ].

Studying existing IM protocols shows that in practice protocols allow either a very restricted set of fields (such as MSN, which - seems to correspond roughly to the largest example above) or - something mapping 1-1 to vCard (such as XMPP).

+ seems to correspond roughly to the largest example above), or + something mapping 1:1 to a large subset of vCard (such as XMPP's + XEP-0054).

+ + +

This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.

+ + +

Some XMPP servers, like Google Talk, only allow a small subset of + the "vcard-temp" protocol. Whether the user's server is one of + these cannot be detected until quite late in the connection + process.

 @@ -389,7 +456,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Flags describing the behaviour of a vCard field. - +

If present, exactly the parameters indicated must be set on this field; in the case of an empty list of parameters, this implies that @@ -411,6 +478,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Contact_Info_Fields forming a structured representation of a vCard (as defined by RFC 2426), using field names and semantics defined therein.

+ +

On some protocols, information about your contacts is pushed to you, + with change notification; on others, like XMPP, the client must + explicitly request the avatar, and has no way to tell whether it has + changed without retrieving it in its entirety. This distinction is + exposed by ContactInfoFlags containing + the Push flag.

+ +

On protocols with the Push flag set, UIs can connect to + ContactInfoChanged, call + GetContactInfo once at login for the set + of contacts they are interested in, and then be sure they will receive + the latest contact info. On protocols like XMPP, clients can do the + same, but will receive (at most) opportunistic updates if the info is + retrieved for other reasons. Clients may call + RequestContactInfo or + RefreshContactInfo to force a contact's + info to be updated, but MUST NOT do so unless this is either in + response to direct user action, or to refresh their own cache after a + number of days.

+ + +

We don't want clients to accidentally cause a ridiculous amount of + network traffic.

+ diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml index 35678c2f9..c74dd59f8 100644 --- a/spec/Connection_Interface_Mail_Notification.xml +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -353,17 +353,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.If Thread_Based appears in the MailNotificationFlags, this property counts the number of threads, not the number of mails.

+ +

Note that this count MAY be bigger than the number of items in + UnreadMails. See + UnreadMails for more details.

- A array of unread Mails. Change notification is via - UnreadMailsChanged. This property is - only useful if Supports_Unread_Mails is set in - MailNotificationFlags; otherwise, it MUST be - an empty list. +

An array of unread Mails. Change notification is + via UnreadMailsChanged. This property + is only useful if Supports_Unread_Mails is set in + MailNotificationFlags; otherwise, it + MUST be an empty list.

+

The array size MAY be shorter than + UnreadMailCount.

+ +

Some servers may limits the amount of detailed e-mails sent. This + can significantly reduce the network traffic for large inbox. For + this reason, it is normal that + UnreadMailCount be bigger or equal + to the size of this array.

+ diff --git a/spec/all.xml b/spec/all.xml index 0ec47089a..9ae5b3db7 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> Telepathy D-Bus Interface Specification -0.19.3 +0.19.4 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation -- cgit v1.2.1