From e088736bbff3ac9054ec405412350d468c0304df Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 14 Jun 2010 12:55:57 +0100 Subject: Update to spec 0.19.7 - update spec/ directory - add WouldBreakAnonymity error to errors.h and documentation - add Chat_State_Map type to documentation - add Account.ConnectionError, Account.ConnectionErrorDetails, ChatState.ChatStates properties to documentation --- spec/Account.xml | 52 +++++++++++++++++++++++++++ spec/Channel_Interface_Anonymity.xml | 8 ++--- spec/Channel_Interface_Chat_State.xml | 43 ++++++++++++++++++++++ spec/Channel_Interface_Service_Point.xml | 11 +++--- spec/Connection_Interface_Anonymity.xml | 49 ++++++++++++++++--------- spec/Connection_Interface_Cellular.xml | 44 ++++++++++++++++++----- spec/Connection_Interface_Forwarding.xml | 27 +++++++------- spec/Connection_Interface_Service_Point.xml | 55 +++++++++++++++-------------- spec/all.xml | 2 +- spec/errors.xml | 15 +++++++- 10 files changed, 231 insertions(+), 75 deletions(-) (limited to 'spec') diff --git a/spec/Account.xml b/spec/Account.xml index f315c15d9..dfc37bc58 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -442,6 +442,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

If the last connection to this account failed with an error, + the D-Bus error name of that error; otherwise, the empty string. + The account manager is expected to set this by observing the + Connection.ConnectionError and + Connection.StatusChanged + signals.

+ +

If ConnectionError is received before the connection disconnects, + its first argument should be used to set this property; + otherwise, the Reason argument of StatusChanged should be converted + to a suitable D-Bus error name.

+ +

Whenever the Connection connects successfully, this property should + be reset to the empty string.

+ + +

This combines the state-recoverability of + ConnectionStatusReason with the + extensibility of Connection.ConnectionError.

+ + + + + + + +

If the last connection to this account failed with an error, + a mapping representing any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + Connection.ConnectionError.

+ +

Whenever the Connection connects successfully, this property should + be reset to the empty map.

+ + +

This combines the state-recoverability of + ConnectionStatusReason with the + extensibility of Connection.ConnectionError.

+ + + + diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml index 7477f9637..ef3a3b85d 100644 --- a/spec/Channel_Interface_Anonymity.xml +++ b/spec/Channel_Interface_Anonymity.xml @@ -21,13 +21,13 @@ 02110-1301, USA.

- - (draft version, not API-stable) + + (as stable API)

Interface for requesting the anonymity modes of a channel - (as defined in Connection.Interface.Anonymity.DRAFT).

+ (as defined in Connection.Interface.Anonymity).

 + + + A map from contacts to their chat states. + + A contact + + + The contact's chat state + + + + + + +

A map containing the chat states of all contacts in this + channel whose chat state is not Inactive.

+ +

Contacts in this channel, but who are not listed in this map, + may be assumed to be in the Inactive state.

+ +

In implementations that do not have this property, its value may be + assumed to be empty until a + ChatStateChanged signal indicates + otherwise.

+ + +

This property was not present in older versions of telepathy-spec, + because chat states in XMPP are not state-recoverable (if you + miss the change notification signal, there's no way to know the + state). However, this property still allows clients to recover + state changes that were seen by the CM before the client started + to deal with the channel.

+ +

In CMs that follow older spec versions, assuming Inactive will + mean that initial chat states will always be assumed to be + Inactive, which is the best we can do. XEP 0085 specifies + Inactive as the "neutral" state to be assumed unless told + otherwise.

+ + + + diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml index 5a0d540e5..787397b20 100644 --- a/spec/Channel_Interface_Service_Point.xml +++ b/spec/Channel_Interface_Service_Point.xml @@ -17,8 +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.

- - (draft version, not API-stable) + + (as stable API)

An interface for channels @@ -55,8 +55,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The service point that the channel is connected to. If the channel is - not connected to any service points, the CM MUST set the - Service_Point_Type field to None. + not connected to a service point, the CM MUST set the + Service_Point_Type field to None; for instance, + this will be the case for ordinary calls. @@ -73,7 +74,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + The new service point that is being used. diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml index 5426b5d50..4d7391891 100644 --- a/spec/Connection_Interface_Anonymity.xml +++ b/spec/Connection_Interface_Anonymity.xml @@ -21,9 +21,8 @@ 02110-1301, USA.

- - (draft version, not API-stable) + + (as stable API)

An interface to support anonymity settings on a per-connection basis. @@ -57,7 +56,7 @@ service level would choose both (anonymity services are opaque to clients of this interface).

-

Clients SHOULD NOT set both Client_Info and ShowClient_Info modes. +

Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. If they are set, the CM MUST respect Client_Info and ignore Show_Client_Info.

 @@ -68,14 +67,15 @@

Explicitly request showing of client information. In connection context, this can be used to override service default. In channel context, this overrides connection anonymity modes.

+ - In GSM, it's possible to have CLIR enabled by default, and - explicitly suppress CLIR for a single phone call. +

In GSM, it's possible to have CLIR enabled by default, and + explicitly suppress CLIR for a single phone call.

Clients SHOULD NOT set both Client_Info and Show_Client_Info modes. If they are set, the CM MUST respect Client_Info and ignore - ShowClientInfo. The CM MAY set both Client_Info and Show_Client_Info + Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info in SupportedAnonymityModes to indicate its support for explicitly hiding and publicising client information.

@@ -110,21 +110,30 @@ - +

This specifies whether or not the anonymity settings MUST be respected by the CM and any intermediaries between the local and remote contacts. If this is set to true but anonymity settings cannot be followed, then the session MUST be denied with a - org.freedesktop.Telepathy.Errors.NotAvailable error. + org.freedesktop.Telepathy.Errors.WouldBreakAnonymity + error. Any client that sets AnonymityModes SHOULD also set this property first (rather than accepting the CM's default value).

-

This property can also be set using a connection parameter in This property SHOULD also be made available as a parameter to + RequestConnection, - see Conn_Mgr_Param_Flags for more information.

+ 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.

 @@ -134,12 +143,20 @@

The currently enabled anonymity modes for the connection. Setting has the effect of requesting new modes for the connection, and may raise an error if the unsupported modes are set. Successfully changing - the modes will result in emmision of + the modes will result in emission of AnonymityModesChanged signal.

-

This property can also be set using a connection parameter in RequestConnection, - see Conn_Mgr_Param_Flags for more information.

+

This property SHOULD also be made available as a parameter 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.

 diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml index c2a25503a..cd5141f8e 100644 --- a/spec/Connection_Interface_Cellular.xml +++ b/spec/Connection_Interface_Cellular.xml @@ -26,7 +26,7 @@ (draft version, not API-stable) -

This interface is for various cellular things (GSM and/or CDMA) things that +

This interface is for various cellular things (GSM and/or CDMA) that aren't really applicable to other protocols.

 @@ -34,20 +34,48 @@ type="u" access="readwrite">

Define how long should the service centre try message delivery before - giving up, failing delivery and deleting the message. A value of 0 means - to use the service centre's default period.

+ giving up, failing delivery and deleting the message. A value of 0 + means to use the service centre's default period.

+

The value specified is in seconds. Note that various protocols or - implementations may round the value up (eg. to a minute or hour - precision). The maximum validity period may vary depending on - protocol or provider.

+ implementations may round the value up (eg. to a minute or hour + precision). The maximum validity period may vary depending on + 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.

 - Address for the messaging service centre. Typically (as is the case - for GSM's SMSC), it's the ISDN / telephony address (ie. a phone number). +

Address for the messaging service centre. Typically (as is the case + for GSM's SMSC), it's the ISDN / telephony address (ie. a phone + number).

+ +

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.

 diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index 4c1c11937..7035ca999 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -105,11 +105,12 @@ - +

The incoming channel should be forwarded if a busy signal is detected. What defines "Busy" is CM-specific (perhaps a single resource is already in use, or a user's status is set to Busy Connection_Presence_Type).

+

If initial timeout is specified for Busy condition and call waiting is not supported by the service, the timeout will be ignored.

@@ -147,13 +148,14 @@ - +

The length of time (in seconds) to wait the contact to respond to the forwarded channel. This MAY be ignored by the CM if it isn't supported by the underlying network/protocol for the specific status of the remote contact (for example, a GSM call that is forwarded may return Not_Reachable immediately without waiting for the timeout value to expire).

+

A value of 0 means the condition can match immediately. A value of MAX_UINT32 means that the CM's default should be used.

@@ -208,23 +210,22 @@ - -

- A map of forwarding conditions supported on this connection to + +

A map of forwarding conditions supported on this connection to maximum number of Forwarding_Rule_Entry - supported for the specific condition. - - When forwarding is done by the provider, different providers + supported for the specific condition.

+ + +

When forwarding is done by the provider, different providers might support different chain sizes, or provider and local - implementation chain sizes might differ. - -

+ implementation chain sizes might differ.

+ - +

The current forwarding rules that are enabled for this connection. Forwarding rules each contain an array of type Forwarding_Rule_Entry.

@@ -269,7 +270,7 @@ - +

The forwarding rule to override. Note that this SHOULD not affect other rules; setting a rule that overrides others (such as Forwarding_Rule_Unconditional) will not modify other rules. This diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml index b0b34b678..b135c04c7 100644 --- a/spec/Connection_Interface_Service_Point.xml +++ b/spec/Connection_Interface_Service_Point.xml @@ -17,8 +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.

- - (draft version, not API-stable) + + (as stable API)

An interface for connections whose channels may be able to indicate @@ -33,33 +33,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + The service point. - + A list of IDs that are mapped to this service. This is provided as a convenience for the UIs, but the preferred method for - requesting channel to a service is by setting InitialServicePoint - property in channel request. + requesting channel to a service is by setting the InitialServicePoint + property in a channel request. -

Description of a service point and IDs which are mapped to id.

+

Description of a service point and IDs which are mapped to it.

-

An example Service Point info for GSM emergency calls (callable through - "911" and "112") could look like:

+

An example Service Point info for GSM emergency calls (callable + through "911" and "112") could look like:

   ServicePointInfo = (
-    ServicePoint: (
-      ServicePointType: 1 (Emergency),
-      ServicePoint: "urn:service:sos"
+    Service_Point: (
+      Service_Point_Type: 1 (Emergency),
+      Service_Point: "urn:service:sos"
     ),
-    ServiceIDs: [ "911", "112" ]
+    Service_IDs: [ "911", "112" ]
   )
@@ -73,20 +73,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + -

The new list of service points.

+

The new value of + KnownServicePoints.

 - Indicate that the list of known service points (or their IDs) have - changed, presenting the new list. + Emitted when the list of known service points (or their IDs) has + changed. A service point. - + The service type. @@ -94,7 +96,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. String representation of the service point. The representation is - service specific; it may be Uniform_Resource_Name + service specific; it may be a 'service' Uniform Resource Name as + specified by RFC 5031, or may be in some other form. Empty, unused or unknown value is represented by "". @@ -103,12 +107,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - The various types of service points the channel might connect to. + The various types of service points a channel might connect to. - The service point is not used/available. + The channel is not communicating with a service point, or it is not + known whether it is communicating with a service point (e.g. an + ordinary call). @@ -125,11 +131,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - - Uniform Resource Name as specified by - RFC 5031. - diff --git a/spec/all.xml b/spec/all.xml index 591efb52b..700c132ce 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.6 +0.19.7 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation diff --git a/spec/errors.xml b/spec/errors.xml index 0137e776c..60a93c95c 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -420,7 +420,20 @@ - Copyright © 2005-2009 Collabora Limited + + + + Raised if a request cannot be satisfied without violating an earlier + request for anonymity, and the earlier request specified that raising + an error is preferable to disclosing the user's identity (for instance + via Connection.Interface.Anonymity.AnonymityMandatory or + Channel.Interface.Anonymity.AnonymityMandatory). + + + + Copyright © 2005-2010 Collabora Limited Copyright © 2005-2009 Nokia Corporation

This library is free software; you can redistribute it and/or -- cgit v1.2.1