From 2948ab95e843a969840d9e2696103e9b63282c92 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 25 May 2010 15:45:24 +0100 Subject: Update to spec 0.19.6 --- spec/Account.xml | 38 ++ spec/Call_Content_Interface_Media.xml | 2 +- spec/Call_Content_Interface_Mute.xml | 83 +++ spec/Channel_Dispatch_Operation.xml | 66 ++ spec/Channel_Dispatcher.xml | 4 +- spec/Channel_Interface_Anonymity.xml | 68 ++ spec/Channel_Interface_DTMF.xml | 179 ++++- spec/Channel_Interface_Messages.xml | 4 + spec/Channel_Interface_Service_Point.xml | 85 +++ spec/Channel_Request.xml | 5 +- spec/Channel_Type_Call.xml | 21 +- spec/Client_Handler.xml | 10 + spec/Client_Interface_Requests.xml | 6 +- spec/Client_Observer.xml | 25 +- spec/Connection_Interface_Anonymity.xml | 170 +++++ spec/Connection_Interface_Capabilities.xml | 2 +- spec/Connection_Interface_Cellular.xml | 82 +++ spec/Connection_Interface_Contact_Groups.xml | 412 ++++++++++++ spec/Connection_Interface_Contact_Info.xml | 11 + spec/Connection_Interface_Contact_List.xml | 837 ++++++++++++++++++++++++ spec/Connection_Interface_Forwarding.xml | 365 +++++++++-- spec/Connection_Interface_Location.xml | 36 +- spec/Connection_Interface_Mail_Notification.xml | 14 +- spec/Connection_Interface_Service_Point.xml | 135 ++++ spec/Makefile.am | 8 + spec/all.xml | 13 +- spec/errors.xml | 23 + spec/generic-types.xml | 30 + 28 files changed, 2628 insertions(+), 106 deletions(-) create mode 100644 spec/Call_Content_Interface_Mute.xml create mode 100644 spec/Channel_Interface_Anonymity.xml create mode 100644 spec/Channel_Interface_Service_Point.xml create mode 100644 spec/Connection_Interface_Anonymity.xml create mode 100644 spec/Connection_Interface_Cellular.xml create mode 100644 spec/Connection_Interface_Contact_Groups.xml create mode 100644 spec/Connection_Interface_Contact_List.xml create mode 100644 spec/Connection_Interface_Service_Point.xml (limited to 'spec') diff --git a/spec/Account.xml b/spec/Account.xml index 4b112cb4d..f315c15d9 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -480,6 +480,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + +

If true, a change to the presence of this account is + in progress.

+ +

Whenever RequestedPresence is set on + an account that could go online, or whenever an account with a + non-offline RequestedPresence becomes + able to go online (for instance because + Enabled or + Valid changes to True), + ChangingPresence MUST change to True, and the two property changes MUST + be emitted in the same + AccountPropertyChanged signal, before the + Set method returns.

+ +

When the account manager succeeds or fails in changing the presence, + or the connection disconnects due to an error, ChangingPresence MUST + change to False as part of the same + AccountPropertyChanged signal.

+ + +

This allows UIs to indicate that a presence change is in progress + or has finished, even if the change was initiated by a different + UI.

+ +

For instance, Maemo 5 and Empathy indicate a presence change by + having the presence indicator alternate between the + RequestedPresence + and the CurrentPresence; they should + start blinking when ChangingPresence becomes true, and stop when it + becomes false.

+ + + + + diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 2b3eb65d5..8b9a17c84 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -61,7 +61,7 @@ - + Extra parameters for this codec diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml new file mode 100644 index 000000000..eea724f59 --- /dev/null +++ b/spec/Call_Content_Interface_Mute.xml @@ -0,0 +1,83 @@ + + + Copyright © 2005-2010 Nokia Corporation + Copyright © 2005-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. + + + + (draft version, not API-stable) + + +

Interface for calls which may be muted. This only makes sense + for channels where audio or video is streaming between members.

+ +

Muting a call content indicates that the user does not wish to send + outgoing audio or video.

+ +

Although it's client's responsibility to actually mute the microphone + or turn off the camera, using this interface the client can also + inform the CM and other clients of that fact.

+ +

For some protocols, the fact that the content is muted needs to be + transmitted to the peer; for others, the notification to the peer is + only informational (eg. XMPP), and some protocols may have no notion + of muting at all.

+ + + + + + Emitted to indicate that the mute state has changed for this call content. + This may occur as a consequence of the client calling + Muted, or as an indication that another + client has (un)muted the content. + + + + + True if the content is now muted. + + + + + + + True if the content is muted. + + + + + + + True if the client has muted the content. + + + + +

Inform the CM that the call content has been muted or unmuted by + che client.

+ +

It is the client's responsibility to actually mute or unmute the + microphone or camera used for the content. However, the client + MUST call this whenever it mutes or unmutes the content.

+ + + + + + diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 26d9b579f..6ec69a67b 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -370,6 +370,72 @@ + + + At the time of writing, no released implementation of the + Channel Dispatcher implements this method; clients should fall + back to calling HandleWith. + + +

A variant of HandleWith allowing the + approver to pass an user action time. This timestamp will be passed + to the Handler when HandleChannels + is called.

+ + + + +

The well-known bus name (starting with + org.freedesktop.Telepathy.Client.) of the channel + handler that should handle the channel, or the empty string + if the client has no preferred channel handler.

+ + + + + +

The time at which user action occurred.

+ + + + + + + The selected handler is non-empty, but is not a syntactically + correct DBus_Bus_Name or does not start with + "org.freedesktop.Telepathy.Client.". + + + + + The selected handler is temporarily unable to handle these + channels. + + + + + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + + + + + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + + + + +

Emitted when this dispatch operation finishes. The dispatch diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index daee24c9c..474c809f2 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -164,7 +164,7 @@ + tp:type="User_Action_Timestamp">

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. @@ -305,7 +305,7 @@ + tp:type="User_Action_Timestamp">

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

diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml new file mode 100644 index 000000000..7477f9637 --- /dev/null +++ b/spec/Channel_Interface_Anonymity.xml @@ -0,0 +1,68 @@ + + + + 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 + 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 version, not API-stable) + + +

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

+ + + + + The list of initially requested anonymity modes on the channel. This + MUST NOT change, and is Requestable. + + + + + + Whether or not the anonymity settings are required for this channel. + This MUST NOT change, and is Requestable. + + + + + +

This is the ID that the remote user of the channel MAY see + (assuming there's a single ID). For example, for SIP connections + where the From address has been scrambled by the CM, the scrambled + address would be available here for the client to see. This is + completely optional, and MAY be an empty string ("") in + cases where anonymity modes are not set, or the CM doesn't know + what the remote contact will see, or any other case where this + doesn't make sense.

+ +

This MAY change over the lifetime of the channel, and SHOULD NOT + be used with the Request interface.

+ + + + + + diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index 7545ff6f3..bd20f6ed3 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -1,8 +1,8 @@ - Copyright (C) 2005, 2006 Collabora Limited - Copyright (C) 2005, 2006 Nokia Corporation - Copyright (C) 2006 INdT + Copyright © 2005-2010 Collabora Limited + Copyright © 2005-2010 Nokia Corporation + Copyright © 2006 INdT

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -21,31 +21,57 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + An interface that gives a Channel the ability to send DTMF events over + audio streams which have been established using the StreamedMedia channel + type. The event codes used are in common with those defined in RFC4733, and are + listed in the DTMF_Event enumeration. + + - A stream ID as defined in the StreamedMedia channel type. + A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the tone SHOULD be sent to all + eligible streams in the channel. A numeric event code from the DTMF_Event enum. + - Start sending a DTMF tone on this stream. Where possible, the tone - will continue until StopTone is called. - On certain protocols, it may - only be possible to send events with a predetermined length. In this - case, the implementation may emit a fixed-length tone, and the StopTone - method call should return NotAvailable. +

Start sending a DTMF tone to all eligible streams in the channel. + Where possible, the tone will continue until + StopTone is called. On certain protocols, + it may only be possible to send events with a predetermined length. In + this case, the implementation MAY emit a fixed-length tone, and the + StopTone method call SHOULD return NotAvailable.

+ + The client may wish to control the exact duration and timing of the + tones sent as a result of user's interaction with the dialpad, thus + starting and stopping the tone sending explicitly. + + +

Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.

 - The given stream ID was invalid. + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. - The requested event is not available on this stream. + There are no eligible audio streams. + + + + + DTMF tones are already being played. @@ -53,28 +79,136 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - A stream ID as defined in the StreamedMedia channel type. + A stream ID as defined in the StreamedMedia channel + type. This argument is included for backwards compatibility and MUST + be ignored by the implementations - the sending SHOULD be stoped in + all eligible streams in the channel. + + + + Stop sending any DTMF tones which have been started using the + StartTone or + MultipleTones methods. + If there is no current tone, this method will do nothing. + If MultipleTones was used, the client should not assume the + sending has stopped immediately; instead, the client should wait + for the StoppedTones signal. + + On some protocols it might be impossible to cancel queued tones + immediately. + + + + + + + The given stream ID was invalid. Deprecated, since stream IDs + are ignored. + + + + + Continuous tones are not supported by this stream. Deprecated, + since stream IDs are ignored. + + + + + + + + + A string representation of one or more DTMF + events. - Stop sending any DTMF tone which has been started using the - StartTone - method. If there is no current tone, this method will do nothing. +

Send multiple DTMF events to all eligible streams in the channel. + Each character in the Tones string must be a valid DTMF event + (as defined by + RFC4733). + Each tone will be played for a pre-defined number of milliseconds, + followed by a pause before the next tone is played. The + duration/pause is defined by the protocol or connection manager.

+ + In cases where the client knows in advance the tone sequence it wants + to send, it's easier to use this method than manually start and stop + each tone in the sequence. + + +

Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.

 - The given stream ID was invalid. + The supplied Tones string was invalid. - Continuous tones are not supported by this stream. + There are no eligible audio streams. + + + + + DTMF tones are already being played. + + + + Indicates whether there are DTMF tones currently being sent in the + channel. If so, the client should wait for + StoppedTones signal before trying to + send more tones. + + + + + + +

If non-empty in a channel request that will create a new channel, + the connection manager should send the tones immediately after + at least one eligible audio stream has been created in the + channel.

+ +

This property is immutable (cannot change).

+ + + + + + + DTMF string (one or more events) that is to be played. + + + +

DTMF tone(s)are being sent to all eligible streams in the channel. + The signal is provided to indicating the fact that the streams are + currently being used to send one or more DTMF tones, so any other + media input is not getting through to the audio stream. It also + serves as a cue for the + StopTone method.

+ + + + + + + True if the DTMF tones were actively cancelled via + StopTone. + + +

DTMF tones have finished playing on streams in this channel.

+ + + 0 @@ -125,15 +259,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.D - - - An interface that gives a Channel the ability to send DTMF events over - audio streams which have been established using the StreamedMedia channel - type. The event codes used are in common with those defined in RFC4733, and are - listed in the DTMF_Event enumeration. - - diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 566e1166d..b33633543 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -314,6 +314,10 @@ USA.

The contact who sent the message. If 0 or omitted, the contact who sent the message could not be determined.
+
sender-nickname (s)
+
The nickname chosen by the sender of the message, which can be + different for each message in a conversation.
+
message-type (u - Channel_Text_Message_Type)
The type of message; if omitted, diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml new file mode 100644 index 000000000..5a0d540e5 --- /dev/null +++ b/spec/Channel_Interface_Service_Point.xml @@ -0,0 +1,85 @@ + + + Copyright © 2005-2010 Nokia Corporation + Copyright © 2005-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.

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

An interface for channels + that can indicate when/if they are connected to some form + of service point. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.

+ +

Note that while the majority of examples given in this + documentation are for GSM calls, they could just as easily be + SIP calls, GSM SMS's, etc.

+ + + + +

This property is used to indicate that the channel target is a + well-known service point. Please note that the CM (or lower layers + of the stack or network) may forward the connection to other other + service points, which the CM SHOULD indicate via + ServicePointChanged + signal.

+ +

This property SHOULD be set for channel requests that are + specifically targeting service points.

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

Emitted when a channel changes the service point that it's connected to. This + might be a new call being connected to a service, a call connected to + a service being routed to a different service + (ie, an emergency call being routed from a generic emergency PSAP to + a poison control PSAP), or any number of other things.

+ +

Note that this should be emitted as soon as the CM has been notified + of the switch, and has updated its internal state. The CM MAY still + be in the process of connecting to the new service point.

+ + + + + The new service point that is being used. + + + + + + + diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 4de78b400..1d59eb874 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -55,14 +55,11 @@ + type="x" tp:type="User_Action_Timestamp" access="read">

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

-

This corresponds to the _NET_WM_USER_TIME property in - EWMH.

-

This property is set when the channel request is created, and can never change.

 diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index dacf906b1..f1d0f0e06 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -381,6 +381,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + The call has been muted by the local user, e.g. using the + Mute.DRAFT interface. This flag SHOULD only be set if + there is at least one Content, and all Contents are locally muted; + it makes sense on calls in state Call_State_Pending_Receiver or + Call_State_Accepted. + + + + + +

The call was forwarded. If known, the handle of the contact + the call was forwarded to will be indicated by the Actor member + of a Call_State_Reason struct.

+ + @@ -557,7 +576,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + The new value of the CallStateReason property. diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index c6edf3376..10a16bd69 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -106,6 +106,14 @@ matches closely related Text channels by their Bundle property. (This is use-case dis5)

+ +

For service-activatable handlers, this property should be specified + in the handler's .client file as follows:

+ +
+[org.freedesktop.Telepathy.Client.Handler]
+BypassApproval=true
+
 @@ -264,6 +272,8 @@ org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true is to be handled for some reason not involving user action. Handlers SHOULD use this for focus-stealing prevention, if applicable. + This property has the same semantic as User_Action_Timestamp + but is unsigned for historical reasons. diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index f777a2a96..f4c11087d 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -119,9 +119,11 @@ properties as possible, given that constraint.

In particular, the properties Requests - and Requests, + UserActionTime + and Account MUST be included.

diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index a2256a753..912edaf4f 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -194,9 +194,17 @@ org.freedesktop.Telepathy.Channel.Requested b=true its ObserverChannelFilter

-

When activatable client having this property disappears from the bus - and there are channels matching its ObserverChannelFilter, - ObserveChannels will be called immediately to reactivate it again.

+

When an activatable client having this property disappears from the + bus and there are channels matching its ObserverChannelFilter, + ObserveChannels will be called immediately to reactivate it + again. Such clients should specify this property in their + .client file as follows:

+ +
+[org.freedesktop.Telepathy.Client.Observer]
+Recover=true
+
+

This means that if an activatable Observer crashes, it will be restarted as soon as possible; while there is an unavoidable @@ -212,8 +220,8 @@ org.freedesktop.Telepathy.Channel.Requested b=true

When the ObserveChannels method is called due to observer recovery, - the "Observer_Info" dictionary will contain one extra item with key - "recovering" and boolean value of True.

+ the Observer_Info dictionary will contain one extra item + mapping the key "recovering" to True.

 @@ -336,8 +344,11 @@ org.freedesktop.Telepathy.Channel.Requested b=true
recovering - b
-
True if ObserveChannels was called on existing channel due to - observer recovery, otherwise False. +
True if ObserveChannels was called for an existing + channel (due to the Recover + property being True); False or omitted + otherwise. + This allows observers to distinguish between new channels (the normal case), and existing channels that were given to the observer in order diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml new file mode 100644 index 000000000..5426b5d50 --- /dev/null +++ b/spec/Connection_Interface_Anonymity.xml @@ -0,0 +1,170 @@ + + + + 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 + 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 version, not API-stable) + + +

An interface to support anonymity settings on a per-connection basis. + This defines what personal identifying information a remote contact + may or may not see. For example, GSM might use this for CLIR, while + SIP might use this for privacy service requests.

+ + + + +

Flags for the various types of anonymity modes. These modes are solely to + inform the CM of the desired anonymous settings. It is up to the + CM to determine whether the anonymity modes should be handled within + the CM itself, or whether the network that a CM might be talking to + should be enforcing anonymity.

+ +

CMs MAY support only a subset of these modes, and specific + connections MAY support none at all.

+ + + + +

Obscure any information that provides user identification, + user-agent identification or personal details. Examples of this + information might be GSM CallerID, SIP from address, various + informational email headers, etc.

+ +

The CM should scrub/replace any of this information before + passing messages or data onto the network. Note that a CM which + has the option of obscuring the information at the CM or privacy + 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. + If they are set, the CM MUST respect Client_Info and ignore + Show_Client_Info.

+ + + + + +

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

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 + in SupportedAnonymityModes to indicate + its support for explicitly hiding and publicising client information. +

+ + + + + +

Obscure any originating IP address information, contact URIs, + and anonymize all traffic involved with sending/receiving any + media streams or call content. + Examples of this include the "headers" portions of + RFC 3323 as + well as the History-Info (described in + RFC 4244) + for a SIP CM.

+ +

This SHOULD have the effect of hiding address information from + the remote contact (ie, the contact cannot know what IP address + the session is originated from). Obviously the network still needs + to be able to route information between contacts, so this provides + no guarantees of what can be seen by intermediaries.

+ + + + + + + The anonymity modes supported by the CM for this connection. Once + Connection.Status has moved to Connected, this property MUST NOT change. + + + + + +

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. + 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 RequestConnection, + see Conn_Mgr_Param_Flags for more information.

+ + + + + +

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

+ +

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

+ + + + + An unsupported mode was supplied. Supported modes are specified + in the SupportedAnonymityModes property, and this should be + checked prior to setting AnonymityModes. + + + + + + + + Emitted when the anonymity mode has changed. + + + + + The new anonymity modes for this connection. + + + + + + + diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index 10d8102f9..56f923170 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -231,7 +231,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + type="a(usuu)" tp:type="Contact_Capability[]">

The same structs that would be returned by GetCapabilities diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml new file mode 100644 index 000000000..c2a25503a --- /dev/null +++ b/spec/Connection_Interface_Cellular.xml @@ -0,0 +1,82 @@ + + + + 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 + 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 version, not API-stable) + + +

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

+ + + + +

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.

+

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.

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

The International Mobile Subscriber Identifier, if it exists. This + would originate from a SIM card. If the IMSI is unknown, this will + contain an empty string ("").

+ + + + + + Emitted when the IMSI for the connection changes. This sort of thing + is rare, but could happen on cellular phones that allow hot-swapping + of SIM cards. In the case of SIM swapping, this signal would be + emitted twice; the first time while the SIM is being ejected (with an + empty string), and the second time after a new SIM has been inserted + (assuming that the IMSI can be determined from the new SIM). + + + + + The new IMSI value. This may be an empty string in the case where + the IMSI is being reset or removed. + + + + + + + diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml new file mode 100644 index 000000000..35465a76f --- /dev/null +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -0,0 +1,412 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 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.

+ + + + + (draft 1) + + +

An interface for connections in which contacts can be placed in + user-defined groups.

+ + + + +

True if each contact can be in at most one group; false if each + contact can be in many groups.

+ +

This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.

+ + + + + +

Indicates the extent to which contacts' groups can be set and + stored.

+ +

This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.

+ + + + + +

The names of groups of which a contact is a member.

+ +

Change notification is via + GroupsChanged, + GroupRenamed and + GroupsRemoved.

+ + + + + +

The names of all groups that currently exist. This may be a + larger set than the union of all contacts' groups + contact attributes, if the connection allows groups to be + empty.

+ +

Change notification is via + GroupsCreated, + GroupRenamed and + GroupsRemoved.

+ + + + + + Emitted when new, empty groups are created. This will often be + followed by GroupsChanged signals that + add some members. + + + + The names of the new groups. + + + + + +

Emitted when a group is renamed. If the group was not empty, + immediately after this signal is emitted, + GroupsChanged MUST signal + that the members of that group were removed from the old name + and added to the new name.

+ +

On connection managers where groups behave like tags, this signal + will probably only be emitted when + RenameGroup is called, and renaming a + group from another client MAY be signalled as a + GroupsChanged signal instead.

+ + +

On protocols like XMPP, another resource "renaming a group" is + indistinguishable from changing contacts' groups individually.

+ + + + + The old name of the group. + + + + The new name of the group. + + + + + + Emitted when one or more groups are removed. If they had members at + the time that they were removed, then immediately after this signal is + emitted, GroupsChanged MUST signal + that their members were removed. + + + + The names of the groups. + + + + + + Emitted when contacts' groups change. + + + + The relevant contacts. + + + + The names of groups to which the contacts were + added. + + + + The names of groups from which the contacts were + removed. + + + + + +

Add the given contact to the given groups (creating new groups + if necessary), and remove them from all other groups.

+ + +

This is the easiest and most correct way to implement user + interfaces that display a single contact with a list of groups, + resulting in a user expectation that when they apply the changes, + the contact's set of groups will become exactly what was + displayed.

+ + +

If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.

+ + +

In protocols like XMPP where groups behave like tags, a group + with no members has no protocol representation.

+ + +

Any GroupsCreated, + GroupsChanged and + GroupsRemoved signals that result from + this method call MUST be emitted before the method returns.

+ + + + The contact to alter. + + + + The set of groups which the contact should be + in. + + + + + + + + Raised if DisjointGroups + is true and the list of groups has more than one + member. + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + + + + +

Add the given members to the given group (creating it if necessary), + and remove all other members.

+ + +

This is the easiest and most correct way to implement user + interfaces that display a single group with a list of contacts, + resulting in a user expectation that when they apply the changes, + the groups's set of members will become exactly what was + displayed.

+ + +

If DisjointGroups is true, + this will also remove each member from their previous group.

+ +

If the user is removed from a group of which they were the only + member, the group MAY be removed automatically.

+ +

Any GroupsCreated, + GroupsChanged and + GroupsRemoved signals that result from + this method call MUST be emitted before the method returns.

+ + + + The group to alter. + + + + The set of members for the group. If this set is + empty, this method MAY remove the group. + + + + + + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + + + + +

Add the given members to the given group, creating it if + necessary.

+ +

If DisjointGroups is true, + this will also remove each member from their previous group.

+ + +

This is good for user interfaces in which you can edit groups + via drag-and-drop.

+ + +

Any GroupsCreated, + GroupsChanged and + GroupsRemoved signals that result from + this method call MUST be emitted before the method returns.

+ + + + The group to alter. + + + + The set of members to include in the group. + + + + + + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + + + + +

Remove the given members from the given group.

+ + +

This is good for user interfaces in which you can edit groups + via drag-and-drop.

+ + +

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

+ + + + The group to alter. If it does not exist, then it has + no members by definition, so this method SHOULD return + successfully. + + + + The set of members to remove from the group. It is not + an error to remove members who are already not in the group. + If there are no members left in the group afterwards, the group MAY + itself be removed. + + + + + + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + + + + +

Remove all members from the given group, then remove the group + itself. If the group already does not exist, this method SHOULD + return successfully.

+ +

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

+ + + + The group to remove. + + + + + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + + + + +

Rename the given group.

+ +

On protocols where groups behave like tags, this is an API + short-cut for adding all of the group's members to a group with + the new name, then removing the old group.

+ + +

Otherwise, clients can't perform this operation atomically, even + if the connection could.

+ + +

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

+ + + + The group to rename. + + + + The new name for the group. + + + + + + + + Raised if GroupStorage + is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + + + + Raised if there is no group with that + name. + + + Raised if there is already a group with the new + name. + + + + + + + diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index 91a948e6c..ce77a56af 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -504,6 +504,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

The same value that would be returned by + GetContactInfo for this contact. + Omitted from the result if the contact's info + is not known.

+ + + diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml new file mode 100644 index 000000000..3ded87083 --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,837 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 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.

+ + + + (draft 1) + + +

An interface for connections that have any concept of a list of + known contacts (roster, buddy list, friends list etc.)

+ + +

On many protocols, there's a server-side roster (as in XMPP), + or a set of server-side lists that can be combined to form a + roster (as in MSN).

+ +

In some protocols (like link-local XMPP), while there might not be + any server or roster, it's possible to list "nearby" contacts.

+ +

In Telepathy 0.18 and older, we represented contact lists as a + collection of ContactList channels. This is remarkably difficult to + work with in practice - every client that cares about contact lists + has to take the union of some hard-to-define set of these + channels - and conflicts with the idea that channels that cannot + be dispatched to a handler should be closed.

+ + +

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

+ + +

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

+ + + + + +

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

+ +

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:

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

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.

+ + +

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.

+ + +

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

+ + + + + +

A list of strings indicating which D-Bus interfaces the calling + process is interested in. Equivalent to the corresponding argument + to GetContactAttributes.

+ + + + + +

Whether to hold the handles on behalf of the calling process. + 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.

+ + + + + +

A dictionary mapping the contact handles to contact attributes, + equivalent to the result of GetContactAttributes.

+ + + + + + + + + + + +

A tristate indicating whether presence subscription is denied, + denied but pending permission, or allowed. The exact semantics + vary according to where this type is used.

+ + + + Presence information cannot be seen. + + + Presence information cannot be seen, but permission + to see presence information has been requested. + + + Presence information can be seen. + + + + + +

If this attribute on a contact is Yes, this connection can + expect to receive their presence, along with any other information + that has the same access control.

+ + +

This is subscription="from" or subscription="both" in XMPP, + the "forward list" on MSN, or the contact being "added to + the local user's buddy list" in ICQ, for example.

+ + +

If this attribute is No or Ask, the local user cannot generally + expect to receive presence from this contact. Their presence status + as returned by GetPresences + is likely to be (Unknown, "unknown", ""), unless the local user + can temporarily see their presence for some other reason (for + instance, on XMPP, contacts seen in chatrooms will temporarily + have available presence).

+ +

If this attribute is Ask, this indicates that the local user has + asked to receive the contact's presence at some time. It is + implementation-dependent whether contacts' subscribe attributes + can remain set to Ask, or are reset to No, when the connection + disconnects.

+ + +

Some protocols store the fact that we wishes to see a contact's + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have been + asked during the current session will ever have Ask status.

+ + + + + + +

If this attribute on a contact is Yes, the local user's presence + is published to that contact, along with any other information that + shares an access-control mechanism with presence (depending on + protocol, server configuration and/or user configuration, this may + include avatars, "rich presence" such as location, etc.).

+ + +

This is subscription="to" or subscription="both" in XMPP, + the "reverse list" on MSN, or the state of "being added to + the contact's buddy list" in ICQ, for example.

+ + +

If this attribute is No or Ask, 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 + attributes can remain set to Ask, or are reset to No, when the + connection disconnects.

+ + +

Some protocols store the fact that a contact wishes to see our + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have asked + during the current session will ever have Ask status.

+ + + + + + +

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 + Telepathy, this is the message they supplied as the Message + argument to RequestSubscription.

+ + +

Otherwise, this SHOULD be omitted.

+ + + + + +

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

+ + +

XMPP, MSN, ICQ, etc. all behave like this.

+ + +

If false, presence subscriptions on this connection are not + stored.

+ + +

In SIMPLE (SIP), clients are expected to keep a record + of subscriptions, as described below. In link-local XMPP, + subscriptions are implicit (everyone on the local network receives + presence from everyone else) so nothing is ever stored.

+ + +

If CanChangeSubscriptions + 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 + of contacts that were not changed locally.

+ + +

In SIMPLE (SIP), SubscriptionsPersist is false, but + CanChangeSubscriptions 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 + lists.

+ +

In protocols like XMPP and MSN, it may be useful for clients to + queue up subscription requests or removals made while offline and + process them next time the connection is online. However, clients + should only replay the changes, rather than resetting the contact + list to match a stored copy, to avoid overwriting changes that + were made on the server.

+ + +

Clients that replay requests like this SHOULD do so by calling + AuthorizePublication to pre-approve publication of presence to the + appropriate contacts, followed by RequestSubscription to request the + appropriate contacts' presences.

+ +

This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.

+ + + + + + Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection. + + + + +

This connection cannot store this type of metadata at all, and + attempting to do so will fail with NotImplemented.

+ + +

Link-local XMPP can't store aliases or group memberships at + all, and subscription and presence states are implicit (all + contacts on the local network have subscribe = publish = Yes + and no other contacts exist).

+ +

As of April 2010, the XMPP server for Facebook Chat provides a + read-only view of the user's Facebook contacts, so it could also + usefully have this storage type.

+ + + + + + +

This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Ask or Yes.

+ + +

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.

+ + +

This supports the recommended calling pattern for adding a + new contact, in which alias and groups are set (without + necessarily waiting for a reply) before requesting the + contact's presence. Until the subscription request is + processed by the server, the alias and groups will be cached + in memory; when the subscription request has been processed, + the connection manager will store the metadata on the server.

+ + + + + + +

This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Yes.

+ + +

No service with this behaviour is currently known, but it's a + stricter form of Subscribed_Or_Pending.

+ + +

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

+ + +

The same rationale applies as for Subscribed_Or_Pending, + except that metadata must be stored until the subscription + request is not only processed by the server, but also allowed + by the remote user.

+ + + + + + +

The user can set this metadata for any valid contact identifier, + whether or not they have any presence subscription relationship + to it, and it will be stored on their contact list.

+ + +

Contact aliases and groups on XMPP have this behaviour; it + is possible to put a contact in a group, or assign an alias + to them, without requesting that presence be shared.

+ + + + + + + + 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. + + + + + + The new value of the contact's "publish-request" attribute, + or the empty string if that attribute would be omitted. + + + + + + + A map from contacts to their subscribe, publish and publish-request + attributes. + + + + + The contact's handle. + + + + + + The contact's subscribe, publish and publish-request attributes. + + + + + + +

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 + GetContactListAttributes, + or when contact are removed from that list.

+ + +

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

+ + + + + + 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. + + + + + + The contacts that have been removed from the list that would be + returned by + 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 + RequestSubscription, + AuthorizePublication and + RemoveContacts methods.

+ +

If false, all of those methods will always fail; they SHOULD raise + the error org.freedesktop.Telepathy.Error.NotImplemented.

+ + +

In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is + implicitly published to everyone in the local subnet, so the user + cannot control their presence publication.

+ + +

This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.

+ + + + + +

Request that the given contacts allow the local user to + subscribe to their presence, i.e. that their subscribe attribute + becomes Yes.

+ +

Before calling this method on a connection where GetAliasFlags returns the User_Set flag, + user interfaces SHOULD obtain, from the user, an alias to + identify the contact in future, and store it using SetAliases. + + The user MAY be + prompted using the contact's current self-assigned nickname, or + something derived from the contact's (presumably self-assigned) + identifier, as a default, but these names chosen by the contact + SHOULD NOT be used without user approval.

+ + +

This is a generalization of + XEP-0165 "Best Practices to Discourage JID Mimicking") + to protocols other than XMPP. A reasonable user interface for + this, as used in many XMPP clients, is to have a text entry + for the alias adjacent to the text entry for the identifier + to add.

+ + +

For contacts with subscribe=Yes, this method has no effect. + It MUST return successfully if all contacts are in this state.

+ +

For contacts with subscribe=Ask, this method SHOULD send a new + 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 + situations).

+ +

Any state changes that immediately result from this request MUST + be signalled via ContactsChanged + before this method returns.

+ + +

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

+ + +

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.

+ + + + +

One or more contacts to whom requests are to be sent.

+ + + + + +

An optional plain-text message from the user, to send to those + contacts with the subscription request. The + RequestUsesMessage property + indicates whether this message will be used or ignored.

+ +

Clients SHOULD NOT send a non-empty message without first giving + the user an opportunity to edit it.

+ + +

These messages are typically presented to the remote contact + as if the user had typed them, so as a minimum, the user should be + allowed to see what the UI will be saying on their behalf.

+ + +

Connections where this message is not useful MUST still allow it to + be non-empty.

+ + + + + + + + + + It was not possible to perform the requested action, because + CanChangeSubscriptions is false. + + + + + + + +

If true, the Message parameter to + RequestSubscription is likely to be + significant, and user interfaces SHOULD prompt the user for a + message to send with the request; a message such as "I would like + to add you to my contact list", translated into the local user's + language, might make a suitable default.

+ + +

This matches user expectations in XMPP and ICQ, for instance.

+ + +

If false, the parameter is ignored; user interfaces SHOULD avoid + prompting the user, and SHOULD pass an empty string to + RequestSubscription.

+ + +

FIXME: is there any such protocol?

+ + + + + + +

For each of the given contacts, request that the local user's + presence is sent to that contact, i.e. that their publish attribute + becomes Yes.

+ +

For contacts with publish=Yes, this method has no effect; it + MUST return successfully if all contacts given have this state.

+ +

For contacts with publish=Ask, this method accepts the + contact's request to see the local user's presence, changing + their publish attribute from Ask to Yes.

+ +

For contacts with publish=No, if the protocol allows it, this + method allows the contacts to see the local user's presence even + though they have not requested it, changing their publish attribute + from No to Yes. Otherwise, it merely records the fact that + presence publication to those contacts is allowed; if any of + those contacts ask to receive the local user's presence + later in the lifetime of the connection, the connection SHOULD + immediately allow them to do so, changing their publish + attribute directly from No to Yes.

+ + +

This makes it easy to implement the common UI policy that if + the user attempts to subscribe to a contact's presence, requests + for reciprocal subscription are automatically approved.

+ + +

Any state changes that immediately result from this request MUST + be signalled via ContactsChanged + before this method returns.

+ + +

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

+ + + + + +

One or more contacts to authorize.

+ + + + + + + + + + It was not possible to perform the requested action, because + CanChangeSubscriptions is false. + + + + + + + +

Remove the given contacts from the contact list entirely. It is + protocol-dependent whether this works, and under which + circumstances.

+ +

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 + 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 + outstanding request to subscribe to the contact's presence, and it's + not possible to cancel such requests). However, all signals that + immediately result from this method call MUST be emitted before it + returns, so that clients can interpret the result.

+ + +

User interfaces removing a contact from the contact list are + unlikely to want spurious failure notifications resulting from + limitations of a particular protocol. However, emitting the + signals first means that if a client does want to check exactly + what happened, it can wait for the method to return (while + applying change-notification signals to its local cache of the + contact list's state), then consult its local cache of the + contact list's state to see whether the contact is still there.

+ + + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeSubscriptions is false. + + + + + + + +

Attempt to set the given contacts' subscribe attribute to No, + i.e. stop receiving their presence.

+ +

For contacts with subscribe=Ask, this attempts to cancel + an earlier request to subscribe to the contact's presence; for + contacts with subscribe=Yes, this attempts to + unsubscribe from the contact's presence.

+ +

As with RemoveContacts, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.

+ + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeSubscriptions is false. + + + + + + + +

Attempt to set the given contacts' publish attribute to No, + i.e. stop sending presence to them.

+ +

For contacts with publish=Ask, this method explicitly rejects the + contact's request to subscribe to the user's presence; for + contacts with publish=Yes, this method attempts to prevent the + user's presence from being received by the contact.

+ +

As with RemoveContacts, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.

+ + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeSubscriptions is false. + + + + + + + + diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index 73051f4b1..4c1c11937 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -1,78 +1,335 @@ - - Copyright (C) 2005, 2006 Collabora Limited - Copyright (C) 2005, 2006 Nokia Corporation - Copyright (C) 2006 INdT + + + Copyright © 2005-2010 Nokia Corporation + Copyright © 2005-2010 Collabora Ltd. + Copyright © 2006 INdT

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.

+ 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 version, not API-stable) + + +

This connection interface is for protocols that are capable of + signaling to remote contacts that incoming communication channels + should be instead sent to a separate contact. This might apply to + things such as call forwarding, for example.

+ +

In some cases, a CM may register forwarding rules with an external + service; in those cases, it will never see the incoming channel, and + the forwarding will happen automatically.

+ +

In other cases, the CM will handle the forwarding itself. When an + incoming channel is detected, the status of the local user will + determine whether or not a forwarding rule is matched. For some + rules, this MAY happen immediately (ie, if the user is Busy); for + others, there MAY be a timeout (in seconds) that must expire + before the forwarding rule is matched (the timeout is specified + by the first element in the Forwarding_Rule_Entry list).

+ +

Once a forwarding rule is matched and any necessary timeouts have + expired, the CM can forward the incoming channel to the specified + handle. If for whatever reason the remote handle does not accept + the channel AND the CM supports multiple forwarding entries AND + any necessary timeouts have expired (specified by the next entry + in the list), the CM can forward the incoming channel to the next + handle in the entry list. This continues until the list is + exhausted, or the incoming channel is accepted.

+ +

Note that the rule matches are only for the first entry in the + in the forwarding rule list. Once the incoming channel has been + forwarded, the next entry in the list (assuming one exists and + the contact that the channel has been forwarded to does not respond + after any necessary timeouts) is used regardless of the status of + the forwarded channel. The initial match rule might have been + Busy, whereas the contact that the channel has been forwarded to + might be offline. Even in this case, the Busy list is still + traversed until the channel is handled (or there are no more + forwarding entries in the list).

+ +

For example, assuming the following dict for Forwarding_Rules:

+ 
+        ForwardingRules = {
+          Busy: ( initial-timeout: 30, [
+            (handle: 3, timeout: 15),
+            (handle: 5, timeout: 20)
+          ]),
+          NoReply: ( initial-timeout: 15, [
+            (handle: 5, timeout: 30),
+            (handle: 3, timeout: 20)
+          ])
+        }
+ +

We can imagine a scenario where an incoming channel is detected, + the media stream is available (ie, not Busy), + and the local user is online. While the CM is waiting for the local user to + accept the channel, it looks at NoReply's first timeout value. After 15s if + the local user hasn't accepted, the CM forwards the channel to Handle #5. The + CM then waits 30s for Handle #5 to accept the channel. If after 30s it does + not, the CM forwards the incoming channel to Handle #3, which will have + 20s to accept the channel.

+ + + + + The various forwarding conditions that are supported by this interface. + In general, the conditions should not overlap; it should be very clear + which rule would be chosen given a CM's behavior with an incoming + channel. The exception to this is Unconditional, + which will override all other rules. + + + - An integer contact handle to forward communication to + Incoming channels should always be forwarded. Note that setting this + will override any other rules. If not set, other rules will + be checked when an incoming communication channel is detected. - - - Emitted when the forwarding contact handle for this connection has been - changed. An zero handle indicates forwarding is disabled. + + + + +

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.

+ + + + + + The incoming channel should be forwarded if the local user doesn't + accept it within the specified amount of time. + + + + + + The incoming channel should be forwarded if the user is offline. + This could be a manual setting (the user has chosen to set their + presence to offline or invisible) or something specified by the + underlying network (the user is not within range of a cell tower). + + + + + + +

A forwarding rule entry. These MAY be chained together + for CMs that support chaining of forwards (in other words, + a forwarding rule may have multiple entries; if the contact + in the first entry doesn't respond, the incoming channel + might be forwarded to the contact in the second entry).

+ +

For CMs and protocols that don't support chaining of + entries, only the first entry would be used.

 - - - + + - An integer contact handle to whom incoming communication is forwarded +

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.

 - + + + + + The contact to forward an incoming channel to. If the handle + doesn't point to anything (e.g. points to a phone number that + doesn't exist), the entry SHOULD be skipped. + + + + + - Returns the current forwarding contact handle, or zero if none is set. + A chain of forwarding rules and an initial timeout after which + the rules are applied. - - - - - - - - + + + Initial timeout for the rule. + + + + The forwarding targets (an array of type + Forwarding_Rule_Entry). + + + + + + A dictionary whose keys are forwarding conditions and + whose values are Forwarding_Rule_Chain structs. + + + + + + + + A dictionary whose keys are forwarding conditions and + whose values are maximum number of Forwarding_Rule_Entry + for the condition. + + + + + + + +

+ 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 + might support different chain sizes, or provider and local + 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.

+ + + + + +

Emitted when the ForwardingRules property changes.

+ +

By the time this is emitted, the property MUST have been updated + with the new rules being active. If any protocol/network + requests must be made, they should be completed before the signal + is emitted.

+ + + + + The condition of the forwarding rule that's been changed. + + + + + + The new initial timeout for the rule. + + + + - An integer contact handle to forward incoming communications to + The new (and as of the emission of the signal, currently active) + forwards. The order is relevant; those at the lowest array index + are used first. + + + - Set a contact handle to forward incoming communications to. A zero - handle disables forwarding. + Update the forwarding rules. + + + +

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 + means that when a client sets Forwarding_Rule_Busy and then + temporarily sets Forwarding_Rule_Unconditional, the + Forwarding_Rule_Busy rule will retain settings after + Forwarding_Rule_Unconditional, has been unset.

+ +

If the CM has no choice but to adjust multiple rules after a call + to this function (ie, due to the network or protocol forcing such + behavior), the CM MUST emit multiple ForwardingRuleChanged + signals for each changed rule. The order of the signals is + implementation-dependent, with the only requirement that the + last signal is for the rule that was originally requested to have + been changed (e.g. if Unconditional automatically modifies + Busy and NoReply, three + separate ForwardingRuleChanged signals should be raised with the + last signal being for Forwarding_Rule_Unconditional).

+ +

Each forwarding condition will occur no more than once in + the rule array. Setting a rule will overwrite the old rule + with the same Forwarding_Condition in its entirety.

+ + + + + + The forwarding targets (an array of type Forwarding_Rule_Entry) to + activate for the rule. An empty array will effectively disable the + rule. + + + + + + The old forwarding targets (an array of type Forwarding_Rule_Entry). + This is the list of entries that is being replaced with the call to + SetForwardingRule. + + - - - + + + The specified Condition is not supported by this connection, + or the number of chained + SupportedForwardingConditions should + be checked prior to calling + SetForwardingRule. + + + + + A Handle that has been supplied is invalid. + + - - A connection interface for services which can signal to contacts - that they should instead contact a different user ID, effectively - forwarding all incoming communication channels to another contact on - the service. - + diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml index fdc622ea8..6c69a80c5 100644 --- a/spec/Connection_Interface_Location.xml +++ b/spec/Connection_Interface_Location.xml @@ -365,7 +365,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + + + The user's server does not support publishing their own location. + If it is possible to determine this ahead of time, the + Can_Set flag will not be set in + SupportedLocationFeatures. + + @@ -385,6 +392,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + Indicates the Location features supported by this connection. This + property MAY be undefined before Status + becomes Connected, but MUST remain constant thereafter. + + + + + + + Indicates that setting your own location with + SetLocation is supported on this + connection. + + + + + Flags describing the Location features which may be supported on any + given connection. + + + diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml index c74dd59f8..cfe67a8f8 100644 --- a/spec/Connection_Interface_Mail_Notification.xml +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -159,9 +159,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - A pair (name, address) representing an e-mail address, - such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). + +

A pair (name, address) representing an e-mail address, + such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At + least one of name and address MUST be provided. A missing element will + be represented by the empty string.

+ +

The CM should provide as much information as possible, but not all + protocols provide both the displayed name and the address. (If a + protocol doesn't provide either, it should omit the appropriate + field from the Mail entirely.)

+ The displayed name corresponding to the e-mail diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml new file mode 100644 index 000000000..b0b34b678 --- /dev/null +++ b/spec/Connection_Interface_Service_Point.xml @@ -0,0 +1,135 @@ + + + Copyright © 2005-2010 Nokia Corporation + Copyright © 2005-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.

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

An interface for connections whose channels may be able to indicate + specific they are connected to some form + of service station. For example, when + dialing 9-1-1 in the US, a GSM modem/network will recognize that as + an emergency call, and inform higher levels of the stack that the + call is being handled by an emergency service. In this example, + the call is handled by a Public Safety Answering Point (PSAP) which is labeled + as "urn:service:sos". Other networks and protocols may handle this + differently while still using this interface.

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

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

+ +

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"
+    ),
+    ServiceIDs: [ "911", "112" ]
+  )
+
+ + + + + + The list of all (known) service points. + + + + + + +

The new list of service points.

+ + + + Indicate that the list of known service points (or their IDs) have + changed, presenting the new list. + + + + + A service point. + + + The service type. + + + + + String representation of the service point. The representation is + service specific; it may be Uniform_Resource_Name + or may be in some other form. Empty, unused or unknown value is + represented by "". + + + + + + + The various types of service points the channel might connect to. + + + + + The service point is not used/available. + + + + + + The service point is a generic emergency point. + + + + + + The service point is some kind of counseling service (ie, mental health + or child-services counseling). + + + + + + Uniform Resource Name as specified by + RFC 5031. + + + + diff --git a/spec/Makefile.am b/spec/Makefile.am index 91f378c3a..a1d08d293 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -5,6 +5,7 @@ EXTRA_DIST = \ all.xml \ Call_Content.xml \ Call_Content_Interface_Media.xml \ + Call_Content_Interface_Mute.xml \ Call_Content_Codec_Offer.xml \ Call_Stream.xml \ Call_Stream_Interface_Media.xml \ @@ -14,6 +15,7 @@ EXTRA_DIST = \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ + Channel_Interface_Anonymity.xml \ Channel_Interface_Call_State.xml \ Channel_Interface_Chat_State.xml \ Channel_Interface_Conference.xml \ @@ -26,6 +28,7 @@ EXTRA_DIST = \ Channel_Interface_Mergeable_Conference.xml \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ + Channel_Interface_Service_Point.xml \ Channel_Interface_Splittable.xml \ Channel_Interface_Transfer.xml \ Channel_Interface_Tube.xml \ @@ -49,11 +52,15 @@ EXTRA_DIST = \ Client_Observer.xml \ Connection_Future.xml \ Connection_Interface_Aliasing.xml \ + Connection_Interface_Anonymity.xml \ Connection_Interface_Avatars.xml \ Connection_Interface_Balance.xml \ Connection_Interface_Capabilities.xml \ + Connection_Interface_Cellular.xml \ Connection_Interface_Contact_Capabilities.xml \ + Connection_Interface_Contact_Groups.xml \ Connection_Interface_Contact_Info.xml \ + Connection_Interface_Contact_List.xml \ Connection_Interface_Contacts.xml \ Connection_Interface_Forwarding.xml \ Connection_Interface_Location.xml \ @@ -62,6 +69,7 @@ EXTRA_DIST = \ Connection_Interface_Privacy.xml \ Connection_Interface_Renaming.xml \ Connection_Interface_Requests.xml \ + Connection_Interface_Service_Point.xml \ Connection_Interface_Simple_Presence.xml \ Connection_Manager.xml \ Connection.xml \ diff --git a/spec/all.xml b/spec/all.xml index a5ea1c4d2..591efb52b 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.5 +0.19.6 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation @@ -42,13 +42,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + + @@ -99,6 +105,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -107,6 +114,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -124,6 +132,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -185,8 +194,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -