From 8eb4a0a4a5a928def54d5c569cbc023340e0fb90 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 14 Sep 2010 19:04:06 +0100 Subject: Update to stable spec 0.20.0 --- spec/Authentication_TLS_Certificate.xml | 195 +++++----- spec/Channel_Interface_Conference.xml | 491 +++++++++++++++++------- spec/Channel_Interface_Mergeable_Conference.xml | 6 +- spec/Channel_Interface_Splittable.xml | 9 +- spec/Channel_Type_Server_TLS_Connection.xml | 7 +- spec/Client_Handler_Future.xml | 4 +- spec/Connection.xml | 6 +- spec/Connection_Interface_Client_Types.xml | 22 +- spec/Connection_Interface_Power_Saving.xml | 41 +- spec/all.xml | 2 +- 10 files changed, 499 insertions(+), 284 deletions(-) (limited to 'spec') diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml index 709ea282c..db1d76fd7 100644 --- a/spec/Authentication_TLS_Certificate.xml +++ b/spec/Authentication_TLS_Certificate.xml @@ -17,9 +17,8 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - (draft 1) + + (as stable API) This object represents a TLS certificate. @@ -41,10 +40,81 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + +

Struct representing one reason why a TLS certificate was rejected.

+

Since there can be multiple things wrong with a TLS certificate, + arrays of this type are used to represent lists of reasons for + rejection. In that case, the most important reason SHOULD be placed + first in the list.

+ + + + +

The value of the TLS_Certificate_Reject_Reason enumeration for + this certificate rejection. + + Clients that do not understand the Error member, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + +

+ + + + + +

The DBus error name for this certificate rejection.

+

This MAY correspond to the value of the Reason member, + or MAY be a more specific D-Bus error name, perhaps implementation-specific.

+ + + + + +

Additional information about why the certificate was rejected. + This MAY also include one or more of the following well-known keys:

+

+

+
user-requested (b)
+
True if the error was due to an user-requested rejection of + the certificate; False if there was an unrecoverable error in the + verification process.
+
expected-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname that + the server certificate was expected to have.
+
certificate-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname of + the certificate that was presented. + +

For instance, if you try to connect to gmail.com but are presented + with a TLS certificate issued to evil.example.org, the error details + for Hostname_Mismatch MAY include:

+ 
+                {
+                  'expected-hostname': 'gmail.com',
+                  'certificate-hostname': 'evil.example.org',
+                }
+
+ +
+
debug-message (s)
+
Debugging information on the error, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances
+
+

+ + + + The possible states for a TLSCertificate.DRAFT + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate object. @@ -149,75 +219,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - +

If the State is Rejected, - the reason why the certificate was rejected; this MAY correspond to - the RejectReason, or MAY be a more - specific D-Bus error name, perhaps implementation-specific.

+ an array of TLS_Certificate_Rejection + structures containing the reason why the certificate is rejected.

If the State is not Rejected, this property is not meaningful, and SHOULD be set to an empty - string.

- - - - - -

If the State is Rejected, - additional information about why the certificate was rejected.

-

If the State is not Rejected, - this property is not meaningful and SHOULD be set to an empty - map.

-

The additional information MAY also include - one or more of the following well-known keys:

-
-
user-requested (b)
-
True if the error was due to an user-requested rejection of - the certificate; False if there was an unrecoverable error in the - verification process.
-
expected-hostname (s)
-
If the rejection reason is Hostname_Mismatch, the hostname that - the server certificate was expected to have.
-
certificate-hostname (s)
-
If the rejection reason is Hostname_Mismatch, the hostname of - the certificate that was presented. - -

For instance, if you try to connect to gmail.com but are presented - with a TLS certificate issued to evil.example.org, the error details - for Hostname_Mismatch MAY include:

- 
-              {
-                'expected-hostname': 'gmail.com',
-                'certificate-hostname': 'evil.example.org',
-              }
-
- -
-
debug-message (s)
-
Debugging information on the error, corresponding to the - message part of a D-Bus error message, which SHOULD NOT be - displayed to users under normal circumstances
-
- - - - - - If the State is Rejected, the - reason why the certificate was rejected. - - Clients that do not understand the RejectError, - which may be implementation-specific, can use this property to - classify rejection reasons into common categories. - - Otherwise, this property is not meaningful, and SHOULD be set to - Unknown. + array.

+

The first rejection in the list MAY be assumed to be + the most important; if the array contains more than one + element, the CM MAY either use the values after the first, + or ignore them.

 @@ -252,19 +266,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The State of this certificate has changed to Rejected. - + - The new value of RejectReason. - - - - - The new value of RejectError. - - - - - The new value of RejectDetails + The new value of the Rejections property. @@ -279,24 +283,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Rejects this certificate. - - - The new value of RejectReason. - - - - - The new value of RejectError. - - - - - The new value of RejectDetails. + + +

The new value of the Rejections property.

+

This MUST NOT be an empty array.

 + + + + Raised when the method is called on an object whose State + is not Pending, or when the provided rejection list is empty. + + + diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml index 92d962d69..afb99c5ca 100644 --- a/spec/Channel_Interface_Conference.xml +++ b/spec/Channel_Interface_Conference.xml @@ -20,16 +20,18 @@ 02110-1301, USA.

- (draft 1) + name="org.freedesktop.Telepathy.Channel.Interface.Conference"> + (as stable API)

An interface for multi-user conference channels that can "continue - from" one or more individual channels.

+ from" one or more individual channels. This could be used to invite + other contacts to an existing 1-1 text conversation, combine two phone + calls into one conference call, and so on, with roughly the same API in + each case.

This interface addresses freedesktop.org (GSM-compatible conference calls) and bug #24939 (upgrading calls and chats to multi-user). - See those bugs for rationale and use cases.

- -

Examples of usage:

- -

Active and held GSM calls C1, C2 can be merged into a single - channel Cn with the Conference interface, by calling - CreateChannel({...ChannelType: ...Call, - ...InitialChannels: [C1, C2]}) - which returns Cn.

- -

An XMPP 1-1 conversation C1 can be continued in a newly created - multi-user chatroom Cn by calling - CreateChannel({...ChannelType: ...Text, - ...InitialChannels: [C1]}) - which returns Cn.

- -

An XMPP 1-1 conversation C1 can be continued in a specified - multi-user chatroom by calling - CreateChannel({...ChannelType: ...Text, ...HandleType: ROOM, - ...TargetID: 'telepathy@conf.example.com', - ...InitialChannels: [C1]}) - which returns a Conference channel.

- -

Either of the XMPP cases could work for Call channels, to - upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases - could in principle work for link-local XMPP (XEP-0174).

- -

The underlying switchboard representing an MSN 1-1 conversation C1 - with a contact X can be moved to a representation as a nameless - chatroom, Cn, to which more contacts can be invited, by calling - CreateChannel({...ChannelType: ...Text, - ...InitialChannels: [C1]}) - which returns Cn. C1 SHOULD remain open, with no underlying - switchboard attached. If X establishes a new switchboard with the - local user, C1 SHOULD pick up that switchboard rather than letting - it create a new channel. - [FIXME: should it?] - Similarly, if the local user sends a message in C1, then - a new switchboard to X should be created and associated with C1.

- -

XMPP and MSN do not natively have a concept of merging two or more - channels C1, C2... into one channel, Cn. However, the GSM-style - merging API can be supported on XMPP and MSN, as an API short-cut - for upgrading C1 into a conference Cn (which invites the - TargetHandle of C1 into Cn), then immediately inviting the - TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

- -

With a suitable change of terminology, Skype has behaviour similar - to MSN.

+ See those bugs for more rationale and use cases.

 +

Existing channels are upgraded by requesting a new channel of the same + ChannelType, + listing the channels to be merged into the new conference in the + InitialChannels property of the request. + If InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, + ad-hoc conferences to a set of contacts may be created by requesting a + channel, specifying + InitialInviteeHandles and/or + InitialInviteeIDs to be the contacts in + question. A request may specify these alongside + InitialChannels, to simultaneously + upgrade a channel to a conference and invite others to join it.

+ +

Channels with this interface MAY also implement MergeableConference.DRAFT + to support merging more 1-1 channels into an ongoing conference. + Similarly, 1-1 channels MAY implement Splittable.DRAFT to + support being broken out of a Conference channel.

+

The Group MAY have channel-specific handles for participants; - clients SHOULD support both Conferences that have channel-specific handles, - and those that do not.

+ >Group interface on Conference channels MAY use + channel-specific handles for participants; clients SHOULD support + both Conferences that have channel-specific handles, and those that + do not.

In the GSM case, the Conference's Group interface MAY have - channel-specific handles, to reflect the fact that the identities of - the participants might not be known - it can be possible to know that - there is another participant in the Conference, but not know who - they are. - [FIXME: fact check from GSM gurus needed] -

+ channel-specific handles, to represent the fact that the same + phone number may be in a conference twice (for instance, it could be + the number of a corporate switchboard).

In the XMPP case, the Conference's Group interface SHOULD have channel-specific handles, to reflect the fact that the participants @@ -132,6 +108,164 @@ be misleading.

 +

Examples of usage

+ +

A pair of 1-1 GSM calls C1 and C2 can be merged + into a single conference call by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Call, + ...InitialChannels: [C1, C2] + }) +
+ +

which returns a new channel Cn implementing the conference + interface. (As a quirk of GSM, both 1-1 will cease to function normally + until they are Split + from the conference, or the conference ends.)

+ +

An XMPP 1-1 conversation C3 (with + chris@example.com, say) can be continued in a newly created + multi-user chatroom by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3] + }) +
+ +

Or, to invite emily@example.net to join the newly-created MUC + at the same time:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3], + ...InitialInviteeIDs: ['emily@example.net'] + }) +
+ +

To continue C3 in a particular multi-user + chatroom (rather than the implementation inventing a unique name for + the room), call:

+ +
+ EnsureChannel({ + ...ChannelType: ...Text, + ...TargetHandleType: ...Room, + ...TargetID: 'telepathy@conf.example.com', + ...InitialChannels: [C3] + }) +
+ +

Note the use of EnsureChannel — if a channel for + telepathy@conf.example.com is already open, this SHOULD be + equivalent to inviting chris@example.com to the existing + channel.

+ +

In the above cases, the text channel C3 SHOULD remain open + and fully functional (until explicitly closed by a client); new + incoming 1-1 messages from chris@example.com SHOULD appear in + C3, and messages sent using C3 MUST be relayed + only to chris@example.com.

+ + +

If there is an open 1-1 text channel with a contact, in every + other situation new messages will appear in that channel. Given + that the old channel remains open — which is the least surprising + behaviour, and eases us towards a beautiful world where channels + never close themselves — it stands to reason that it should be + where new messages from Chris should appear. On MSN, creating a + conference from C3 should migrate the underlying + switchboard from C3 to the new channel; this is an + implementation detail, and should not affect the representation on + D-Bus. With a suitable change of terminology, Skype has the same + behaviour.

+ +

If the current handler of that channel doesn't want this to happen + (maybe it transformed the existing tab into the group chat window, + and so there'd be no UI element still around to show new messages), + then it should just Close the + old 1-1 channel; it'll respawn if necessary.

+ + +

Either of the XMPP cases could work for Call channels, to + upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases + could in principle work for link-local XMPP (XEP-0174).

+ +

XMPP and MSN do not natively have a concept of merging two or more + channels C1, C2... into one channel, Cn. However, the GSM-style + merging API can be supported on XMPP and MSN, as an API short-cut + for upgrading C1 into a conference Cn (which invites the + TargetHandle of C1 into Cn), then immediately inviting the + TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

+ +

Sample RequestableChannelClasses

+ +

A GSM connection might advertise the following channel class for + conference calls:

+ +
+ +( Fixed = {
+    ...ChannelType: + ...StreamedMedia
+  },
+  Allowed = [ InitialChannels, + InitialAudio + ]
+) + +
+ +

This indicates support for starting audio-only conference calls by + merging two or more existing channels (since + InitialInviteeHandles and + InitialInviteeIDs are not allowed).

+ +

An XMPP connection might advertise the following classes for ad-hoc + multi-user text chats:

+ +
+ +( Fixed = {
+    ...ChannelType: + ...Text
+  },
+  Allowed = [ InitialChannels, + InitialInviteeHandles, + InitialInviteeIDs, + InvitationMessage + ]
+),
+( Fixed = {
+    ...ChannelType: + ...Text,
+    ...TargetHandleType: + Room
+  },
+  Allowed = [ TargetHandle, + TargetID,
+              InitialChannels, + InitialInviteeHandles, + InitialInviteeIDs, + InvitationMessage + ]
+) + +
+ +

The first class indicates support for starting ad-hoc (nameless) chat + rooms, upgraded from existing 1-1 channels and/or inviting new + contacts, along with a message to be sent along with the invitations. + The second indicates support for upgrading to a particular named chat + room.

 TargetHandleType = CONTACT.

-

This property MUST NOT be requestable. - [FIXME: or would it be better for this one, and not IC, to be - requestable?] -

+

This property MUST NOT be requestable; instead, the + InitialChannels property may be + specified when requesting a channel.

+ + +

This is consistent with requesting + InitialInviteeHandles and + InitialInviteeIDs, rather than + requesting Group.Members + and some hypothetical ID version of that property.

+

Change notification is via the ChannelMerged and @@ -166,6 +308,22 @@ The channel that was added to Channels. + + + A new channel-specific handle for the TargetHandle of + Channel, as will appear in + OriginalChannels, or 0 if a + global handle is used for + Channel's TargetHandle on the Group interface + of this channel. + + + + Channel's immutable properties. + @@ -176,14 +334,24 @@ namespace="org.freedesktop.Telepathy.Channel.Interface" >Splittable.DRAFT.Split method.

-

[FIXME: relative ordering of this vs. Closed? Do we - care?]

+

If a channel is removed because it was closed, Closed should be emitted + before this signal.

The channel that was removed from Channels. + + + + Additional information about the removal, which may include + the same well-known keys as the Details argument of + MembersChangedDetailed, with the same semantics. + + This property SHOULD be requestable. Omitting it from a request is equivalent to providing it with an empty list as value. Requests - where its value has at least two elements SHOULD be expected to - succeed on any implementation of this interface.

- -

Whether a request with 0 or 1 elements in the list will succeed is - indicated by SupportsNonMerges.

+ where its value has at least two channel paths SHOULD be expected to + succeed on any implementation of this interface. If + InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, then requests with zero + or one channel paths SHOULD also succeed; otherwise, clients SHOULD + NOT make requests with zero or one paths for this property.

-

In GSM, a pair of calls can be merged into a conference. In XMPP - and MSN, you can create a new chatroom, or upgrade one 1-1 channel - into a chatroom; however, on these protocols, it is also possible - to fake GSM-style merging by upgrading the first channel, then - inviting the targets of all the other channels into it.

+

In GSM, a pair of calls can be merged into a conference, but you + can't start a conference call from zero or one existing calls. In + XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 + channel into a chatroom; however, on these protocols, it is also + possible to fake GSM-style merging by upgrading the first channel, + then inviting the targets of all the other channels into it.

If possible, the Channels' states SHOULD @@ -213,9 +386,7 @@ them in this property's value or by calling MergeableConference.DRAFT.Merge on them. - [FIXME: there's nothing in RequestableChannelClasses yet - to say what will happen, see #24906 comment 6]

+ >MergeableConference.DRAFT.Merge on them.

In Jingle, nothing special will happen to merged calls. UIs MAY @@ -223,10 +394,6 @@ the desired behaviour; this SHOULD always work. Not doing an implicit hold/unhold seems to preserve least-astonishment.

-

[FIXME: check whether ring supports faking Hold on both - channels, as it probably should: see #24906 comment 6] -

-

In GSM, the calls that are merged go into a state similar to Hold, but they cannot be unheld, only split from the conference call using A list of additional contacts invited to this conference when it was created.

-

This property SHOULD be requestable, and appear in the allowed +

If it is possible to invite new contacts when creating a conference + (as opposed to merging several channels into one new conference + channel), this property SHOULD be requestable, and appear in the allowed properties in RequestableChannelClasses, in all connection - managers that can implement its semantics (in practice, this is - likely to mean exactly those connection managers where - SupportsNonMerges will be true).

+ >RequestableChannelClasses. Otherwise, this property + SHOULD NOT be requestable, and its value SHOULD always be the empty + list.

+ + +

On GSM you have to place a 1-1 call before you can merge it into a + conference; on the other hand, you can invite new contacts to XMPP + Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a + 1-1 channel with them first.

+

If included in a request, the given contacts are automatically invited into the new channel, as if they had been added with @@ -326,8 +501,8 @@

A list of additional contacts invited to this conference when it was created.

-

This property SHOULD be requestable as an alternative to, or - combined with, InitialInviteeHandles. +

This property SHOULD be requestable if and only if + InitialInviteeHandles is requestable. Its semantics are the same, except that it takes a list of the string representations of contact handles; invitations are sent to any contact present in either or both of these properties.

@@ -369,60 +544,92 @@ - + -

[FIXME: needs a better name; or perhaps it could be implied - by InitialInviteeHandles being requestable in XMPP/MSN but not in - GSM?]

- -

If true, requests with InitialChannels - omitted, empty, or one element long should be expected to succeed.

- -

This property SHOULD appear in RequestableChannelClasses for - conference channels if and only if its value on those channels will - be true.

- - -

Putting this in RequestableChannelClasses means clients can find - out whether their request will succeed early enough to do - something about it.

- -

In XMPP, you can request a channel of type ROOM without - incorporating any 1-1 chats at all - indeed, this is the normal - way to do it - or as a continuation of a single 1-1 chat, and then - invite other people in later.

- -

The sense of this property is a bit awkward, but it avoids making it - an anti-capability. If the sense were inverted, then its presence in - RequestableChannelClasses would imply that the protocol lacks - a feature; as it stands, it is additive. (Contrast with - ImmutableStreams, which is the wrong way around for - backwards-compatibility reasons.)

- +

On GSM conference calls, it is possible to have the same phone + number in a conference twice; for instance, it could be the number of + a corporate switchboard. This is represented using channel-specific + handles; whether or not a channel uses channel-specific handles is + reported in Group.GroupFlags. + The Group.HandleOwners + property specifies the mapping from opaque channel-specific handles + to actual numbers; this property specifies the original 1-1 channel + corresponding to each channel-specific handle in the conference.

+ +

In protocols where this situation cannot arise, such as XMPP, + this property MAY remain empty.

+ +

For example, consider this situation:

+ +
    +
  1. Place a call (with path /call/to/simon) to the contact + +441234567890 (which is assigned the handle h, + say), and ask to be put through to Simon McVittie;
    2. +
  2. Put that call on hold;
    3. +
  3. Place another call (with path /call/to/jonny) to + +441234567890, and ask to be put + through to Jonny Lamb;
    4. +
  4. Request a new channel with + InitialChannels: + ['/call/to/simon', '/call/to/jonny'].
    5. +
+ +

The new channel will have the following properties, for some handles + s and j:

+ +
+ {
+ ...Group.GroupFlags: + Channel_Specific_Handles | (other flags),
+ ...Group.Members: + [self_handle, s, j],
+ ...Group.HandleOwners: + { s: h, j: h },
+ ...InitialChannels: + ['/call/to/simon', '/call/to/jonny'],
+ ...Channels: + ['/call/to/simon', '/call/to/jonny'],
+ ...OriginalChannels: + { s: '/call/to/simon', j: '/call/to/jonny' },
+ # ...standard properties like ChannelType: Group elided...
+ } +
-

If false, InitialChannels SHOULD be - supplied in all requests for this channel class, and contain at least - two channels. Requests where this requirement is not met SHOULD fail - with NotImplemented. -

- - -

In GSM, you can only make a conference call by merging at least - two channels. - [FIXME: the CM could conceivably fake it, but that would be - rather nasty] -

- +

Change notification is via the + ChannelMerged and + ChannelRemoved signals: if + Channel_Specific_Handle in the former is non-zero, this + property SHOULD be updated to map that handle to the merged channel's + path.

 + + + + A channel-specific handle for a participant in this conference. + + + + + The object path of Channels + representing the original 1-1 channel with + Channel_Specific_Handle. + + + + + A mapping from members of a conference to the original 1-1 channel with + that contact, if any. See + OriginalChannels for details. + + diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml index 989ffacf5..03e89683c 100644 --- a/spec/Channel_Interface_Mergeable_Conference.xml +++ b/spec/Channel_Interface_Mergeable_Conference.xml @@ -23,7 +23,7 @@ name="org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT" tp:causes-havoc="experimental"> (draft 1) - +

An interface for multi-user conference channels that can have @@ -50,11 +50,11 @@

The given channel SHOULD be added to Conference.DRAFT.Channels if and only if the + >Conference.Channels if and only if the underlying protocol signals the merge in some way. It MUST NOT be added to Conference.DRAFT.InitialChannels (to preserve + >Conference.InitialChannels (to preserve immutability).

diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml index 063565e8c..7509c9c89 100644 --- a/spec/Channel_Interface_Splittable.xml +++ b/spec/Channel_Interface_Splittable.xml @@ -28,7 +28,7 @@

An interface for channels that can be made conceptually part of a Conference.DRAFT, and can then be detached from that + >Conference, and can then be detached from that conference.

@@ -45,14 +45,11 @@

Request that this channel is removed from any Conference.DRAFT of which it is a part.

+ >Conference of which it is a part.

This implies that the media streams within the conference are put on hold and the media streams within the member channel leaving the - conference are unheld. - [FIXME: or, maybe it'd be less surprising if it didn't do - this?] -

+ conference are unheld.

 diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml index 7b1202a01..efab49451 100644 --- a/spec/Channel_Type_Server_TLS_Connection.xml +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -18,9 +18,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - (draft 1) + + (as stable API) @@ -48,7 +47,7 @@ tp:name-for-bindings="ServerCertificate">

A TLSCertificate.DRAFT + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate containing the certificate chain as sent by the server, and other relevant information.

This property is immutable.

diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml index 776fa4f3a..da31fadc3 100644 --- a/spec/Client_Handler_Future.xml +++ b/spec/Client_Handler_Future.xml @@ -39,9 +39,9 @@

If true, channels destined for this handler that have the Conference.DRAFT interface, with a channel that + >Conference interface, with a channel that was previously handled by the same client process in their - InitialChannels property, should bypass the approval stage. In effect, this is a weaker form of

Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances
-
expected-hostname (s), certificate-hostname (s)
-
The same details defined in TLSCertificate.DRAFT.RejectDetails -
+
user-requested (b), expected-hostname (s), certificate-hostname (s)
+
The same details defined in TLS_Certificate_Rejection.
 diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml index 879095e7c..fc5c7b8c7 100644 --- a/spec/Connection_Interface_Client_Types.xml +++ b/spec/Connection_Interface_Client_Types.xml @@ -56,21 +56,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + other words, the returned client types are those for the resource whose + presence will be retreived using the + SimplePresence + interface.

+ +

For example, if a contact has two resources:

    -
  • one his phone, with presence "available", and
    • -
  • one his pc, with presence "busy",
    • +
  • their phone, with presence "available"; and
    • +
  • their pc, with presence "busy";

then the methods in this interface will return an array (with - one element: "phone") as the client types as that is the more - available resource. If some time later his phone's presence - moves to "away", then the + one element: "phone") as the client types because that is the more + available resource. If at some later time the contact's phone's presence + changes to "away", the ClientTypesUpdated signal will - notify that his client type have changed from "phone" to "pc", + notify that the contact's client types attribute has changed from + ["phone"] to ["pc"], because "busy" is a more available presence than "away".

 diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml index 30b25f403..ae82d2fa2 100644 --- a/spec/Connection_Interface_Power_Saving.xml +++ b/spec/Connection_Interface_Power_Saving.xml @@ -23,20 +23,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

An interface for telling the connection when to enter and - leave power saving mode.

+

Some protocols support mechanisms for reducing bandwidth usage—and + hence power usage, on mobile devices—when the user is not directly + interacting with their IM client. For instance, Google Talk's XMPP + server supports queueing incoming presence updates at the client's + instruction; the client can instruct the server to deliver all + outstanding presence updates at a later time. This interface may be + used to instruct the connection manager to enable and disable such + protocol-level features when a screensaver is activated, the device + screen is locked, and so on, by calling the + SetPowerSaving method.

-

Power saving mode should be used when the user is not - directly interacting with the interface. For example, when - the screen saver is active, or when device screen is - locked.

- -

Connection managers should implement this feature in a way - that is not noticeable by end users. For example, a protocol - might allow server-side blocking presence updates from - contacts to reduce network chatter. This would not affect the - user, since they are not interacting with their device when it - is in power saving mode.

+

Enabling power saving SHOULD NOT change behaviour in any way + that is noticable to a user not actively interacting with their client. + For example, delaying presence updates somewhat is unlikely to be + noticed by a user not staring at their device waiting for a contact to + come online; on the other hand, requesting that the server queue + incoming messages would be noticable by the user, so is not an + acceptable effect of calling + SetPowerSaving.

 @@ -45,7 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Depending on the device's activity level, the - connection can have it's power saving mode turned on or off.

+ connection can have its power saving mode turned on or off.

Errors raised by this method indicate that power saving could not be @@ -62,7 +67,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - True when activating power saving, false when deactivating. + True if protocol-level power saving features should be + activated; False if they should be de-activated. @@ -79,7 +85,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

The current state of power saving. Change notifications is via the +

True if protocol-level power saving features are + currently activated. This property can be changed using the + SetPowerSaving method; change + notifications is via the PowerSavingChanged signal.

 diff --git a/spec/all.xml b/spec/all.xml index 2a7673bb7..e92a5542e 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.12 +0.20.0 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation -- cgit v1.2.1