From fa810607e474b44755612baded586efcb2c2c739 Mon Sep 17 00:00:00 2001 From: Xavier Claessens Date: Thu, 29 Sep 2011 21:17:42 +0200 Subject: Update to spec 0.23.4 Except for Call stuff because the example using extensions needs update to new spec. --- spec/Account_Manager.xml | 26 ++++------ spec/Channel_Interface_DTMF.xml | 4 +- spec/Channel_Interface_Group.xml | 86 ++++++++++++++++++++++++++++++++ spec/Channel_Interface_Hold.xml | 16 ++++-- spec/Channel_Interface_Messages.xml | 63 ++++++++++++++++++++--- spec/Channel_Interface_SMS.xml | 6 +-- spec/Channel_Request.xml | 44 +++++++++++++++- spec/Channel_Type_File_Transfer.xml | 25 ++++++---- spec/Channel_Type_Text.xml | 35 +++++++++---- spec/Connection_Interface_Forwarding.xml | 2 +- spec/Media_Stream_Handler.xml | 11 ++++ spec/all.xml | 14 ++++-- spec/errors.xml | 45 +++++++++++++++-- spec/template.xml | 2 +- 14 files changed, 318 insertions(+), 61 deletions(-) (limited to 'spec') diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml index cd82e7f53..52cd42a1e 100644 --- a/spec/Account_Manager.xml +++ b/spec/Account_Manager.xml @@ -25,19 +25,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. details.

The current account manager is defined to be the process that owns - the well-known bus name org.freedesktop.Telepathy.AccountManager on + the well-known bus name org.freedesktop.Telepathy.AccountManager on the session bus. This process must export an - /org/freedesktop/Telepathy/AccountManager object with the + /org/freedesktop/Telepathy/AccountManager object with the AccountManager interface.

- -

Until a mechanism exists for making a reasonable automatic choice - of AccountManager implementation, implementations SHOULD NOT - register as an activatable service for the AccountManager's - well-known bus name. Instead, it is RECOMMENDED that some component - of the user's session will select and activate a particular - implementation, and that other Telepathy-enabled programs can - detect whether Telepathy is in use by checking whether the - AccountManager's well-known name is in use at runtime.

@@ -275,16 +266,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

The Connection_Manager is not installed or does not - implement the given Protocol, or one of the properties in the - Properties argument is unsupported.

+

The Connection_Manager is not installed or does not + implement the given Protocol.

 -

The Parameters provided omit a required parameter - or provide unsupported parameter, or the type of one - of the Parameters or Properties is inappropriate.

+

The Parameters provided were unacceptable: they might + omit a + Required + parameter, include an unsupported parameter, or have a value of + the wrong type.

 diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index d74ea6fa7..bb579a113 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -21,12 +21,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + The Stream_IDs in this interface should now be ignored by CMs. This is primarily to allow this interface to be used with Call.DRAFT + namespace='ofdT.Channel.Type'>Call1 channels. diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml index 92de9c5c4..890e84ebe 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -334,6 +334,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. This signal should not be relied on unless Channel_Group_Flag_Properties is present. + Clients should listen to + HandleOwnersChangedDetailed instead to + get the new identifiers as well. + @@ -352,6 +356,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + +

Emitted whenever the HandleOwners + property changes.

+ +

Clients can assume this signal is emitted by the Connection Manager + if the MemberIdentifiers property exists +

+ + + + + + A map from channel-specific handles to their owners, in which the + keys include all the handles that were added to the keys of the + HandleOwners property, and all the handles in that property whose + owner has changed + + + + + The channel-specific handles that were removed from the keys of the + HandleOwners property, as a result of the contact leaving this group + in a previous MembersChanged signal + + + + + The string identifiers for handles mentioned in this signal, to + give clients the minimal information necessary to create contacts + without waiting for round-trips. Connection managers MUST include at + least the identifiers for all handles in the Added map, and MAY + include those from Removed array. + + + + @@ -519,6 +561,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. This signal should not be relied on unless Channel_Group_Flag_Properties is present. + Clients should listen to + SelfContactChanged instead to get the new + identifier as well. + @@ -527,6 +573,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + +

Emitted whenever the SelfHandle property + changes.

+ +

Clients can assume this signal is emitted by the Connection Manager + if the MemberIdentifiers property exists. +

+ + + + + + The new value of the SelfHandle property. + + + + + The new value of the SelfHandle property's identifier. + + + + @@ -545,6 +614,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + The string identifiers for handles mentioned in this channel, to + give clients the minimal information necessary to create contacts + without waiting for round-trips. Connection managers MUST include at + least the identifiers for + SelfHandle, + Members, + LocalPendingMembers (and their actors if + any), + RemotePendingMembers and + HandleOwners. + + + + diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index ef5a08f19..69d295d97 100644 --- a/spec/Channel_Interface_Hold.xml +++ b/spec/Channel_Interface_Hold.xml @@ -22,7 +22,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + + first API-stable version @@ -31,7 +32,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. This only makes sense for channels where you are streaming media to or from the members. (To see whether the other participant has put you on hold, see CallState.)

+ namespace="org.freedesktop.Telepathy.Channel.Interface" + >CallState.)

If you place a channel on hold, this indicates that you do not wish to be sent media streams by any of its members and will be ignoring @@ -40,6 +42,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. an actively used channel (e.g. in a GSM or PBX call, it will be necessary to place an active call on hold before you can start another call).

+ +

This can also be used for putting a single Content on hold, if the + protocol supports it (This interface is in the Channel namespace for + historical reasons).

 @@ -107,14 +113,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The connection manager is attempting to move to state Held, but has not yet completed that operation. It is unspecified whether any, all or none of the streams making up the channel are on hold. + Examining the Hold state of Call Contents (if applicable) may + provide more useful information. - The connection manager is attempting to move to state Held, but + The connection manager is attempting to move to state Unheld, but has not yet completed that operation. It is unspecified whether any, all or none of the streams making up the channel are on hold. + Examining the Hold state of Call Contents (if applicable) may + provide more useful information. diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 62e83846a..a88576dc8 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -599,15 +599,66 @@ USA.

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. + identified by its 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.). -
+ + Connection Managers SHOULD represent repeatedly edited messages + in the following form: + 
+                message {token = a};
+                message {token = b, supersedes = a};
+                message {token = c, supersedes = a};
+
+ + The alternative form is: + 
+                  message {token = a};
+                  message {token = b, supersedes = a};
+                  message {token = c, supersedes = b};
+
+ but it is more difficult to implement in UIs/loggers, and it + breaks irrecoverably if message b is lost. If a CM is forced + to use this form, it should be tested extensively for + interoperability with existing clients. + + + Clients should deal gracefully if the original message gets + lost, but one or more corrections to it get through: + 
+                message {token = x} gets lost;
+                message {token = y, supersedes = x};
+                message {token = z, supersedes = x};
+
+ + This is the form that CMs will use to mean "I know + that this message was edited, but I don't know what it + originally said." It is often in the interests of the + remote side for message x to be lost (e.g. to hide + embarassing mistakes or sensitive information) so it might not + be possible to retrieve it (even on protocols with reliable + message-delivery guarantees). + +
original-message-sent (x - Unix_Timestamp64)
+
The message-sent header of the message that this + one supersedes. + This key should only be present if supersedes is also + present. It MAY be used as a hint to help clients locate the + original message in its logs. If present, comparing the tuple + (original-message-sent, supersedes) with (message-sent, + message-token) SHOULD be enough to uniquely + identify the original message.
+ +
original-message-received (x - Unix_Timestamp64)
+
The message-received header of the message that this + one supersedes. + This key should only be present if supersedes is also + present. It MAY be used as a hint in a similar way to + original-message-sent.
pending-message-id (u - Message_ID)
The incoming message ID. This MUST NOT be present on outgoing @@ -996,7 +1047,7 @@ USA.

recipient. If a delivery failure is detected later, this is signalled by receiving a message whose message-type header maps to - Channel_Text_Message_Type_Delivery_Report. + Delivery_Report. Similarly, if delivery is detected to have been successful (which is not possible in all protocols), a successful delivery report will be signalled.

diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml index 480a2a77c..497e94519 100644 --- a/spec/Channel_Interface_SMS.xml +++ b/spec/Channel_Interface_SMS.xml @@ -50,7 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. { ...ChannelType: ...Text,
  ...TargetHandleType: - Handle_Type_Contact,
+ Contact,
  ...SMS.Flash: True,
} @@ -74,7 +74,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ({ ...ChannelType: ...Text,
   ...TargetHandleType: - Handle_Type_Contact,
+ Contact,
 },
 [ ...TargetHandle, ...TargetID ]),
@@ -82,7 +82,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ({ ...ChannelType: ...Text,
   ...TargetHandleType: - Handle_Type_Contact,
+ Contact,
   ...SMSChannel: True,
 },
 [ ...TargetHandle, diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index fbb67925e..dd10049e1 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -218,7 +218,7 @@

A dictionary of metadata provided by the channel requester, which the handler and other clients MAY choose to - interpret. Currently no standard keys are defined; clients MAY + interpret. Clients MAY choose to use platform-specific keys for their own purposes, but MUST ignore unknown keys and MUST cope with expected keys being missing. Clients SHOULD namespace hint names by having them @@ -249,6 +249,48 @@ namespace="ofdT.Client.Interface.Requests">AddRequest by the ChannelDispatcher.

+

The following standardised hints are defined:

+ +
+
org.freedesktop.Telepathy.ChannelRequest.DelegateToPreferredHandler - b
+
If present and True the client currently handling the channel + SHOULD pass the channel to the + PreferredHandler using + DelegateChannels. + + + This hint allows the user to request a channel in their + preferred client in a situation where there are two chat + handlers (for example: requesting a channel in Empathy which is + currently being handled by gnome-shell). + + + If the channel is currently unhandled, clients SHOULD ignore this + hint. + + + It is assumed that Mission Control will correctly delegate an + unhandled channel to the preferred Handler. This allows + requesting clients to always include this hint in their channel + request. + + + The Handler should check each + ChannelRequest + of the Requests_Satisfied parameter of + HandleChannels + for the hint. The first request containing the hint SHOULD be used + and all further hints SHOULD be ignored. + + + This covers the very unlikely case where + HandleChannels + satisfies two separate requests which have different + PreferredHandlers. + +
+
+ diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml index 6963d2133..f50b96344 100644 --- a/spec/Channel_Type_File_Transfer.xml +++ b/spec/Channel_Type_File_Transfer.xml @@ -96,7 +96,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Content_Type" tp:immutable="yes" tp:requestable="yes">

The file's MIME type. This cannot change once the channel has been created.

@@ -109,7 +109,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Filename" tp:immutable="yes" tp:requestable="yes">

The name of the file on the sender's side. This is therefore given as a suggested filename for the receiver. This cannot change @@ -126,7 +126,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Size" tp:immutable="yes" tp:requestable="yes">

The size of the file. If this property is set, then the file transfer is guaranteed to be this size. This cannot change once @@ -145,7 +145,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + access="read" tp:name-for-bindings="Content_Hash_Type" tp:immutable="yes" + tp:requestable="yes">

The type of the ContentHash property.

@@ -168,7 +169,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Content_Hash" tp:immutable="yes" + tp:requestable="yes">

Hash of the contents of the file transfer, of type described in the value of the ContentHashType @@ -184,7 +186,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Description" tp:immutable="yes" tp:requestable="yes">

Description of the file transfer. This cannot change once the channel has been created.

@@ -197,7 +199,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:type="Unix_Timestamp64" tp:name-for-bindings="Date" tp:immutable="yes" + tp:requestable="yes">

The last modification time of the file being transferred. This cannot change once the channel has been created

@@ -210,7 +213,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Available_Socket_Types" + tp:immutable="yes" tp:requestable="yes">

A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) @@ -243,7 +247,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + tp:name-for-bindings="Initial_Offset" tp:requestable="yes">

The offset in bytes from where the file should be sent. This MUST be respected by both the receiver and the sender after the state @@ -276,7 +280,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.For incoming file transfers, this property MAY be set by the channel handler before calling AcceptFile to - inform observers where the incoming file will be saved. + inform observers where the incoming file will be saved. If set by an + approver, the handler MUST save the file to that location. Setting this property once AcceptFile has been called MUST fail. Once this property has been set URIDefined is emitted.

diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 0cd4d5bb2..86bf567fc 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -555,14 +555,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Simple one-to-one chats (such as streams of private messages in XMPP or IRC) should be represented by a Text channel whose TargetHandleType - is Handle_Type_Contact. The expected way to - request such a channel is to set the ChannelType, TargetHandleType, - and either TargetHandle or TargetID in a call to EnsureChannel.

+ is Contact. The + expected way to request such a channel is to set the ChannelType, TargetHandleType, + and either TargetHandle or TargetID in a call to + EnsureChannel.

Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text - channels with Handle_Type_Room and the Group + channels with TargetHandleType = + Room and the + Group interface. In protocols where a chatroom can be used as a continuation of one or more one-to-one chats, these channels should also have the Conference @@ -571,7 +579,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Unnamed, transient chat rooms which cannot be rejoined by their unique identifier (e.g. a conversation on MSN which has, or once had, three or more participants) are expected to be represented by Text - channels with Handle_Type_None (and hence TargetHandle 0), the + channels with TargetHandleType = None (and hence TargetHandle = 0), Group interface, and optionally the Conference @@ -580,7 +591,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.On protocols like MSN where a conversation with a user is actually just a nameless chat room starting with exactly two members, to which more members can be invited, the initial one-to-one conversation - SHOULD be represented with Handle_Type_Contact. If a third participant + SHOULD be represented with TargetHandleType = + Contact. If a third + participant joins or is invited, this SHOULD be represented by signalling a new Conference channel @@ -606,8 +620,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.NewChannels signal. The new channel should resemble the old channel, but have - Requested = FALSE regardless of its previous value; the InitiatorHandle - and InitiatorID should correspond to the sender of one of the pending + Requested = FALSE + regardless of its previous value; the InitiatorHandle + and InitiatorID + should correspond to the sender of one of the pending messages.

diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index e5457b1ea..32c7e1cbb 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -92,7 +92,7 @@ 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 + namespace='ofdT.Channel.Type'>Call1 channels, the Call_State_Change_Reason Forwarded should be used.

 diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index dbcaf816e..0a833709a 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -723,11 +723,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + This struct is also used by Call, but + in call, the CM should know about RTP profiles, and never use MAXUINT + as a default value, because it complicates things unnecessarily. + The minimum interval between two regular RTCP packets in milliseconds for this content. If no special value is desired, one should put MAXUINT (0xFFFFFFFF). + + Implementors and users of Call's RTCPFeedback should not use the MAXUINT default. + Instead, in RTP/AVP, the default should be 5000 (5 seconds). + If using the RTP/AVPF profile, it can be set to a lower value, + the default being 0. Telepathy D-Bus Interface Specification -0.23.2 +0.23.4 Copyright © 2005-2011 Collabora Limited Copyright © 2005-2011 Nokia Corporation @@ -191,7 +191,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Hold and DTMF interfaces, which may also appear on Call.DRAFT channels.

+ namespace='ofdT.Channel.Type'>Call1 channels.

 @@ -206,7 +206,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Text, StreamedMedia and - Call.DRAFT + Call1 channels, but may also appear on other types of channel.

 @@ -236,9 +236,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + - + + + + diff --git a/spec/errors.xml b/spec/errors.xml index a5271b5b6..7726f3cfd 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -386,6 +386,45 @@ + + + + Raised when the local streaming implementation has no codecs in common + with the remote side. + + + This corresponds to + Media_Error. + + + + + + + + The media stream type requested is not supported by either the + local or remote side. + + + This corresponds to + Media_Error. + + + + + + + + Raised when the call's streaming implementation has some kind of internal + error. + + + This corresponds to + Internal_Error. + + + + Raised when a connection is refused. @@ -495,7 +534,7 @@ Raised when an incoming or outgoing Call.DRAFT is + namespace="ofdT.Channel.Type">Call1 is rejected by the the receiver. @@ -537,7 +576,7 @@ errors bad-format, invalid-xml, etc., which can't happen unless the local (or remote) XMPP implementation is faulty. This is also analogous to - Media_Stream_Error_Invalid_CM_Behavior, + Invalid_CM_Behavior, TP_DBUS_ERROR_INCONSISTENT in telepathy-glib, and TELEPATHY_QT4_ERROR_INCONSISTENT in telepathy-qt4. @@ -589,7 +628,7 @@ to place a call or send a message.

The key 'balance-required' MAY be included in - CallStateDetails + CallStateDetails or a delivery report's Message_Part (with the same units and scale as AccountBalance) diff --git a/spec/template.xml b/spec/template.xml index 726472070..283804a94 100644 --- a/spec/template.xml +++ b/spec/template.xml @@ -22,7 +22,7 @@ - (draft 1) + (draft 1)

Foo.

-- cgit v1.2.1