From 1473e1f8f782a263ec1fbcd21efa978651da0a42 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 10 Sep 2010 11:32:11 +0100 Subject: Update to spec 0.19.12 - NotYet error is generated - Object_Immutable_Properties_Map is generated - TP_PROP_CONNECTION_INTERFACE_CELLULAR_OVERRIDE_MESSAGE_SERVICE_CENTRE --- spec/Account_Interface_Minimum_Presence.xml | 108 +++++++ spec/Channel.xml | 11 +- spec/Channel_Dispatcher_Future.xml | 377 +++++++++++++++++++++++ spec/Channel_Interface_Addressing.xml | 107 +++++++ spec/Channel_Interface_DTMF.xml | 9 + spec/Channel_Interface_SMS.xml | 93 ++++++ spec/Channel_Request_Future.xml | 98 ++++++ spec/Channel_Type_Call.xml | 13 + spec/Channel_Type_Server_TLS_Connection.xml | 10 + spec/Channel_Type_Streamed_Media.xml | 6 +- spec/Client_Handler.xml | 20 +- spec/Client_Interface_Requests.xml | 4 +- spec/Client_Observer.xml | 11 +- spec/Connection_Interface_Addressing.xml | 258 ++++++++++++++++ spec/Connection_Interface_Cellular.xml | 53 +++- spec/Connection_Interface_Contact_Groups.xml | 64 +++- spec/Connection_Interface_Contact_List.xml | 433 ++++++++++++++++++--------- spec/Connection_Interface_Power_Saving.xml | 101 +++++++ spec/Makefile.am | 8 + spec/Protocol.xml | 24 +- spec/Protocol_Interface_Addressing.xml | 300 +++++++++++++++++++ spec/all.xml | 10 +- spec/errors.xml | 10 +- spec/generic-types.xml | 17 ++ 24 files changed, 1974 insertions(+), 171 deletions(-) create mode 100644 spec/Account_Interface_Minimum_Presence.xml create mode 100644 spec/Channel_Dispatcher_Future.xml create mode 100644 spec/Channel_Interface_Addressing.xml create mode 100644 spec/Channel_Interface_SMS.xml create mode 100644 spec/Channel_Request_Future.xml create mode 100644 spec/Connection_Interface_Addressing.xml create mode 100644 spec/Connection_Interface_Power_Saving.xml create mode 100644 spec/Protocol_Interface_Addressing.xml (limited to 'spec') diff --git a/spec/Account_Interface_Minimum_Presence.xml b/spec/Account_Interface_Minimum_Presence.xml new file mode 100644 index 000000000..eb829b824 --- /dev/null +++ b/spec/Account_Interface_Minimum_Presence.xml @@ -0,0 +1,108 @@ + + + Copyright © 2010 Collabora Ltd. + Copyright © 2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public +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) + + +

This interface extends the core Account interface to provide a way + for applications to request minimum presence on the account.

+ + +

Some applications, for example mail notifiers or address book + synchronisation, can make use of account's connection even while + the user is nominally offline.

+ + +

Each client's unique name may set a minimum desired presence on the + account. The combined presence is the most available presence + of the minimum presences set and of RequestedPresence + set by the user. The account manager should attempt to manipulate + the connection to set the combined presence.

+ + + + + Active requests for minimum presence status, a map of client unique + name to the (non-offline) minimum presence they set. + + + + + +

Set a minimum presence needed by the client for this account. Setting + (Offline, "offline", "") removes the minimum presence requirement for + the client's unique name.

+ + + + + Requested presence status. + + + + + + + Emitted when the + MinimumPresenceRequests property + changes. + + + + + A new value of MinimumPresenceRequests property. + + + + + + +

A map of active minimum presence requests.

+ + + +

Client unique name.

+ + + + +

Requested minimum presence.

+ + +

Some applications may want to monitor the currently active + minimum presences required. An example is an tool allowing + the user to inspect applications maintaining open connections and + close those applications.

+ + + + + + + diff --git a/spec/Channel.xml b/spec/Channel.xml index 897b68353..b1772d7d4 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -101,7 +101,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.TargetHandleType MUST be present and not Handle_Type_None, and TargetID MUST NOT be - present.

+ present. Properties from + Addressing.DRAFT + MUST NOT be present.

The channel that satisfies the request MUST either:

@@ -147,8 +149,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.TargetHandleType MUST be present and not Handle_Type_None, and TargetHandle MUST NOT be - present. The request MUST fail with error InvalidHandle, without - side-effects, if the requested TargetID would not be accepted by + present. Properties from + Addressing.DRAFT + MUST NOT be present.The request MUST fail with error InvalidHandle, + without side-effects, if the requested TargetID would not be + accepted by RequestHandles.

The returned channel must be related to the handle corresponding diff --git a/spec/Channel_Dispatcher_Future.xml b/spec/Channel_Dispatcher_Future.xml new file mode 100644 index 000000000..701b42470 --- /dev/null +++ b/spec/Channel_Dispatcher_Future.xml @@ -0,0 +1,377 @@ + + + + Copyright © 2008-2010 Collabora Ltd. + Copyright © 2008-2009 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.

+ + + + + + + +

This interface contains functionality which we intend to incorporate + into the ChannelDispatcher + interface in future. It should be considered to + be conceptually part of the core ChannelDispatcher interface, but without + API or ABI guarantees.

+ + + + + Support for this method is indicated by the + SupportsRequestHints property. + Clients MUST recover from this method being unsupported by falling back + to CreateChannel. + + +

Start a request to create a channel. This initially just creates a + ChannelRequest + object, which can be used to continue the request and track its + success or failure.

+ + +

The request can take a long time - in the worst case, the + channel dispatcher has to ask the account manager to put the + account online, the account manager has to ask the operating + system to obtain an Internet connection, and the operating + system has to ask the user whether to activate an Internet + connection using an on-demand mechanism like dialup.

+ +

This means that using a single D-Bus method call and response + to represent the whole request will tend to lead to that call + timing out, which is not the behaviour we want.

+ + +

If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + ChannelRequest.Proceed + is called, at which point + ChannelRequest.Failed + is emitted with an appropriate error.

+ + +

This means there's only one code path for errors, apart from + InvalidArgument for "that request makes no sense".

+ +

It also means that the request will proceed if the account is + enabled after calling CreateChannel, but before calling + Proceed.

+ + + + + + The + Account + for which the new channel is to be created. + + + + + +

A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + Connection.Interface.Requests.CreateChannel. +

+ +

Certain properties will not necessarily make sense in this + dictionary: for instance, + TargetHandle + can only be given if the requester is able to interact with a + Connection + to the desired account.

+ + + + + +

The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action. + The UserActionTime + property will be set to this value, and it will eventually be + passed as the User_Action_Time parameter of HandleChannels.

+ + + + + +

Either the well-known bus name (starting with + org.freedesktop.Telepathy.Client.) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler—irrespective of whether that handler's HandlerChannelFilter + matches the channel—and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler.

+ + +

This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.

+ +

This is partly so the channel dispatcher can call + HandleChannels + on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.

+ +

The filter should be disregarded for ease of use of this + interface: clients will usually use this argument to request + channels be sent to themself, and this should trump the filter + not matching. This also allows a client to become the handler + for a channel produced by one of its own requests, while not + being a candidate to handle other channels of that type.

+ + +

If this is a well-known bus name and the handler has the + Requests interface, the channel dispatcher SHOULD + call AddRequest + on that Handler after this method has returned.

+ + +

This ordering allows a Handler which calls CreateChannel with + itself as the preferred handler to associate the call to + AddRequest with that call.

+ + +

This is copied to the ChannelRequest that is returned, + as the PreferredHandler + property.

+ + + + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + + + + + +

Additional information about the channel request, which will be + used as the value for the resulting request's Hints + property, but will not otherwise be interpreted by the Channel + Dispatcher.

+ + +

See the Hints property's documentation for rationale.

+ + + + + + + A + ChannelRequest + object. + + + + + + + The Preferred_Handler is syntactically invalid or does + not start with org.freedesktop.Telepathy.Client., + the Account does not exist, or one of the Requested_Properties + is invalid + + + + + + + + + Support for this method is indicated by the + SupportsRequestHints property. + Clients MUST recover from this method being unsupported by falling back + to EnsureChannel. + + +

Start a request to ensure that a channel exists, creating it if + necessary. This initially just creates a ChannelRequest + object, which can be used to continue the request and track its + success or failure.

+ +

If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + ChannelRequest.Proceed + is called, at which point + ChannelRequest.Failed + is emitted with an appropriate error.

+ + +

The rationale is as for CreateChannel.

+ + + + + + The + Account + for which the new channel is to be created. + + + + + +

A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + Connection.Interface.Requests.EnsureChannel. +

+ +

Certain properties will not necessarily make sense in this + dictionary: for instance, + TargetHandle + can only be given if the requester is able to interact with a + Connection + to the desired account.

+ + + + + +

The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + + + +

Either the well-known bus name (starting with + org.freedesktop.Telepathy.Client.) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + CreateChannelWithHints, except + as noted here.

+ +

If any new channels are created in response to this + request, the channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler. If the requested channel already exists (that + is, Connection.Interface.Requests.EnsureChannel + returns Yours=False) then the channel dispatcher + SHOULD re-dispatch the channel to its existing handler, and MUST + NOT dispatch it to this client (unless it is the existing handler); + the request is still deemed to have succeeded in this case.

+ + +

An address book application, for example, might call EnsureChannel + to ensure that a text channel with a particular contact is + displayed to the user; it does not care whether a new channel was + made. An IM client might call EnsureChannel + in response to the user double-clicking an entry in the contact + list, with itself as the Preferred_Handler; if the + user already has a conversation with that contact in another + application, they would expect the existing window to be + presented, rather than their double-click leading to an error + message. So the request should succeed, even if its + Preferred_Handler is not used.

+ + + + + + + + Additional information about the channel request, which will be used + as the value for the resulting request's Hints + property. + + + + + A + ChannelRequest + object. + + + + + + + The Preferred_Handler is syntactically invalid or does + not start with org.freedesktop.Telepathy.Client., + the Account does not exist, or one of the Requested_Properties + is invalid + + + + + + + + + + If True, the channel dispatcher is new enough to support + CreateChannelWithHints and + EnsureChannelWithHints, in addition + to the older CreateChannel + and EnsureChannel. + methods. If False or missing, only the metadata-less + variants are supported. + + + + + + diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml new file mode 100644 index 000000000..494fd7bf0 --- /dev/null +++ b/spec/Channel_Interface_Addressing.xml @@ -0,0 +1,107 @@ + + + Copyright © 2010 Collabora Limited + +

This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

+ + + (as draft) + +

This interface provides properties that can be used for + requesting channels through different contact addressing + schemes like vCard addresses or URIs. +

+ + + + +

The vCard field, normalized to lower case, + TargetVCardAddress refers to.

+ +

The url vCard field MUST NOT appear here; see + TargetURI instead.

+ + +

In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

+ + +

If this is omitted from a request, + TargetVCardAddress MUST be + omitted as well.

+ + + + + +

The URI scheme used in TargetURI

+ + +

While this seems redundant, since the scheme is included in + TargetURI, it exists for constructing + RequestableChannelClasses + that support a limited set of URI schemes.

+ + +

If this is omitted from a request, + TargetURI MUST be + omitted as well.

+ + + + + +

The vCard address of the Channel's target.

+ +

If this is present in a channel request, + TargetVCardField + MUST be present, and + TargetHandle, + TargetID, + and TargetURI MUST NOT be present. + TargetHandleType + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.

+ + + + + +

The URI of the Channel's target. The URI's scheme (i.e. the + part before the first colon) MUST be identical to + TargetURIScheme.

+ +

If this is present in a channel request, + TargetVCardField + MUST be present, and + TargetHandle, + TargetID, + and TargetVCardAddress MUST NOT be + present. + TargetHandleType + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.

+ + + + + diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index bd20f6ed3..c74dd5136 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -20,6 +20,11 @@ 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 + channels. An interface that gives a Channel the ability to send DTMF events over @@ -30,6 +35,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The Stream_ID parameter became + vestigial. A stream ID as defined in the StreamedMedia channel type. This argument is included for backwards compatibility and MUST @@ -78,6 +85,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The Stream_ID parameter became + vestigial. A stream ID as defined in the StreamedMedia channel type. This argument is included for backwards compatibility and MUST diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml new file mode 100644 index 000000000..b0dce6647 --- /dev/null +++ b/spec/Channel_Interface_SMS.xml @@ -0,0 +1,93 @@ + + + Copyright © 2008–2010 Nokia Corporation + Copyright © 2010 Collabora Ltd. + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + Imported from + rtcom-telepathy-glib, with the unused properties removed and the + documentation tidied up. + + +

This interface contains SMS-specific properties for text channels. + This currently only includes whether the SMSes received on the channel + should be displayed immediately to the user, without prompting.

+ +

Handler filters

+ +

A handler for class 0 SMSes should advertise the following filter:

+ +
+{ ...ChannelType: + ...Text,
+  ...TargetHandleType: + Handle_Type_Contact,
+  ...SMS.Flash: + True,
+}
+ +

It should also set its BypassApproval property + to True, so that it is invoked immediately for new + channels.

+ + + + +

If True, then this channel is exclusively for + receiving class 0 SMSes (and no SMSes can be sent using SendMessage + on this channel). If False, no incoming class 0 SMSes + will appear on this channel.

+ +

This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. NewChannels signals.

+ + +

Class 0 SMSes should be displayed immediately to the user, and + need not be saved to the device memory unless the user explicitly + chooses to do so. This is unlike “normal”, class 1 SMSes, which + must be stored, but need not be shown immediately in their entirity + to the user.

+ +

Separating class 0 SMSes into their own channel with this + immutable property allows them to be dispatched to a different + Handler—which + would include this property in its HandlerChannelFilter—avoiding the normal Text + channel handler having to decide for each message whether it should + be displayed to the user immediately or handled normally.

+ +

Currently, no mechanism is defined for sending class 0 + SMSes. It seems reasonable to support specifying the class of an + outgoing SMS in its header Message_Part, rather + than requiring the UI to request a special channel for such SMSes; + hence, we define here that channels with Flash set to + True are read-only.

+ + + + + diff --git a/spec/Channel_Request_Future.xml b/spec/Channel_Request_Future.xml new file mode 100644 index 000000000..d75c7e0ce --- /dev/null +++ b/spec/Channel_Request_Future.xml @@ -0,0 +1,98 @@ + + + Copyright © 2008-2010 Collabora Ltd. + Copyright © 2008-2009 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + + + +

This interface contains functionality which we intend to incorporate + into the ChannelRequest + interface in future. It should be considered to + be conceptually part of the core ChannelRequest interface, but without + API or ABI guarantees.

+ + + + (as draft) + +

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 + choose to use platform-specific keys for their own purposes, but MUST + ignore unknown keys and MUST cope with expected keys being + missing.

+ + This property might be used to pass a contact ID for a + telephone number shared between two contacts from the address book to + the call UI, so that if you try to call “Mum”, the call UI knows this + rather than having to guess or show “Calling Mum or Dad”. The format + of these contact IDs would be platform-specific, so we leave the + definition of the dictionary entry up to the platform in question. + But third-party channel requesters might not include the contact ID, + so the call UI has to be able to deal with it not being + there. + +

The channel dispatcher will not interpret these hints: they are + solely for communication between cooperating clients.

+ + +

Any extra parameters that do affect the channel dispatcher should + be designed separately.

+ + +

This property may be set when the channel request is created, and + can never change. Since it is immutable, it SHOULD be included in the + dictionary of properties passed to AddRequest + by the ChannelDispatcher.

+ + + + + (as draft) + +

Variant of the Succeeded signal + allowing to get the channel which has been created.

+ + + + +

The Connection owning the channel.

+ + + + + +

The channel which has been created.

+ + + + + + + + diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index f1d0f0e06..68dc7ffc7 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -663,6 +663,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + + diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml index 1d705c552..7b1202a01 100644 --- a/spec/Channel_Type_Server_TLS_Connection.xml +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -55,6 +55,16 @@ + + + + The hostname of the server we expect ServerCertificate + to certify; clients SHOULD verify ServerCertificate against + this hostname when checking its validity. + + + diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index 544565912..aa2b90345 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -771,14 +771,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.HandlerChannelFilter: 
-{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
 }
To advertise support for audio calls, also include the following filter:
-{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
   '...Channel.Type.StreamedMedia.InitialAudio': True,
 }
@@ -786,7 +786,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.To advertise support for video calls, also include the following filter: 
-{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
   '...Channel.Type.StreamedMedia.InitialVideo': True,
 }
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 10a16bd69..2cceed170 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -279,11 +279,21 @@ org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true -

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

- -

If keys are defined for this dictionary, all will be optional; - handlers MAY safely ignore any entry in this dictionary.

+

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

+ +
+
request-properties - a{oa{sv}}
+
A map from ChannelRequest + paths listed in Requests_Satisfied to + Qualified_Property_Value_Maps containing + namespaced immutable properties of each request.
+
+ +

When more keys are defined for this dictionary, all will be + optional; handlers MAY safely ignore any entry in this + dictionary.

 diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index f4c11087d..cfab58de7 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -124,7 +124,9 @@ namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime and Account - MUST be included.

+ MUST be included, and Hints + SHOULD be included if implemented.

diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 912edaf4f..01fee8b9f 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -326,7 +326,9 @@ Recover=true - The requests satisfied by these channels. + The ChannelRequests + satisfied by these channels. If the same process is an Observer and a Handler, it can be useful @@ -356,6 +358,13 @@ Recover=true the same observer crashed). + +
request-properties - a{oa{sv}}
+
A map from ChannelRequest + paths listed in Requests_Satisfied to + Qualified_Property_Value_Maps containing + namespaced immutable properties of each request.

All defined keys for this dictionary are optional; diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml new file mode 100644 index 000000000..497c6d0d9 --- /dev/null +++ b/spec/Connection_Interface_Addressing.xml @@ -0,0 +1,258 @@ + + + Copyright (C) 2010 Collabora Limited + +

This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version.

+ +

This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser + General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public License + along with this library; if not, write to the Free Software Foundation, + Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

+ + + + + (as draft) + +

This interface deals with the multiple address types that can + refer to the same contact, such as vCard fields and URIs.

+ +

It can be used to retrieve contacts with a specific addresses + through GetContactsByVCardField and + GetContactsByURI, as well as + defining the various addressing methods for a given contact + through this interface's contact attributes.

+ + + + + +

The vCard field of the addresses we are requesting. The + field name SHOULD be in lower case. Supported + fields can be found in + AddressableVCardFields.

+ +

The url vCard field MUST NOT appear here; see + GetContactsByURI instead.

+ + +

In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

+ + + + + + + The addresses to get contact handles for. The address types + should match the given vCard field. + + + + +

A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.

+ +

Attributes from this interface and from + org.freedesktop.Telepathy.Connection + are always returned, and need not be requested + explicitly.

+ +

The behavior of this parameter is similar to the same + parameter in + Contacts.GetContactAttributes.

+ + + + + +

A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.

+ +

Requested addresses that cannot be satisfied MUST be ommitted + from the mapping.

+ +

Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (org.freedesktop.Telepathy.Connection/contact-id), + and the vCard field used for requesting the contact in + org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info. +

+ + + + +

Request contacts and retrieve their attributes using a given field + in their vCards.

+ +

The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + Connection.ReleaseHandles + method.

+ + + + + + + + + + + The URI addresses to get contact handles for. Supported + schemes can be found in + AddressableURISchemes. + + + + +

A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.

+ +

Attributes from this interface and from + org.freedesktop.Telepathy.Connection + are always returned, and need not be requested + explicitly.

+ +

The behavior of this parameter is similar to the same + parameter in + Contacts.GetContactAttributes.

+ + + + + +

A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.

+ +

Requested URIs that cannot be satisfied MUST be ommitted + from the mapping.

+ +

Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (org.freedesktop.Telepathy.Connection/contact-id). +

+ + + + +

Request contacts and retrieve their attributes using URI addresses.

+ +

The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + Connection.ReleaseHandles + method.

+ + + + + + + + + +

A mapping of vCard fields and addresses that repreent + the given contact.

+ + + + + + + + The various vCard addresses that identify this contact. + + + + + + The various URI addresses that identify this contact. + + + + + +

The contact's address, as it was requested + through GetContactsByVCardField. This + attribute MUST be ommitted if the contact was not retrieved + through GetContactsByVCardField.

+ +

When retrieving more than one contact + through GetContactsByVCardField, + there needs to be a way to map the given contact back o the + original request.

+ + + + + + +

The contact's URI, as it was requested through + GetContactsByURI. This + attribute MUST be ommitted if the contact was not retrieved + through GetContactsByURI.

+ +

When retrieving more than one contact + through GetContactsByURI, + there needs to be a way to map the given contact back o the + original request.

+ + + + + + + The address that has been requested by + GetContactsByVCardField or + GetContactsByURI. + + + + + The vCard field used in GetContactsByVCardField. + + + + + + The address that was requested. + + + + + + + + diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml index bf0f1a9c8..3dc29e329 100644 --- a/spec/Connection_Interface_Cellular.xml +++ b/spec/Connection_Interface_Cellular.xml @@ -63,12 +63,63 @@ + + Previously, as an undocumented + feature, setting MessageServiceCentre + to the empty string caused the SIM's default SMSC to be used. + +

If True, SMSes will be sent via the service centre + specified by MessageServiceCentre. If + False, the SIM's default SMSC will be used, ignoring the + value of MessageServiceCentre.

+ + +

It could be desirable for a configuration interface to remember + the user's previous choice of custom SMSC, even if it's not in use. + This boolean allows that choice to be saved as an account parameter + by Mission Control, rather than the UI needing to save it elsewhere + to be restored if the user wants to reactivate it.

+ + +

Connections with this interface SHOULD provide this property as a + parameter of the same (fully-qualified) name to ConnectionManager.RequestConnection, with the + 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.OverrideMessageServiceCentre": True + }, []) +
+ +

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

+ + + + This property's value is now + ignored unless + OverrideMessageServiceCentre is + True. + +

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

+ number). If + OverrideMessageServiceCentre is + False, this property's value should be ignored by the CM + in favour of the SIM's default SMSC.

Connections with this interface SHOULD provide this property as a parameter of the same (fully-qualified) name to - + (draft 1) @@ -79,11 +79,9 @@ distinguish between a create/remove pair and a renamed group by receiving GroupRenamed.

-

This property's value is not meaningful until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this property to be meaningful by calling - RequestContactList.

+

This property's value is not meaningful until the + ContactListState has become Success.

 @@ -213,6 +211,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -239,6 +245,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -265,6 +272,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -286,6 +301,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -306,6 +322,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -326,6 +350,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -341,6 +366,14 @@

Any GroupsChanged or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -366,6 +399,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -378,6 +412,14 @@

Any GroupsChanged or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -393,6 +435,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -412,6 +455,14 @@

Any GroupRenamed or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

@@ -439,6 +490,7 @@ Raised if there is already a group with the new name. + diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index 9db86aa2c..3366b57e2 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -18,10 +18,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

- - (draft 2) + (draft 3)

An interface for connections that have any concept of a list of @@ -46,87 +46,119 @@

The list of contacts is not exposed as a D-Bus property; it can be - fetched using RequestContactList. + fetched using GetContactListAttributes.

In some protocols, such as XMPP, the contact list may not be available immediately. The - RequestContactList method - will wait until the contact list is available before returning. + GetContactListAttributes method + will fail until the contact list is available. Using a method also allows extra attributes to be retrieved at the same time.

 - - (in draft: renamed from - GetContactListAttributes) - -

Return some contact attributes for a list of contacts somehow - associated with the user.

+ + + The progress made in retrieving the contact list. + + + + The connection has not started to retrieve the contact + list. If GetContactListAttributes is + called in this state, it will raise NotYet. + + + + The connection has started to retrieve the contact + list, but has not yet succeeded or failed. + If GetContactListAttributes is called + in this state, it will raise NotYet. + + + + +

The connection has tried and failed to retrieve the contact + list. If GetContactListAttributes + is called in this state, it will immediately raise an error + indicating the reason for failure.

+ +

The connection manager SHOULD try again to obtain the contact + list, if appropriate for the protocol. If it succeeds later, + the ContactListState MUST advance + to Success.

+ + + + + The connection has successfully retrieved the contact + list. If GetContactListAttributes + is called in this state, it will return successfully. + + + + + (in draft 3) + + The progress made in retrieving the contact list. + Change notification is via + ContactListStateChanged. + + + + + (in draft 3) + + Emitted when ContactListState + changes. + + + + + The new value of ContactListState. + + + -

This definition is deliberately vague: in practice, most user - interfaces should display some subset of this list, by filtering it - by some contact attributes (for instance, displaying all contacts - whose "subscribe" attribute is Yes is expected to be a common case). - This list MAY contain any contacts whatsoever, but MUST contain - at least the following:

+ + (semantics changed in draft + 3) + +

Return some contact attributes for a list of contacts + associated with the user. This list MUST include at least:

    -
  • all contacts whose "subscribe" attribute is Ask or Yes
    • -
  • all contacts whose "publish" attribute is Ask or Yes
    • -
  • all contacts with a persistently-stored stored alias, if - supported
    • -
  • all contacts in user-defined contact groups, if supported
    • +
  • all contacts whose subscribe + attribute is not No
    • +
  • all contacts whose publish + attribute is not No
-

This list does not need to contain every visible contact: for - instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear - here. Blocked contacts SHOULD NOT appear here either, unless they - are still stored in a persistent roster/contact list as well as - being blocked.

+

but MAY contain other contacts.

-

This is basically the union of the historical ContactList subscribe, publish and stored - channels.

- -

For example, XMPP, it's the roster; on link-local XMPP, it's the - set of visible users on the local network; on MSN, it's the union - of the forward and reverse buddy lists.

- -

An easy way for an application to display a contact list is to - call this method with at least this interface in the Interfaces - argument, then check which subset of contacts should be displayed - (perhaps based on their subscribe attribute, for instance) and display - them. Any additional information required to display the contact - list, like aliases or presence, can be retrieved at the same - time.

- -

In practice, most user interfaces for the contact list will - usually display a large proportion of this list - (for instance, most contacts on the contact list will usually - have subscribe=Yes in practice, so contact lists that display - subscribe=Yes contacts need to display almost the entire list), - so the overhead of returning information about too many contacts - is small.

+

For instance, on XMPP, all contacts on the roster would appear + here even if they have subscription="none", unless there's + reason to believe the user does not want to see them (such as + having been blocked).

 -

This method SHOULD NOT return before the contact list has been - retrieved, on protocols where this is possible. As a result, - clients SHOULD use a longer-than-default timeout for this method - call, since retrieving the contact list can take a significant - time on some servers.

+

This list does not need to contain every visible contact: for + instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear + here. Blocked contacts SHOULD NOT appear here, unless they still + have a non-No subscribe or + publish attribute + for some reason.

-

This makes it possible for clients to wait for the contact list. - For instance, on XMPP this method shouldn't return until the - roster has been retrieved, which is an asynchronous process. - However, on link-local XMPP you can't know when you have the - complete list, so this method would have to return immediately.

+

It's reasonable to assume that blocked contacts should not be + visible to the user unless they specifically go looking for them, + at least in protocols like XMPP where blocking a contact + suppresses presence.

 @@ -150,12 +182,6 @@ Equivalent to the corresponding argument to GetContactAttributes.

- -

FIXME: if we do distributed refcounting, we should probably - rename this to 'Reference' and implement handle-refcounting - semantics first? On the other hand, if we make handles persist - for the lifetime of the connection, we can just remove this - parameter.

 @@ -171,31 +197,64 @@ - + + + + + + +

The ContactListState is + None or Waiting. In particular, this error is raised if the + Status + is not yet Connection_Status_Connected.

+ + - + -

A tristate indicating whether presence subscription is denied, +

An enumeration indicating whether presence subscription is denied, denied but pending permission, or allowed. The exact semantics - vary according to where this type is used.

+ vary according to where this type is used: see the + subscribe and + publish contact attributes for + details.

 - - Presence information cannot be seen. + + The presence subscription state is + unknown. - - Presence information cannot be seen, but permission - to see presence information has been requested. + + + Presence information cannot be seen, and either the + subscription state Removed_Remotely does not apply, or it is + not known whether that state applies. + + + + + Presence information cannot be seen because the + remote contact took action: either the local user's request to + see the remote contact's presence was denied, or the remote + contact requested to see the local user's presence but then + cancelled their request. - + + + Presence information cannot be seen. Permission + to see presence information has been requested, and the request + has not yet been declined or accepted. + + + Presence information can be seen. + type="u" tp:type="Subscription_State">

If this attribute on a contact is Yes, this connection can expect to receive their presence, along with any other information @@ -207,7 +266,7 @@ the local user's buddy list" in ICQ, for example.

-

If this attribute is No or Ask, the local user cannot generally +

If this attribute is not Yes, the local user cannot generally expect to receive presence from this contact. Their presence status as returned by GetPresences @@ -229,18 +288,30 @@ asked during the current session will ever have Ask status.

-

This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - RequestContactList.

+

If this attribute is Removed_Remotely, this indicates that the + local user has asked to receive the contact's presence at some time, + but the remote contact has rejected that request, and a local + user interface has not yet acknowledged this. It is + implementation-dependent whether contacts' subscribe attributes can + remain set to Removed_Remotely, or are reset to No, when the + connection disconnects.

+ +

After notifying the user, user interfaces MAY acknowledge a change + to subscribe=Removed_Remotely by calling either + Unsubscribe or + RemoveContacts, which will set + subscribe to No (and perhaps remove the contact). This + allows user interfaces to detect that the user has been notified + about the rejected request.

+ +

This attribute's value will be Unknown or omitted until the + ContactListState has changed to + Success.

 + type="u" tp:type="Subscription_State">

If this attribute on a contact is Yes, the local user's presence is published to that contact, along with any other information that @@ -254,12 +325,12 @@ the contact's buddy list" in ICQ, for example.

-

If this attribute is No or Ask, the +

If this attribute is not Yes, the local user's presence is not published to that contact; however, if it is Ask, the contact has requested that the local user's presence is made available to them.

-

It is implementation-dependent whether contacts' publish +

It is implementation-dependent whether contacts' publish attributes can remain set to Ask, or are reset to No, when the connection disconnects.

@@ -270,21 +341,32 @@ during the current session will ever have Ask status.

-

This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - RequestContactList.

+

If this attribute is Removed_Remotely, this indicates that the + remote contact has asked to receive the user's presence at some time, + but has then cancelled that request before a response was given by + the local user. User interfaces MAY reset publish from + Removed_Remotely to No, by calling either + Unpublish or + RemoveContacts.

+ +

If multiple factors affect whether a contact can receive the local + user's presence, this attribute SHOULD reflect the overall + result. For instance, an XMPP contact with subscription="to" or + subscription="both", but who has been blocked via + XEP-0016 Privacy + Lists, SHOULD have publish=No.

+ +

This attribute's value will be Unknown or omitted until the + ContactListState has changed to + Success.

 -

If the "publish" attribute is Ask, an optional message that was - sent by the contact asking to receive the local user's presence; - omitted if none was given.

+

If the publish attribute is Ask, an + optional message that was sent by the contact asking to receive the + local user's presence; omitted if none was given.

If the contact asking to receive our presence is also using @@ -294,17 +376,15 @@

Otherwise, this SHOULD be omitted.

-

This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received. Clients MAY wait for this by calling - RequestContactList.

+

This attribute will also be omitted until the + ContactListState has changed to + Success.

 - + + (renamed in draft 3)

If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

@@ -323,17 +403,17 @@ presence from everyone else) so nothing is ever stored.

-

If CanChangeSubscriptions +

If CanChangeContactList is true, Telepathy clients (e.g. user interfaces or address books) MAY keep a record of permission to publish and requests to subscribe locally, and attempt to restore it for each Connection. If - SubscriptionsPersist is false, clients MAY do this for all contacts; - if SubscriptionsPersist is true, clients SHOULD NOT change the state + ContactListPersists is false, clients MAY do this for all contacts; + if ContactListPersists is true, clients SHOULD NOT change the state of contacts that were not changed locally.

-

In SIMPLE (SIP), SubscriptionsPersist is false, but - CanChangeSubscriptions is true. Presence will not be received +

In SIMPLE (SIP), ContactListPersists is false, but + CanChangeContactList is true. Presence will not be received unless clients renew any subscriptions they have for each connection, in the way described. There is no server-side storage, so clients have no alternative but to maintain independent contact @@ -392,11 +472,12 @@

Contact aliases and groups on MSN have this behaviour.

 -

If this type of metadata is set on a contact with subscribe=No, - the Connection MUST cache it until disconnected, and return it - if requested. If subscription to the contact's presence is - subsequently requested, making it possible to store this metadata, - the Connection MUST store the cached value at that time.

+

If this type of metadata is set on a contact with subscribe=No + or subscribe=Rejected, the Connection MUST cache it until + disconnected, and return it if requested. If subscription to the + contact's presence is subsequently requested, making it possible + to store this metadata, the Connection MUST store the cached + value at that time.

This supports the recommended calling pattern for adding a @@ -455,13 +536,13 @@ A single contact's subscribe, publish and publish-request attributes. - + The new value of the contact's "subscribe" attribute. - + The new value of the contact's "publish" attribute. @@ -500,19 +581,32 @@

Emitted when the contact list becomes available, when contacts' basic stored properties change, when new contacts are added to the list that would be returned by - RequestContactList, + GetContactListAttributes, or when contacts are removed from that list.

This provides change notification for that list, and for - contacts' "subscribe", "publish" and - "publish-request" attributes.

+ contacts' subscribe, + publish and + publish-request attributes.

+ + +

Connection managers SHOULD also emit this signal when a contact + requests that the user's presence is published to them, even if + that contact's publish attribute is already + Ask and the publish-request has not changed.

+ + +

If the same contact sends 10 identical requests, 10 identical + signals should be emitted.

 - The new subscribe, publish and publish-request attributes of all the + The new subscribe, + publish and + publish-request attributes of all the contacts that have been added, and all the contacts for which those attributes have changed. @@ -522,15 +616,15 @@ The contacts that have been removed from the list that would be returned by - RequestContactList. + GetContactListAttributes. This also implies that they have subscribe = No and publish = No; contacts MUST NOT be listed both here and in Changes. - +

If true, presence subscription and publication can be changed using the @@ -590,10 +684,10 @@ request, with the given message, if allowed by the underlying protocol.

-

For contacts with subscribe=No, this method SHOULD request that - the contact allows the local user to subscribe to their presence; - in general, this will change their publish attribute from No - to Ask (although it could change directly from No to Yes in some +

For contacts with subscribe=No or subscribe=Rejected, this method + SHOULD request that the contact allows the local user to subscribe + to their presence; in general, this will change their publish + attribute to Ask (although it could change directly to Yes in some situations).

Any state changes that immediately result from this request MUST @@ -606,9 +700,20 @@

If the remote contact accepts the request, their subscribe - attribute will later change from Ask to Yes; if they explicitly - reject the request (in protocols that allow this), their subscribe - attribute will later change from Ask to No.

+ attribute will later change from Ask to Yes.

+ +

If the remote contact explicitly rejects the request (in protocols + that allow this), their subscribe attribute will later change from + Ask to Rejected.

+ +

If the subscription request is cancelled by the local user, the + contact's subscribe attribute will change from Ask to No.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

 + + + The ContactListState is None + or Waiting. + + It was not possible to perform the requested action, because - CanChangeSubscriptions is false. + CanChangeContactList is false. @@ -714,6 +825,12 @@

This makes it easy for user interfaces to see what practical effect this method had.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

It was not possible to perform the requested action, because - CanChangeSubscriptions is false. + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. @@ -745,7 +868,7 @@

If possible, this method SHOULD set the contacts' subscribe and publish attributes to No, remove any stored aliases for those contacts, and remove the contacts from the result of - RequestContactList.

+ GetContactListAttributes.

This method SHOULD succeed even if it was not possible to carry out the request entirely or for all contacts (for instance, if there is an @@ -764,6 +887,12 @@ contact list's state), then consult its local cache of the contact list's state to see whether the contact is still there.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. @@ -801,6 +936,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. @@ -838,6 +979,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.

+ +

This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml new file mode 100644 index 000000000..30b25f403 --- /dev/null +++ b/spec/Connection_Interface_Power_Saving.xml @@ -0,0 +1,101 @@ + + + Copyright (C) 2007 Collabora Limited + +

This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +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.

+ +

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.

+ + + + +

Turn power saving mode on or off.

+ + +

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

+ + +

Errors raised by this method indicate that power saving could not be + enabled, which SHOULD NOT generally be treated as fatal.

+ + + If the CM cannot switch modes, either because of the + protocol (NotImplemented), or because of the service + (NotAvailable), Mission Control (or whoever manages this) + should be made aware. The error could be ignored or, in the extreme, + be fascist and disconnect the account. + + + + + + True when activating power saving, false when deactivating. + + + + + + + The current connection has no power saving features. + + + + + + + + +

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

+ + + + + + + The new state of the power saving feature. + + + + The PowerSavingActive + property changed. + + + + + diff --git a/spec/Makefile.am b/spec/Makefile.am index 4343e06b2..40d58ee8b 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -1,5 +1,6 @@ EXTRA_DIST = \ Account_Interface_Avatar.xml \ + Account_Interface_Minimum_Presence.xml \ Account_Interface_Storage.xml \ Account_Manager.xml \ Account.xml \ @@ -14,9 +15,11 @@ EXTRA_DIST = \ Call_Stream_Endpoint.xml \ Channel_Dispatch_Operation.xml \ Channel_Dispatcher.xml \ + Channel_Dispatcher_Future.xml \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ + Channel_Interface_Addressing.xml \ Channel_Interface_Anonymity.xml \ Channel_Interface_Call_State.xml \ Channel_Interface_Chat_State.xml \ @@ -32,10 +35,12 @@ EXTRA_DIST = \ Channel_Interface_Password.xml \ Channel_Interface_Room.xml \ Channel_Interface_Service_Point.xml \ + Channel_Interface_SMS.xml \ Channel_Interface_Splittable.xml \ Channel_Interface_Transfer.xml \ Channel_Interface_Tube.xml \ Channel_Request.xml \ + Channel_Request_Future.xml \ Channel_Type_Call.xml \ Channel_Type_Contact_List.xml \ Channel_Type_Contact_Search.xml \ @@ -55,6 +60,7 @@ EXTRA_DIST = \ Client_Interface_Requests.xml \ Client_Observer.xml \ Connection_Future.xml \ + Connection_Interface_Addressing.xml \ Connection_Interface_Aliasing.xml \ Connection_Interface_Anonymity.xml \ Connection_Interface_Avatars.xml \ @@ -70,6 +76,7 @@ EXTRA_DIST = \ Connection_Interface_Forwarding.xml \ Connection_Interface_Location.xml \ Connection_Interface_Mail_Notification.xml \ + Connection_Interface_Power_Saving.xml \ Connection_Interface_Presence.xml \ Connection_Interface_Privacy.xml \ Connection_Interface_Renaming.xml \ @@ -85,6 +92,7 @@ EXTRA_DIST = \ Media_Stream_Handler.xml \ Properties_Interface.xml \ Protocol.xml \ + Protocol_Interface_Addressing.xml \ Protocol_Interface_Avatars.xml \ Protocol_Interface_Presence.xml \ template.xml diff --git a/spec/Protocol.xml b/spec/Protocol.xml index 50562c9b6..e37fe224d 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -216,6 +216,20 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy Jabber/XMPP (including Google Talk), or tel for the PSTN.

+

A more exhaustive list of addressable vCard fields can be found in + the Protocol's Addressing interface's + AddressableVCardFields.

+ +

It is not necessarily valid to interpret contacts' identifiers + as values of this vCard field. For instance, telepathy-sofiasip + supports contacts whose identifiers are of the form + sip:jenny@example.com or tel:8675309, which would not normally + both be represented by any single vCard field. Arbitrary + handles/identifiers as vCard fields are represented + through the Connection's + Addressing.DRAFT + contact attributes.

+

This is taken from Mission Control profiles as used on Maemo 5. One valid use of this field is to answer the question: given a @@ -225,14 +239,6 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy protocols that handle x-jabber, then offer the user a list of accounts for those protocols and/or the option to create a new account for one of those protocols.

- -

It is not necessarily valid to interpret contacts' identifiers - as values of this vCard field. For instance, telepathy-sofiasip - supports contacts whose identifiers are of the form - sip:jenny@example.com or tel:8675309, which would not normally - both be represented by any single vCard field. Representing - arbitrary handles/identifiers as vCard fields is a topic for - future work.

Connection managers with a .manager file @@ -423,6 +429,6 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy - + diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml new file mode 100644 index 000000000..3722c3b81 --- /dev/null +++ b/spec/Protocol_Interface_Addressing.xml @@ -0,0 +1,300 @@ + + + + Copyright © 2010 Collabora Ltd. + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (as draft) + +

An interface for protocols that support multiple forms of + addressing contacts, for example through vCard addresses and URIs.

+ +

If the ConnectionManager has a .manager file, and it + supports this interface, the interface's immutable properties + must be represented in the file; the representation is described as + part of the documentation for each property.

+ +

For instance, a SIP connection manager might have the + following lines in the .manager file.

+ +
+[Protocol sip]
+AddressableVCardFields=tel;x-sip;
+AddressableURISchemes=tel;sip;
+
+ + + + +

The vCard fields that can be used to request a contact with + normalized to lower case. If the URL vCard + field is addressable, a colon, followed by the supported URI + schemes will be concatenated.

+ +

For example: ["tel", "x-sip"].

+ +

The url vCard field MUST NOT appear here; see + AddressableURISchemes instead.

+ + +

In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

+ + +

This property should only be used when the connection is + offline. When it is connected the addressable fields should be + retrieved from the + Requests.RequestableChannelClasses's + TargetVCardField fixed-property instead.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file if it is non-empty, using the key + AddressableVCardFields. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.

+ +

Well-known vCard fields:

+ +
+
tel
+
The TEL vCard field. Used for phone numbers.
+
x-sip
+
The X-SIP vCard field. Used for SIP addresses.
+
x-aim
+
The X-AIM vCard field. Used for AIM user IDs.
+
x-icq
+
The X-ICQ vCard field. Used for ICQ UINs.
+
x-skype
+
The X-SKYPE vCard field. Used for Skype user names or + telephone numbers. There is also a X-SKYPE-USERNAME field, + but for Telepathy purposes, x-skype is preferred
+
x-groupwise
+
The X-GROUPWISE vCard field. Used for Groupwise contacts.
+
x-gadugadu
+
The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.
+
x-jabber
+
The X-JABBER vCard field. Used for XMPP JIDs.
+
x-msn
+
The X-MSN vCard field. Used for MSN contacts.
+
x-yahoo
+
The X-YAHOO vCard field. Used for Yahoo! IDs.
+
+ + + + + + +

The URI schemes that are supported by this protocol.

+ +

For example: ["tel", "sip"].

+ +

This property should only be used when the connection is + offline. When it is connected the addressable URI schemes should be + retrieved from the + Requests.RequestableChannelClasses's + TargetURIScheme fixed-property instead.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file if it is non-empty, using the key + AddressableURISchemes. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.

+ +

Well-known URI schemes:

+ +
+
sip
+
SIP protocol. + For example: sip:julien@example.com.
+
sips
+
Secure (encrypted) SIP protocol. + For example: sips:julien@example.com.
+
tel
+
Used for telephone numbers. + For example: tel:+12065551234.
+
xmpp
+
XMPP protocol. + For example: xmpp:julien@example.com.
+
msnim
+
For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be add; the + contact field in the query string is used to + identify the contact. + For example: msnim:add?contact=julien.
+
aim
+
For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be addbuddy; the + screenname field in the query string is used to + identify the contact. + For example: aim:addbuddy?screenname=julien.
+
skype
+
Skype protocol. + For example: skype:julien.
+
ymsgr
+
For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be addfriend; the + query string is used to identify the contact. + For example: ymsgr:addfriend?julien.
+
gg
+
Gadu-Gadu protocol. + For example: gg:julien.
+
+ + + + + +

Attempt to normalize the given vCard address. Where possible, this + SHOULD return an address that would appear in the + org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses + attribute for a contact on a connected + Connection. +

+ +

If full normalization requires network activity or is otherwise + impossible to do without a Connection, + this method SHOULD perform a best-effort normalization.

+ +

An example would be a vCard TEL field with a formatted + number in the form of +1 (206) 555 1234, this would be + normalized to +12065551234.

+ +

This method MAY simply raise NotImplemented on some + protocols, if it has no use.

+ + + + + The vCard field of the address we are normalizing. The + field name SHOULD be in lower case, and MUST appear in + AddressableVCardFields. + + + + + + The address to normalize. + + + + + + The vCard address, normalized as much as possible. + + + + + + + The vCard field is not supported (it is not in + AddressableVCardFields). + + + + + + The address is syntactically incorrect. + + + + + + + +

Attempt to normalize the given contact URI. Where possible, this + SHOULD return an address that would appear in the + org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris + attribute for a contact on a connected + Connection. +

+ +

If full normalization requires network activity or is otherwise + impossible to do without a Connection, + this method SHOULD perform a best-effort normalization.

+ +

Example: xmpp:eitan@EXAMPLE.COM would be normalized to + xmpp:eitan@example.com.

+ +

This method MAY simply raise NotImplemented on some + protocols, if it has no use.

+ + + + + The URI to normalize. The URI's scheme (i.e. the part before + the first colon) MUST appear in + AddressableURISchemes. + + + + + + A URI, normalized as much as possible. + + + + + + + The URI scheme is not supported (it is not in + AddressableURISchemes). + + + + + + The URI is syntactically incorrect. + + + + + + + + diff --git a/spec/all.xml b/spec/all.xml index af6863b4b..2a7673bb7 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.11 +0.19.12 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation @@ -33,6 +33,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -44,6 +45,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -59,6 +61,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -110,6 +113,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -124,6 +128,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -174,6 +179,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -185,9 +191,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + diff --git a/spec/errors.xml b/spec/errors.xml index e14dacbe5..a5368c02f 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -293,7 +293,7 @@ Raised if the length in bytes of the server certificate, or the depth of the - sever certificate chain exceed the limits imposed by the crypto + server certificate chain exceeds the limits imposed by the crypto library. This corresponds to Cert_Limit_Exceeded in the @@ -483,6 +483,14 @@ + + + + Raised when the requested functionality is not yet available, but is + likely to become available after some time has passed. + + + Copyright © 2005-2010 Collabora Limited Copyright © 2005-2009 Nokia Corporation diff --git a/spec/generic-types.xml b/spec/generic-types.xml index c017ba595..014f8ada4 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -195,4 +195,21 @@ + + + A mapping from object path to the immutable properties of + the object. + + + The object path of an object + + + + + The immutable properties of the object + + + + -- cgit v1.2.1