From 11f06e38a50fffe3ef02540e09123aeca4113200 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 20 Jul 2010 17:27:15 +0100 Subject: Update spec to 0.19.10 --- spec/Account.xml | 30 ++++-- spec/Channel.xml | 67 ++++++++---- spec/Channel_Interface_Group.xml | 28 +++++- spec/Channel_Interface_Messages.xml | 12 +++ spec/Channel_Type_Contact_Search.xml | 55 +++++----- spec/Channel_Type_Streamed_Media.xml | 168 +++++++++++++++++++++++-------- spec/Connection_Interface_Anonymity.xml | 32 +++--- spec/Connection_Interface_Cellular.xml | 81 +++++++++------ spec/Connection_Interface_Forwarding.xml | 10 ++ spec/Connection_Manager.xml | 4 +- spec/Protocol.xml | 5 +- spec/Protocol_Interface_Avatars.xml | 2 +- spec/Protocol_Interface_Presence.xml | 2 +- spec/all.xml | 2 +- 14 files changed, 351 insertions(+), 147 deletions(-) (limited to 'spec') diff --git a/spec/Account.xml b/spec/Account.xml index 2bce393ee..5917c6f0b 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -330,7 +330,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

If any of the changed parameters' Conn_Mgr_Param_Flags include - DBus_Property, the change will be applied to the + DBus_Property, the change will be applied immediately to + the corresponding D-Bus Property on the active Connection, if there is one. Changes to other parameters will not take effect until the next time the account @@ -372,14 +373,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - A list of the names of parameters with changes that will not take - effect until the account is reconnected (this may be empty, e.g. if - all the parameters are D-Bus properties or parameters for which the - account manager has specific support). User interfaces that - require "instant apply" semantics MAY call - Reconnect in response to receiving - a non-empty list. + +

If all of the parameters had the DBus_Property flag, + the empty list, signifying that no reconnection is required for the + new parameters to take effect. For example, if the only parameter + updated is ...Cellular.MessageValidityPeriod, + the new value can be applied immediately to the connection.

+ +

Otherwise, a list of the names of parameters with changes that + will not take effect until the account is reconnected. User + interfaces that require "instant apply" semantics MAY call + Reconnect in response to receiving a + non-empty list. For example, if the caller updates both + ...Anonymity.AnonymityMandatory + and require-encryption, the former can be applied to the + current connection, but the latter needs a reconnect to take + effect, so this method should return + ["require-encryption"].

diff --git a/spec/Channel.xml b/spec/Channel.xml index 0fedf6896..897b68353 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -451,7 +451,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Channel.Type.ContactList - which represents a list of people (such as a buddy list) or a Channel.Type.Text which represents a channel over which textual messages are sent and received.

@@ -472,31 +472,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

Each channel may have an immutable handle associated with it, which - may be any handle type, such as a contact, room or list handle, - indicating that the channel is for communicating with that handle.

- -

If a channel does not have a handle (an "anonymous channel" with - Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it - means that the channel is defined by some other terms, such as it - may be a transient group defined only by its members as visible - through the Channel.Interface.Group - interface.

- -

Other optional interfaces can be implemented to indicate other available +

Each channel has a number of immutable properties (which cannot vary + after the channel has been announced with NewChannels), + provided to clients in the + ObserveChannels, + AddDispatchOperation and + HandleChannels + methods to permit immediate identification of the channel. This interface + contains immutable properties common to all channels. In brief:

+ + + +

Other optional Interfaces can be + implemented to indicate other available functionality, such as Channel.Interface.Group if the channel contains a number of contacts, Channel.Interface.Password to indicate that a channel may have a password set to require entry, and Properties for - extra data about channels which represent chat rooms or voice calls. The - interfaces implemented may not vary after the channel's creation has been - signalled to the bus (with the connection's NewChannel - signal).

+ namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState + for typing notifications. The interfaces implemented may not vary after + the channel has been created. These other interfaces (along with the + interface named by ChannelType) may + themselves specify immutable properties to be announced up-front along + with the properties on this interface.

+ +

Some channels are “anonymous”, with + TargetHandleType set to None, + which indicates that the channel is defined by some other properties. For + instance, transient ad-hoc chat rooms may be defined only by their members (as visible + through the Group + interface), and ContactSearch + channels represent a single search attempt for a particular Server.

Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml index a3319bf3f..92de9c5c4 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -580,6 +580,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +

The reason for a set of handles to move to one of + Members, + LocalPendingMembers or + RemotePendingMembers, or to be removed + from the group. A client may supply a reason when attempting to + remove members from a group with + RemoveMembersWithReason, and reasons + are supplied by the CM when emitting + MembersChanged and + MembersChangedDetailed. Some reason + codes have different meanings depending on the Actor in a + MembersChanged signal.

+ +

No reason was provided for this change.

@@ -712,7 +727,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.If a one-to-one StreamedMedia - call fails because the contact being called did not respond, the + call fails because the contact being called did not respond, or the + local user did not respond to an incoming call, the connection manager SHOULD indicate this by removing both the SelfHandle and the other contact's handle from the Group interface with reason No_Answer.

@@ -836,6 +852,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.after emitting a MembersChanged signal in which channel-specific handles are removed.

+ +

See StreamedMedia + for an overview of how group state changes are used to indicate the + progress of a call.

 @@ -963,6 +984,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.after emitting a MembersChangedDetailed signal in which channel-specific handles are removed.

+ +

See StreamedMedia + for an overview of how group state changes are used to indicate the + progress of a call.

diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 31cf47194..d4fde0d2b 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -557,6 +557,18 @@ USA.

Channel_Text_Message_Type_Normal MUST be assumed. MAY be omitted for normal chat messages. +
supersedes (s – Protocol_Message_Token)
+
If present, this message supersedes a previous message, + identified by its protocol-token or + message-token header. The user interface MAY, for + example, choose to replace the superseded message with this + message, or grey out the superseded message. + + Skype, for example, allows the user to amend + messages they have already sent (to correct typos, + etc.). +
+
pending-message-id (u - Message_ID)
The incoming message ID. This MUST NOT be present on outgoing messages. Clients SHOULD NOT store this key - it is only valid diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 195d97be7..de58bfcc0 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -18,16 +18,20 @@ 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.

- + - (draft 2) + + as stable API. Changes from draft 2: + Contact_Search_Result_Map keys are now identifiers + rather than handles; consequently, the values need not include + x-telepathy-identifier. +

A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been - found in order to free unused handles.

+ found.

Before searching, the AvailableSearchKeys property should be @@ -57,8 +61,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.The client should call the channel's Close - method when it is finished with the channel, so that any handles held - only by the channel can be released.

+ method when it is finished with the channel.

Each channel can only be used for a single search; a new channel should be requested for each subsequent search. Connection managers @@ -377,10 +380,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - A map from contact handle to search result. - - - An integer handle for the contact. + A map from contact identifier to search result, emitted in + the SearchResultReceived + signal. + + + + The identifier of a contact matching the search terms. + + + This is an identifier rather than a handle in case we make handles + immortal; see fd.o#23155 + and fd.o#13347 + comment 5. + @@ -392,29 +407,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.RequestContactInfo would return more information than this signal provides.

- -

This array SHOULD include the x-telepathy-identifier - field, whose values matches the result of calling InspectHandles - on the Contact handle.

- - -

UIs will most likely want to show the identifier to the user; - while they could do this by inspecting the signalled handle, - including it in this signal is cheap and removes a roundtrip to - look it up.

- - - A mapping from contact handle to an array of fields - representing information about this contact. Handles in this mapping - MUST remain valid until the Channel closes. + + A mapping from contact identifier to an array of fields + representing information about this contact. + Emitted when a some search results are received from the server. This signal can be fired arbitrarily many times so clients MUST NOT diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index 4484b7ce3..544565912 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -598,46 +598,126 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

A channel that can send and receive streamed media such as audio or video. - Provides a number of methods for listing and requesting new streams, and - signals to indicate when streams have been added, removed and changed - status.

- -

To make a media call to a contact, clients should call CreateChannel - with ChannelType - = StreamedMedia, - TargetHandleType - = Contact, and one of TargetHandle - or TargetID - (which should yield a channel with the local user in Members, - and the remote contact as A channel that can send and receive streamed media such as audio or + video. Provides a number of methods for listing and requesting new + streams, and signals to indicate when streams have been added, removed + and changed status. The state of the call (ringing remotely, ringing + locally, answered, missed, etc.) are represented using the properties + and signals of the Group interface.

+ +

In general this should be used in conjunction with the MediaSignalling + interface to exchange connection candidates and codec choices with + whichever component is responsible for the streams. However, in certain + applications where no candidate exchange is necessary (eg the streams + are handled by specialised hardware which is controlled directly by the + connection manager), the signalling interface can be omitted and this + channel type used simply to control the streams.

+ +

Outgoing calls

+ +

To make an audio-only call to a contact foo@example.com, + clients should call:

+ +
+ 
+CreateChannel({
+  ChannelType: StreamedMedia,
+  TargetHandleType: Contact,
+  TargetID: 'foo@example.com',
+  InitialAudio: True,
+)
+ +

As always, TargetHandle - but not in any group members list), then call - RequestStreams to initiate the call (at - which point the contact should appear in the channel's RemotePendingMembers).

+ may be used in place of TargetID if the contact's handle is already + known. To make an audio-and-video call, the client should also specify + InitialVideo. The connection manager + SHOULD return a channel whose immutable properties contain the local + user as the InitiatorHandle, + the remote contact as the TargetHandle, + Requested = True + (indicating that the call is outgoing); the Group interface should + initially have the local user in Members and the remote + contact in RemotePendingMembers, to + indicate that we are awaiting their response.

+ +

The contact answering the call is represented by the CM signalling + MembersChanged, + moving the remote contact to Members, with the remote contact as the + Actor and Reason None. The contact + rejecting the call is represented by both contacts being removed from + the group, with the remote contact as the Actor and + Reason set appropriately. The local user may hang up at any + time by calling + RemoveMembersWithReason + to remove themself, with an appropriate reason; the CM SHOULD relay the + reason to the remote contact, and emit MembersChanged removing both + contacts from the group with the self handle as the Actor.

-

In the past, several other patterns have been used to place outgoing +

(In the past, several other patterns have been used to place outgoing calls; see 'Requesting StreamedMedia Channels' on the Telepathy wiki - for the details.

+ for the details.)

+ +

Incoming calls

-

Incoming calls should be signalled as Incoming calls' immutable properties should contain TargetHandleType - = Contact, TargetHandle - set to the remote contact, with the local user in LocalPendingMembers; - to accept the call, TargetHandle and + InitiatorHandle + set to the remote contact, Requested = False + (indicating that this is an incoming call), and appropriate values of + InitialAudio and + InitialVideo; the Group interface should + initially have the local user in LocalPendingMembers + and the remote contact in Members, + indicating that the contact is awaiting our response.

+ +

To accept the call, use AddMembers - can be used to move the local user to the group's members.

+ to move the local user to the group's members. To reject the call, use + RemoveMembersWithReason + to remove the local member from the group, with an appropriate reason. + If the remote user ends the call before it is answered, this is + represented by MembersChanged + removing both parties from the group with the remote contact as the + Actor, and Reason set appropriately.

+ +

Note that the call may end with the self handle as the + Actor without the user having chosen to reject the call, as + indicated by the nature of the Reason. Specifically, some + local component may time out the call (indicating this with reason + No_Answer; for example, the CM may have forwarded the call + to another number, as configured using Forwarding.DRAFT), + or something may have gone wrong with the call + (indicated by reason Error). Such calls SHOULD be + considered missed, just as if the remote contact had hung up before the + local user answered the call.

+ + +

This is a bit awkward, but these are the best ways we can represent + these situations. It's important to document which calls should be + considered missed, to ensure that the user can be notified.

+

When the local user accepts an incoming call, the connection manager SHOULD change the direction of any streams with pending local send @@ -658,14 +738,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

In general this should be used in conjunction with the MediaSignalling - interface to exchange connection candidates and codec choices with - whichever component is responsible for the streams. However, in certain - applications where no candidate exchange is necessary (eg the streams are - handled by specialised hardware which is controlled directly by the - connection manager), the signalling interface can be omitted and this - channel type used simply to control the streams.

+

During a call

+ +

If ImmutableStreams is + False, new streams may be requested using + RequestStreams (to add video to an + audio-only call, for instance), and existing streams may be removed using + RemoveStreams (for example, to downgrade + an audio-video call to audio-only). The call may be ended by calling + RemoveMembers + or RemoveMembersWithReason; the call ending is signalled by the CM emitting MembersChanged, + removing both parties from the group.

Handler filters

diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml index 4d7391891..31f1554f8 100644 --- a/spec/Connection_Interface_Anonymity.xml +++ b/spec/Connection_Interface_Anonymity.xml @@ -123,17 +123,21 @@ SHOULD also set this property first (rather than accepting the CM's default value).

-

This property SHOULD also be made available as a parameter to - This property SHOULD also be made available as a parameter of the + same (fully-qualified) name to RequestConnection, with the DBus_Property flag in its Conn_Mgr_Param_Flags. For connections managed by the AccountManager, - clients (other than the account manager itself) SHOULD set this - property via the Account's UpdateParameters - method.

+ this property SHOULD be set via the Account Manager as follows:

+ +
+ UpdateParameters({ + "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityMandatory": new_value + }, []) +
@@ -146,17 +150,21 @@ the modes will result in emission of AnonymityModesChanged signal.

-

This property SHOULD also be made available as a parameter to - This property SHOULD also be made available as a parameter of the + same (fully-qualified) name to RequestConnection, with the DBus_Property flag in its Conn_Mgr_Param_Flags. For connections managed by the AccountManager, - clients (other than the account manager itself) SHOULD set this - property via the Account's UpdateParameters - method.

+ this property SHOULD be set via the Account Manager as follows:

+ +
+ UpdateParameters({ + "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityModes": new_value + }, []) +
diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml index f6427806a..bf0f1a9c8 100644 --- a/spec/Connection_Interface_Cellular.xml +++ b/spec/Connection_Interface_Cellular.xml @@ -42,17 +42,24 @@ protocol or provider.

Connections with this interface SHOULD provide this property as a - parameter for ConnectionManager.RequestConnection, with the - DBus_Property flag.

- -

For connections managed by the AccountManager, - this property SHOULD be set via the Account Manager, by calling - Account.UpdateParameters; the AccountManager - provides change-notification, as long as all other clients cooperate - by using it instead of setting this property directly.

+ DBus_Property flag. For connections managed by the + AccountManager, + this property SHOULD be set via the Account Manager as follows:

+ +
+ UpdateParameters({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageValidityPeriod": new_validity_period + }, []) +
+ +

The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.

@@ -64,17 +71,24 @@ number).

Connections with this interface SHOULD provide this property as a - parameter for ConnectionManager.RequestConnection, with the - DBus_Property flag.

- -

For connections managed by the AccountManager, - this property SHOULD be set via the Account Manager, by calling - Account.UpdateParameters; the AccountManager - provides change-notification, as long as all other clients cooperate - by using it instead of setting this property directly.

+ DBus_Property flag. For connections managed by the + AccountManager, + this property SHOULD be set via the Account Manager as follows:

+ +
+ UpdateParameters({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageServiceCentre": new_smsc_address + }, []) +
+ +

The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.

@@ -117,17 +131,24 @@ into a country‐specific GSM reduced character set.

Connections with this interface SHOULD provide this property as a - parameter for ConnectionManager.RequestConnection, with the - DBus_Property flag.

- -

For connections managed by the AccountManager, - this property SHOULD be set via the Account Manager, by calling - Account.UpdateParameters; the AccountManager - provides change‐notification, as long as all other clients cooperate - by using it instead of setting this property directly.

+ DBus_Property flag. For connections managed by the + AccountManager, + this property SHOULD be set via the Account Manager as follows:

+ +
+ UpdateParameters({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageReducedCharacterSet": new_value + }, []) +
+ +

The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.

 diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index 7035ca999..e5457b1ea 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -85,6 +85,16 @@ 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.

+ +

When an unanswered StreamedMedia call is + forwarded, both the contact and the self handle should be removed from + the group with the self handle as the actor, and + Channel_Group_Change_Reason No_Answer or + Busy, as appropriate. For Call.DRAFT channels, the + Call_State_Change_Reason Forwarded + should be used.

diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 0d0bbecb4..709a9b952 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -192,7 +192,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.A map from protocol identifiers supported by a connection manager to the immutable properties of the corresponding Protocol.DRAFT objects.

+ >Protocol objects.

@@ -212,7 +212,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.A map from protocol identifiers supported by this connection manager to the immutable properties of the corresponding Protocol.DRAFT objects.

+ >Protocol objects.

Providing the immutable properties here means that diff --git a/spec/Protocol.xml b/spec/Protocol.xml index 55585b20b..91c350f58 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -20,9 +20,8 @@ 02110-1301, USA.

- - (draft 1) + + (as stable API)

An object representing a protocol for which this (draft 1) - +

An interface for protocols where it might be possible to set the diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml index 1ae3cfb6a..47a37eab0 100644 --- a/spec/Protocol_Interface_Presence.xml +++ b/spec/Protocol_Interface_Presence.xml @@ -23,7 +23,7 @@ (draft 1) - +

An interface for protocols where it might be possible to set the diff --git a/spec/all.xml b/spec/all.xml index e77f63405..9140a1f30 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.9 +0.19.10 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation -- cgit v1.2.1