From cf6fee0bf643c65956e2ab20ea50666833a0e3af Mon Sep 17 00:00:00 2001 From: "Andre Moreira Magalhaes (andrunko)" Date: Fri, 7 Jan 2011 01:08:02 -0200 Subject: Start developement. --- spec/Account.xml | 733 ++++++++++ spec/Account_Interface_Addressing.xml | 76 ++ spec/Account_Interface_Avatar.xml | 76 ++ spec/Account_Interface_Storage.xml | 169 +++ spec/Account_Manager.xml | 296 ++++ spec/Authentication_TLS_Certificate.xml | 305 +++++ spec/Call_Content.xml | 291 ++++ spec/Call_Content_Codec_Offer.xml | 87 ++ spec/Call_Content_Interface_Media.xml | 331 +++++ spec/Call_Content_Interface_Mute.xml | 85 ++ spec/Call_Stream.xml | 261 ++++ spec/Call_Stream_Endpoint.xml | 182 +++ spec/Call_Stream_Interface_Media.xml | 447 ++++++ spec/Channel.xml | 557 ++++++++ spec/Channel_Bundle.xml | 48 + spec/Channel_Dispatch_Operation.xml | 483 +++++++ spec/Channel_Dispatcher.xml | 595 ++++++++ ...Channel_Dispatcher_Interface_Operation_List.xml | 140 ++ spec/Channel_Future.xml | 68 + spec/Channel_Handler.xml | 78 ++ spec/Channel_Interface_Addressing.xml | 107 ++ spec/Channel_Interface_Anonymity.xml | 68 + spec/Channel_Interface_Call_State.xml | 147 ++ spec/Channel_Interface_Chat_State.xml | 144 ++ spec/Channel_Interface_Conference.xml | 628 +++++++++ spec/Channel_Interface_DTMF.xml | 342 +++++ spec/Channel_Interface_Destroyable.xml | 82 ++ spec/Channel_Interface_Group.xml | 1166 ++++++++++++++++ spec/Channel_Interface_HTML.xml | 86 ++ spec/Channel_Interface_Hold.xml | 222 +++ spec/Channel_Interface_Media_Signalling.xml | 235 ++++ spec/Channel_Interface_Mergeable_Conference.xml | 110 ++ spec/Channel_Interface_Messages.xml | 1433 ++++++++++++++++++++ spec/Channel_Interface_Password.xml | 104 ++ spec/Channel_Interface_Room.xml | 373 +++++ spec/Channel_Interface_SASL_Authentication.xml | 704 ++++++++++ spec/Channel_Interface_SMS.xml | 179 +++ spec/Channel_Interface_Securable.xml | 78 ++ spec/Channel_Interface_Service_Point.xml | 86 ++ spec/Channel_Interface_Splittable.xml | 71 + spec/Channel_Interface_Transfer.xml | 53 + spec/Channel_Interface_Tube.xml | 258 ++++ spec/Channel_Request.xml | 300 ++++ spec/Channel_Type_Call.xml | 1429 +++++++++++++++++++ spec/Channel_Type_Contact_List.xml | 104 ++ spec/Channel_Type_Contact_Search.xml | 462 +++++++ spec/Channel_Type_DBus_Tube.xml | 189 +++ spec/Channel_Type_File_Transfer.xml | 531 ++++++++ spec/Channel_Type_Room_List.xml | 166 +++ spec/Channel_Type_Server_Authentication.xml | 121 ++ spec/Channel_Type_Server_TLS_Connection.xml | 69 + spec/Channel_Type_Stream_Tube.xml | 292 ++++ spec/Channel_Type_Streamed_Media.xml | 853 ++++++++++++ spec/Channel_Type_Text.xml | 669 +++++++++ spec/Channel_Type_Tubes.xml | 615 +++++++++ spec/Client.xml | 122 ++ spec/Client_Approver.xml | 197 +++ spec/Client_Handler.xml | 337 +++++ spec/Client_Handler_Future.xml | 88 ++ spec/Client_Interface_Requests.xml | 175 +++ spec/Client_Observer.xml | 379 ++++++ spec/Connection.xml | 1293 ++++++++++++++++++ spec/Connection_Future.xml | 110 ++ spec/Connection_Interface_Addressing.xml | 258 ++++ spec/Connection_Interface_Aliasing.xml | 185 +++ spec/Connection_Interface_Anonymity.xml | 165 +++ spec/Connection_Interface_Avatars.xml | 516 +++++++ spec/Connection_Interface_Balance.xml | 111 ++ spec/Connection_Interface_Capabilities.xml | 254 ++++ spec/Connection_Interface_Cellular.xml | 131 ++ spec/Connection_Interface_Client_Types.xml | 218 +++ spec/Connection_Interface_Communication_Policy.xml | 163 +++ spec/Connection_Interface_Contact_Capabilities.xml | 306 +++++ spec/Connection_Interface_Contact_Groups.xml | 549 ++++++++ spec/Connection_Interface_Contact_Info.xml | 550 ++++++++ spec/Connection_Interface_Contact_List.xml | 1085 +++++++++++++++ spec/Connection_Interface_Contacts.xml | 191 +++ spec/Connection_Interface_Forwarding.xml | 346 +++++ spec/Connection_Interface_Keepalive.xml | 73 + spec/Connection_Interface_Location.xml | 464 +++++++ spec/Connection_Interface_Mail_Notification.xml | 624 +++++++++ spec/Connection_Interface_Power_Saving.xml | 109 ++ spec/Connection_Interface_Presence.xml | 346 +++++ spec/Connection_Interface_Privacy.xml | 94 ++ spec/Connection_Interface_Renaming.xml | 98 ++ spec/Connection_Interface_Requests.xml | 628 +++++++++ spec/Connection_Interface_Resources.xml | 212 +++ spec/Connection_Interface_Service_Point.xml | 136 ++ spec/Connection_Interface_Simple_Presence.xml | 634 +++++++++ spec/Connection_Manager.xml | 614 +++++++++ spec/Debug.xml | 165 +++ spec/Media_Session_Handler.xml | 81 ++ spec/Media_Stream_Handler.xml | 725 ++++++++++ spec/Properties_Interface.xml | 194 +++ spec/Protocol.xml | 485 +++++++ spec/Protocol_Interface_Addressing.xml | 300 ++++ spec/Protocol_Interface_Avatars.xml | 157 +++ spec/Protocol_Interface_Presence.xml | 113 ++ spec/all.xml | 303 +++++ spec/errors.xml | 564 ++++++++ spec/generic-types.xml | 215 +++ spec/template.xml | 33 + 102 files changed, 32880 insertions(+) create mode 100644 spec/Account.xml create mode 100644 spec/Account_Interface_Addressing.xml create mode 100644 spec/Account_Interface_Avatar.xml create mode 100644 spec/Account_Interface_Storage.xml create mode 100644 spec/Account_Manager.xml create mode 100644 spec/Authentication_TLS_Certificate.xml create mode 100644 spec/Call_Content.xml create mode 100644 spec/Call_Content_Codec_Offer.xml create mode 100644 spec/Call_Content_Interface_Media.xml create mode 100644 spec/Call_Content_Interface_Mute.xml create mode 100644 spec/Call_Stream.xml create mode 100644 spec/Call_Stream_Endpoint.xml create mode 100644 spec/Call_Stream_Interface_Media.xml create mode 100644 spec/Channel.xml create mode 100644 spec/Channel_Bundle.xml create mode 100644 spec/Channel_Dispatch_Operation.xml create mode 100644 spec/Channel_Dispatcher.xml create mode 100644 spec/Channel_Dispatcher_Interface_Operation_List.xml create mode 100644 spec/Channel_Future.xml create mode 100644 spec/Channel_Handler.xml create mode 100644 spec/Channel_Interface_Addressing.xml create mode 100644 spec/Channel_Interface_Anonymity.xml create mode 100644 spec/Channel_Interface_Call_State.xml create mode 100644 spec/Channel_Interface_Chat_State.xml create mode 100644 spec/Channel_Interface_Conference.xml create mode 100644 spec/Channel_Interface_DTMF.xml create mode 100644 spec/Channel_Interface_Destroyable.xml create mode 100644 spec/Channel_Interface_Group.xml create mode 100644 spec/Channel_Interface_HTML.xml create mode 100644 spec/Channel_Interface_Hold.xml create mode 100644 spec/Channel_Interface_Media_Signalling.xml create mode 100644 spec/Channel_Interface_Mergeable_Conference.xml create mode 100644 spec/Channel_Interface_Messages.xml create mode 100644 spec/Channel_Interface_Password.xml create mode 100644 spec/Channel_Interface_Room.xml create mode 100644 spec/Channel_Interface_SASL_Authentication.xml create mode 100644 spec/Channel_Interface_SMS.xml create mode 100644 spec/Channel_Interface_Securable.xml create mode 100644 spec/Channel_Interface_Service_Point.xml create mode 100644 spec/Channel_Interface_Splittable.xml create mode 100644 spec/Channel_Interface_Transfer.xml create mode 100644 spec/Channel_Interface_Tube.xml create mode 100644 spec/Channel_Request.xml create mode 100644 spec/Channel_Type_Call.xml create mode 100644 spec/Channel_Type_Contact_List.xml create mode 100644 spec/Channel_Type_Contact_Search.xml create mode 100644 spec/Channel_Type_DBus_Tube.xml create mode 100644 spec/Channel_Type_File_Transfer.xml create mode 100644 spec/Channel_Type_Room_List.xml create mode 100644 spec/Channel_Type_Server_Authentication.xml create mode 100644 spec/Channel_Type_Server_TLS_Connection.xml create mode 100644 spec/Channel_Type_Stream_Tube.xml create mode 100644 spec/Channel_Type_Streamed_Media.xml create mode 100644 spec/Channel_Type_Text.xml create mode 100644 spec/Channel_Type_Tubes.xml create mode 100644 spec/Client.xml create mode 100644 spec/Client_Approver.xml create mode 100644 spec/Client_Handler.xml create mode 100644 spec/Client_Handler_Future.xml create mode 100644 spec/Client_Interface_Requests.xml create mode 100644 spec/Client_Observer.xml create mode 100644 spec/Connection.xml create mode 100644 spec/Connection_Future.xml create mode 100644 spec/Connection_Interface_Addressing.xml create mode 100644 spec/Connection_Interface_Aliasing.xml create mode 100644 spec/Connection_Interface_Anonymity.xml create mode 100644 spec/Connection_Interface_Avatars.xml create mode 100644 spec/Connection_Interface_Balance.xml create mode 100644 spec/Connection_Interface_Capabilities.xml create mode 100644 spec/Connection_Interface_Cellular.xml create mode 100644 spec/Connection_Interface_Client_Types.xml create mode 100644 spec/Connection_Interface_Communication_Policy.xml create mode 100644 spec/Connection_Interface_Contact_Capabilities.xml create mode 100644 spec/Connection_Interface_Contact_Groups.xml create mode 100644 spec/Connection_Interface_Contact_Info.xml create mode 100644 spec/Connection_Interface_Contact_List.xml create mode 100644 spec/Connection_Interface_Contacts.xml create mode 100644 spec/Connection_Interface_Forwarding.xml create mode 100644 spec/Connection_Interface_Keepalive.xml create mode 100644 spec/Connection_Interface_Location.xml create mode 100644 spec/Connection_Interface_Mail_Notification.xml create mode 100644 spec/Connection_Interface_Power_Saving.xml create mode 100644 spec/Connection_Interface_Presence.xml create mode 100644 spec/Connection_Interface_Privacy.xml create mode 100644 spec/Connection_Interface_Renaming.xml create mode 100644 spec/Connection_Interface_Requests.xml create mode 100644 spec/Connection_Interface_Resources.xml create mode 100644 spec/Connection_Interface_Service_Point.xml create mode 100644 spec/Connection_Interface_Simple_Presence.xml create mode 100644 spec/Connection_Manager.xml create mode 100644 spec/Debug.xml create mode 100644 spec/Media_Session_Handler.xml create mode 100644 spec/Media_Stream_Handler.xml create mode 100644 spec/Properties_Interface.xml create mode 100644 spec/Protocol.xml create mode 100644 spec/Protocol_Interface_Addressing.xml create mode 100644 spec/Protocol_Interface_Avatars.xml create mode 100644 spec/Protocol_Interface_Presence.xml create mode 100644 spec/all.xml create mode 100644 spec/errors.xml create mode 100644 spec/generic-types.xml create mode 100644 spec/template.xml (limited to 'spec') diff --git a/spec/Account.xml b/spec/Account.xml new file mode 100644 index 0000000..acd8c30 --- /dev/null +++ b/spec/Account.xml @@ -0,0 +1,733 @@ + + + Copyright © 2008-2009 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. +

+ + + +

An Account object encapsulates the necessary details to make a + Telepathy connection.

+ +

Accounts are uniquely identified by object path. The object path + of an Account MUST take the form + /org/freedesktop/Telepathy/Account/cm/proto/acct, where:

+ +
    +
  • cm is the same Connection_Manager_Name + that appears in the connection manager's well-known bus name and + object path
    • +
  • proto is the Protocol name as seen in + ConnectionManager.ListProtocols, + but with "-" replaced with "_" + (i.e. the same as in the object-path of a Connection)
    • +
  • acct is an arbitrary string of ASCII letters, digits + and underscores, starting with a letter or underscore, which + uniquely identifies this account
    • +
  • Clients SHOULD parse the object path to discover the + connection manager and protocol
    • +
  • Clients MUST NOT attempt to parse acct
    • +
  • Clients MUST NOT assume that acct matches + the connection-specific part of a Connection's object-path and + bus name
    • +
  • The account manager SHOULD choose acct such that if + an account is deleted, its object path will be re-used if and only + if the new account is in some sense "the same" + (incorporating the 'account' parameter in some way is + recommended)
    • +
+ + +

This API avoids specifying the "profiles" used in Mission Control + 4.x or the "presets" that have been proposed to replace them. An + optional interface will be provided for AM implementations + that want to provide presets.

+ +

There is deliberately no functionality here for opening channels; + we intend to provide that in the channel dispatcher.

+ +

Other missing features which would be better in their own + interfaces:

+ +
    +
  • dynamic parameter-providing (aka provisioning)
    • +
  • saved server capabilities
    • +
  • account conditions
    • +
  • account grouping
    • +
+ + + + + moved the Avatar property to a separate + interface + + + + + + A list of the extra interfaces provided by this account. + + + + + Delete the account. + + + + + + + + This account has been removed. + + + This is redundant with AccountRemoved, + but it's still worth having, + to avoid having to bind to AccountManager.AccountRemoved to tell + you whether your Account is valid — ideally, an account-editing UI + should only care about a single Account. + + + + + + + The values of one or more properties on this interface (that do not + specify that this signal does not apply to them) may have changed. + This does not cover properties of other interfaces, which must + provide their own change notification if appropriate. + + + + + A map from property names in this namespace (e.g. + Nickname) to + values. Properties whose values have not changed SHOULD be + omitted, but this need not be done. + + + + + + + The user-visible name of this account. This SHOULD be chosen by the + user at account creation time. The account creation user interface + is responsible for setting a reasonable default value in the user's + locale; something like "Jabber (bob@example.com)" would be sensible. + + + This approximately corresponds to "display name" in NMC 4.x and + Decibel. + + + + + + + The name of an icon in the system's icon theme, such as "im-msn", + or the empty string to not specify an icon. If the icon is set to + an empty string, the account manager or any client MAY derive a + default icon, for instance from the protocol. + + + This approximately corresponds to mc_profile_get_icon_name + (or possibly mc_profile_get_branding_icon_name) in NMC 4.x. + It's accessed via the account rather than the profile because + we no longer have profiles as a core concept. + + + + + + + If true, this account is considered by the account manager to be + complete and usable. If false, user action is required to make it + usable, and it will never attempt to connect (for instance, this + might be caused by the absence of a required parameter). + + + For connection managers with a plugin architecture, like + telepathy-haze, we have little or no control over the parameters + offered; for platforms with package management, we have little or + no control over the CMs offered. NMC 4.x would just pretend the + account didn't exist in these circumstances, but silent data loss + is bad, and UIs with CM-specific knowledge (or a user filling in + newly-required parameters) might be able to rescue a broken account. + + + + + + +

This property gives the users the possibility to prevent an account + from being used. This flag does not change the validity of the + account.

+ +

A disabled account can never be put online.

+ + +

Use cases:

+ +
    +
  • user has two or more accounts capable of calling contact X, but + he doesn't want the UI to prompt him everytime about which one he + wants to use for the call. He can then disable all the equivalent + accounts but one.
    • + +
  • There is some temporary server error and the user doesn't want + to be be bother by error messages, or change the account + configuration: temporarily disabling the account is quicker.
    • +
+ + +

The AccountManager SHOULD allow this property to be set on invalid + accounts, but MUST NOT attempt to put invalid accounts online + even if they become Enabled.

+ + +

There doesn't seem to be any good reason not to allow this.

+ + + + + + + The nickname to set on this account for display to other contacts, + as set by the user. When the account becomes connected, the + account manager SHOULD set this as the user's alias using SetAliases + if appropriate. + + + In a later specification revision, we plan to separate the concepts + of a contact's nickname as set by themselves, and the local + name for them in our contact list (a "handle" or "pet name" as + described in XEP-0165 and its references). The terminology change + from alias to nickname here is a step in that direction. + This corresponds to NMC 4.x mc_account_get_alias. + + + + + + + +

Some protocols, like XMPP and SIP, are used by various different + user-recognised brands, such as Google Talk and Ovi by + Nokia. On accounts for such services, this property SHOULD be + set to a string describing the service, which MUST consist only of + ASCII letters, numbers and hyphen/minus signs, and start with a + letter (matching the requirements for Protocol). + For the jabber protocol, one of the following service names + should be used if possible:

+ + + +

The Icon property SHOULD be set to a + corresponding brand-specific icon name, if possible. In the future, + this property may be used as an index into additional + service-specific customizations. If this property is the empty string + (or missing), the service is determined by the protocol name (either + because this is a single-service protocol like msn, or + because this is just a generic jabber or sip + account without specific branding).

+ +

This property MAY be set, if appropriate, when calling + CreateAccount. Updating this property will fail on + externally-stored accounts whose StorageRestrictions include + Cannot_Set_Service.

+ + + + + +

A map from connection manager parameter names (as in the + ConnectionManager + interface) to their values. This property includes + only those parameters that are stored for this account, and SHOULD + only include those parameters that the user has explicitly set. +

+

This property cannot be altered using Set() - use + UpdateParameters instead.

+ + + + + +

Change the value of the Parameters + property.

+ +

If any of the changed parameters' + Conn_Mgr_Param_Flags include + DBus_Property, the change will be applied immediately to + the + corresponding D-Bus Property on the active + Connection, if there is one. Changes to + other parameters will not take effect until the next time the account + is disconnected and reconnected.

+ + +

In general, reconnecting is a destructive operation that shouldn't + happen as a side-effect. In particular, migration tools that + twiddle the settings of all accounts shouldn't cause an automatic + disconnect and reconnect.

+ + + + + parameters which are also D-Bus properties can and should be updated on + existing Connections + + + + return an array of the parameters that won't change until the account + is reconnected + + + + + A mapping from parameter names to their values. These parameters + should be stored for future use. + + + + + + A list of the names of parameters to be removed from the set of + stored values, allowing the default values to be used. + If the given parameters were not, in fact, stored, or even if they + do not exist at all, the account manager MUST accept this without + error. + + + + + +

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

+ +

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

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

The presence status that this account should have if it is brought + online.

+ + + In ITOS2007 and ITOS2008 this is a global preference, not visible + on D-Bus (the "default presence"). "Automatic presence" better + describes when it is used. + + +

Setting this property MUST NOT actually change the account's + status until the next time it is (re)connected for some reason.

+ +

The value of this property MUST be one that would be acceptable + for RequestedPresence, + with the additional restriction that the + Connection_Presence_Type MUST NOT be Offline.

+ + +

Otherwise, it would not be possible to use this presence to bring + the account online for a channel request.

+ + + + + + + If true, the account manager SHOULD attempt to put this account + online with the AutomaticPresence + whenever possible (in the base + Account interface this is deliberately left vague). If false, + it MUST NOT put the account online automatically in response to, + for instance, connectivity changes, but SHOULD still put the account + online with the AutomaticPresence if + requested by the user (for + instance, if the user tries to start a conversation using this + account). + + + This approximately corresponds to NMC 4.x "enabled" and Decibel + "autoreconnect". + + + + + + +

Either the object path of the Connection to + this account, or the special value '/' if there is no + connection.

+ +

If this object path is not '/', the Connection's well-known bus + name can be derived from this object path by removing the first '/' + and replacing subsequent '/' characters with '.'.

+ + + Object paths aren't nullable, so we can't use an empty string. + + + + + + + If the Connection property is non-empty, + the status of that connection. + If the Connection property is the empty string, this property may + either be Disconnected (indicating that the account manager is not + attempting to bring it online), or Connecting (indicating that the + account manager is attempting to connect). + The account manager is expected to set this by observing signals + from the Connection. + + + If the AM is doing some sort of backoff/delay on reconnection + attempts, the account's status is conceptually "Connecting" even + though there is no Connection. This vaguely corresponds to + GetCurrentStatus in NMC 4.x. + + + + + + + The reason for the last change to + ConnectionStatus. + The account manager is expected to set this by observing signals + from the Connection. + + + If you weren't watching the Connection at the time it failed, + you can't tell why - unless the AM can tell you. This is part + of GetCurrentStatus in NMC 4.x. + + + + + + + +

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

+ +

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

+ +

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

+ + +

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

+ + + + + + + +

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

+ +

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

+ + +

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

+ + + + + + + The actual presence. If the connection is not online, the + Connection_Presence_Type SHOULD be + Connection_Presence_Type_Offline. + If the connection is online but does not support the SimplePresence + interface, the type SHOULD be Connection_Presence_Type_Unset. + The account manager is expected to set this by observing signals + from the Connection. + + + This corresponds to GetPresenceActual in NMC 4.x. + + + + + + +

The requested presence for this account. When this is changed, the + account manager should attempt to manipulate the connection manager to + make CurrentPresence match + RequestedPresence as closely as + possible. It should not be saved to any sort of persistent + storage.

+ +

When the account manager automatically connects an account, + it must signal this by setting the RequestedPresence to the same + thing as the AutomaticPresence.

+ + + This corresponds to e.g. GetPresence and GetPresenceMessage + in NMC 4.x. + + +

The Connection_Presence_Type in this property + MUST NOT be Unset, Unknown or Error.

+ + +

Requesting those presence types doesn't make sense.

+ + + + + + +

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.

+ + + + + + + + +

Re-connect this account. If the account is currently disconnected + and the requested presence is offline, or if the account + is not Enabled or not + Valid, this does nothing.

+ +

If the account is disconnected and the requested presence is not + offline, this forces an attempt to connect with the requested + presence immediately.

+ +

If the account is connecting or connected, this is equivalent to + remembering the current value of + RequestedPresence, setting its value + to (OFFLINE, "offline", ""), waiting for the change to take effect, + then setting its value to the value that was previously + remembered.

+ + +

Clients desiring "instant apply" semantics for CM parameters MAY + call this method to achieve that.

+ + +

In particular, if the account's + Connection is in the Connecting + state, calling this method causes the attempt to connect to be + aborted and re-tried.

+ + +

This is necessary to ensure that the new parameters are + picked up.

+ + + + + + +

The normalized user ID of the local user on this account (i.e. the + string returned when the InspectHandles + method is called on the + result of GetSelfHandle + for an active connection).

+ +

It is unspecified whether this user ID is globally unique.

+ + +

As currently implemented, IRC user IDs are only unique within + the same IRCnet. On some saner protocols, the user ID includes a + DNS name which provides global uniqueness.

+ + +

If this value is not known yet (which will always be the case for + accounts that have never been online), it will be an empty + string.

+ +

It is possible that this value will change if the connection + manager's normalization algorithm changes, although this SHOULD + be avoided.

+ + +

It's not always completely clear what normalization algorithm + should be used; for instance, in Gabble, we currently use JIDs, + but it would also have been reasonable to use xmpp URIs.

+ + + + + + + If true, this account has successfully been put online at some point + in the past. + + + UIs could apply a policy that the 'account' parameter can only be + edited in accounts that have never been online, or that + ConnectAutomatically cannot be set on such accounts. The account + manager should not enforce such policies, but it can expose enough + information to UIs that the UI can decide what to do. + + + + + + + diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml new file mode 100644 index 0000000..4b2846b --- /dev/null +++ b/spec/Account_Interface_Addressing.xml @@ -0,0 +1,76 @@ + + + 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 stable API) + +

Some accounts can be used for multiple protocols; for instance, SIP + and Skype accounts can often be used to contact the PSTN, MSN and + Yahoo accounts can contact each other, and XMPP accounts can + potentially contact many protocols via a transport.

+

However, if the user does not intend to make use of this functionality, + user interfaces can improve clarity by not displaying it: for instance, + if a user prefers to call phone numbers via a particular SIP account, + when an address book displays a contact with a phone number, it is + desirable to display a "call with SIP" button for that account, but + avoid displaying similar buttons for any other configured SIP or + Skype accounts.

+

The purpose of this interface is to allow this "for use with" information + to be recorded and retrieved.

+ + + + +

A list of fields indicating the type of URI addressing scheme + the the account should be used for (eg 'tel') indicating the + account is intended for use by applications offering a telephony + UI, or 'sip' or 'xmpp' for those protocols

+

Note that these fields signify intent, not ability: It is + entirely possible that an account which can be used for a + given URI scheme is not wanted for it by the user, and + therefore not flagged as such in this field.

+ + + + + +

Associate (or disassociate) an account with a particular + URI addressing scheme, (such as 'tel' for telephony)

+ + + + +

URI scheme to associate/disassociate the account with/from

+ + + + + +

True to associate this account with a given addressing scheme

+

False if the account should not be associated with said scheme

+ + + + + + + + diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml new file mode 100644 index 0000000..6c85b8e --- /dev/null +++ b/spec/Account_Interface_Avatar.xml @@ -0,0 +1,76 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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 extends the core Account interface to provide a + user-settable avatar image.

+ + +

The avatar could have been a property on the core Account interface, + but was moved to a separate interface because it is likely to be + large. This means that clients can safely use GetAll to get + properties on the core Account interface without flooding the + session bus with large images.

+ + + + + + + +

A struct containing avatar data marked with its MIME type.

+ + + + + + + + The avatar to set on this account for display to other contacts, + represented as a structure containing the bytes of the avatar, + and the MIME type as a string; may be set to an empty byte-array and + an empty string to indicate no avatar. When the account becomes + connected, the account manager SHOULD set this avatar using SetAvatar + if appropriate. + + + This corresponds to NMC 4.x mc_account_get_avatar. + + + + + + + Emitted when the Avatar property changes. + + The avatar itself is deliberately not included in this + signal, to reduce bus traffic in the (likely common) case where no + running application cares about the user's own avatar. + + + + + + diff --git a/spec/Account_Interface_Storage.xml b/spec/Account_Interface_Storage.xml new file mode 100644 index 0000000..4e3ba5d --- /dev/null +++ b/spec/Account_Interface_Storage.xml @@ -0,0 +1,169 @@ + + + Copyright (C) 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. +

+ + + + + +

+ This interface extends the core Account interface to specify details + regarding the storage of this account. +

+ + +

+ Single-sign-on systems do not generally have directly user-editable + properties for Accounts, and require the user to visit a specific UI + to alter their account properties. User interfaces should know not to + expose these account properties as user-editable, and instead + redirect the user to the appropriate interface. +

+ + + + + + + +

+ The name of the account storage implementation, which SHOULD start + with a reversed domain name in the same way as D-Bus interface names. + When this is the empty string the account is internally stored. +

+

+ This property cannot change once an Account has been created. +

+ + + + + +

+ Unique identification of the account within the storage backend. + The contents of the variant are defined by the + StorageProvider. +

+

+ This property cannot change once an Account has been created. +

+ +

+ Different storage systems will have their own way of uniquely + identifying an account, typically an integer or a string. + Given that all users of this property should have direct knowledge + of the backend they should know what types to expect and how to + handle it. +

+ + + + + + +

+ Map containing information specific to the storage backend. The keys + and the types of their values are defined by the + StorageProvider, and are not + interpreted by the AccountManager implementation. +

+

+ As the values in this map may change at any time (due to an external + application manipulating the storage provider directly), this + property should not be cached; it should instead be retrieved each + time it is needed. +

+ + +

+ This can be used to provide additional hints to user interfaces + aware of a specific storage provider, without requiring those user + interfaces to use the + StorageIdentifier to query the + storage provider directly. +

+ + + + + + +

+ Bitfield which defines what restrictions this Storage method has. +

+

+ This property cannot change once an Account has been created. +

+ + + + + + Flags indicating restrictions imposed on an Account by its storage + method. + + + + + The account's Parameters property can't be changed by calling + UpdateParameters. + + + + + + The account can't be enabled/disabled by setting the Enabled property. + + + + + + The account's presence can't be changed by setting the RequestedPresence and AutomaticPresence properties. + + + + + + The account's Service + property cannot be changed. + + + + + + + diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml new file mode 100644 index 0000000..cd82e7f --- /dev/null +++ b/spec/Account_Manager.xml @@ -0,0 +1,296 @@ + + + Copyright © 2008-2009 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. +

+ + + +

The account manager is a central service used to store account + details.

+ +

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

+ +

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

+ + + + + + + + A list of the interfaces provided by the account manager object. + + + + + + A list of the valid (complete, usable) Accounts. Change + notification is via + AccountValidityChanged. + + + This split between valid and invalid accounts makes it easy to + ignore the invalid ones. The only things that should be manipulating + invalid accounts are account-editing UIs, which might be able to + rescue them. + + + + + + + A list of incomplete or otherwise unusable Accounts. Change + notification is via + AccountValidityChanged. + + + + + + The given account has been removed. + + + This is effectively change notification for the valid and invalid + accounts lists. On emission of this signal, the Account indicated + will no longer be present in either of the lists. + + + + + + An Account, which must not be used any more. + + + + + + + The validity of the given account has changed. New accounts are + also indicated by this signal, as an account validity change + (usually to True) on an account that did not previously exist. + + + This is effectively change notification for the valid and invalid + accounts lists. + + + + + + An Account. + + + + + + True if the account is now valid. + + + + + + + +

A list of the fully qualified names of properties that can be set + via the Properties argument to + CreateAccount when an account is + created.

+ + +

Examples of good properties to support here include + Icon, + Enabled, + Nickname, + AutomaticPresence, + ConnectAutomatically, + RequestedPresence + and + Avatar. +

+ +

Examples of properties that would make no sense here include + Valid, + Connection, + ConnectionStatus, + ConnectionStatusReason, + CurrentPresence + and + NormalizedName. +

+ + +

This property MUST NOT include include the DisplayName + and Parameters + properties, which are set using separate arguments.

+ +

This property MAY include the names of properties that, after + account creation, will be read-only: this indicates that the property + can be set at account creation but not changed later.

+ + +

For example, an account manager might support migration tools that + use this to preserve the HasBeenOnline + property, even though that property is usually read-only.

+ + + + + + + Request the creation of a new Account. The + account manager SHOULD NOT allow invalid accounts to be created. + + added the Properties argument + + + + The name of the connection manager, e.g. "salut". + + + + + The protocol, e.g. "local-xmpp". + + + + The initial value of the new account's DisplayName + property. The account manager SHOULD modify this to make it unique if + an Account already exists with the same display name, for instance by + appending a number or the 'account' parameter. Account manager + implementations SHOULD accept an empty string, but account editing + user interfaces should avoid passing an empty string for this + parameter. + + +

The account creation UI may ask the user for a name for the new + account. If the author of the UI chooses not to do this, the + account creation UI is better able to suggest a default display + name because it has protocol-specific knowledge which the account + manager does not.

+ +

The account manager always knows the complete list of accounts so + it can easily tell whether it should append something to the + display name to avoid presenting two identically-named accounts to + the user.

+ + + + + + Initial parameter values, as would be passed to + RequestConnection. + + + + +

The values of any other properties to be set immediately on the + new Account.

+ +

Only the properties mentioned in + SupportedAccountProperties are + acceptable here. In particular, the DisplayName + and Parameters + properties are never allowed here, since they are set using the other + arguments to this method.

+ +

Account manager implementations SHOULD support creating accounts + with an empty value for this argument.

+ + + + + The new Account. + + + + + +

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

+ + + + +

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

+ + + + + + + + + diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 0000000..db1d76f --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,305 @@ + + + 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 stable API) + + + This object represents a TLS certificate. + + + + +

The raw data contained in a TLS certificate.

+ +

For X.509 certificates (CertificateType + = "x509"), this MUST be in DER format, as defined by the + X.690 + ITU standard.

+ +

For PGP certificates (CertificateType + = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 + of RFC 4880.

+ + + + + +

Struct representing one reason why a TLS certificate was rejected.

+

Since there can be multiple things wrong with a TLS certificate, + arrays of this type are used to represent lists of reasons for + rejection. In that case, the most important reason SHOULD be placed + first in the list.

+ + + + +

The value of the TLS_Certificate_Reject_Reason enumeration for + this certificate rejection. + + Clients that do not understand the Error member, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + +

+ + + + + +

The DBus error name for this certificate rejection.

+

This MAY correspond to the value of the Reason member, + or MAY be a more specific D-Bus error name, perhaps implementation-specific.

+ + + + + +

Additional information about why the certificate was rejected. + This MAY also include one or more of the following well-known keys:

+

+

+
user-requested (b)
+
True if the error was due to an user-requested rejection of + the certificate; False if there was an unrecoverable error in the + verification process.
+
expected-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname that + the server certificate was expected to have.
+
certificate-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname of + the certificate that was presented. + +

For instance, if you try to connect to gmail.com but are presented + with a TLS certificate issued to evil.example.org, the error details + for Hostname_Mismatch MAY include:

+ 
+                {
+                  'expected-hostname': 'gmail.com',
+                  'certificate-hostname': 'evil.example.org',
+                }
+
+ +
+
debug-message (s)
+
Debugging information on the error, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances
+
+

+ + + + + + + The possible states for a TLSCertificate + object. + + + + + The certificate is currently waiting to be accepted or rejected. + + + + + + The certificate has been verified. + + + + + + The certificate has been rejected. + + + + + + + Possible reasons to reject a TLS certificate. + + + + + The certificate has been rejected for another reason + not listed in this enumeration. + + + + + + The certificate is not trusted. + + + + + + The certificate is expired. + + + + + + The certificate is not active yet. + + + + + + The certificate provided does not have the expected + fingerprint. + + + + + + The hostname certified does not match the provided one. + + + + + + The certificate is self-signed. + + + + + + The certificate has been revoked. + + + + + + The certificate uses an insecure cipher algorithm, or is + cryptographically weak. + + + + + + The length in bytes of the certificate, or the depth of the + certificate chain exceed the limits imposed by the crypto + library. + + + + + + + The current state of this certificate. + State change notifications happen by means of the + Accepted and + Rejected signals. + + + + + +

If the State is Rejected, + an array of TLS_Certificate_Rejection + structures containing the reason why the certificate is rejected.

+

If the State is not Rejected, + this property is not meaningful, and SHOULD be set to an empty + array.

+

The first rejection in the list MAY be assumed to be + the most important; if the array contains more than one + element, the CM MAY either use the values after the first, + or ignore them.

+ + + + + + The type of this TLS certificate (e.g. 'x509' or 'pgp'). +

This property is immutable

+ + + + + +

One or more TLS certificates forming a trust chain, each encoded as + specified by Certificate_Data.

+

The first certificate in the chain MUST be the server certificate, + followed by the issuer's certificate, followed by the issuer's issuer + and so on.

+ + + + + + The State of this certificate has changed to Accepted. + + + + + + The State of this certificate has changed to Rejected. + + + + The new value of the Rejections property. + + + + + + + Accepts this certificate, i.e. marks it as verified. + + + + + + Rejects this certificate. + + + +

The new value of the Rejections property.

+

This MUST NOT be an empty array.

+ + + + + + Raised when the method is called on an object whose State + is not Pending, or when the provided rejection list is empty. + + + + + + + + diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml new file mode 100644 index 0000000..17ed710 --- /dev/null +++ b/spec/Call_Content.xml @@ -0,0 +1,291 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + + This object represents one Content inside a Call.DRAFT. For + example, in an audio/video call there would be one audio content + and one video content. Each content has one or more Stream.DRAFT objects which + represent the actual transport to one or more remote contacts. + + + + + + A representation of the reason for a content to be removed, + which may be used by simple clients, or used as a fallback + when the DBus_Reason is not understood. This enum will be + extended with future reasons as and when appropriate, so + clients SHOULD keep up to date with its values, but also be + happy to fallback to the Unknown value when an unknown value + is encountered. + + + + + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + + + + + +

The local user requests that this content is removed + from the call.

+ + + + + +

There is an error with the content which means that it + has to be removed from the call.

+ + + + + +

Some aspect of the content is unsupported so has to be + removed from the call.

+ + + + + + previously there were no + arguments + + Remove the content from the call. + + + + + A generic hangup reason. + + + + + + A more specific reason for the content removal, if one is + available, or an empty string. + + + + + + A human-readable message for the reason of removing the + content, such as "Fatal streaming failure" or "no codec + intersection". This property can be left empty if no reason + is to be given. + + + + + + + + Raised when a Call doesn't support removing contents + (e.g. a Google Talk video call). + + + + + + + +

Emitted when the content is removed from the call. This + is the same as the Call.DRAFT.ContentRemoved + signal.

+ + + + + + +

Extra interfaces provided by this content, such as Content.Interface.Media.DRAFT or + Content.Interface.Mute.DRAFT. + This SHOULD NOT include the Content interface itself, and cannot + change once the content has been created.

+ + + + + +

The name of the content.

+ + + The content name property should be meaningful, so should be + given a name which is significant to the user. The name + could be the "audio" or "video" string localized, or perhaps + include some string identifying the source, such as a webcam + identifier. + + + + + + +

The media type of this content.

+ + + + + + The disposition of this content, which defines whether to + automatically start sending data on the streams when + Call.DRAFT is + called on the channel. + + + + + The content has no specific disposition + + + + + +

The content was initially part of the call. When + Accept + is called on the channel, all streams of this content with + LocalSendingState + set to Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending + (True) had been called.

+ + + + + + + The disposition of this content. + + + + + plural version, renamed from + StreamAdded + +

Emitted when streams are added to a call.

+ + + + The Stream.DRAFTs which were + added. + + + + + + plural version, renamed from + StreamRemoved + +

Emitted when streams are removed from a call

+ + + + The Stream.DRAFTs which were + removed. + + + + + + +

The list of Stream.DRAFT objects that exist in this + content.

+ + + In a conference call multiple parties can share one media + content (say, audio), but the streaming of that media can + either be shared or separate. For example, in a multicast + conference all contacts would share one stream, while in a + Muji conference there would be a stream for each + participant. + + +

Change notification is through the + StreamsAdded and + StreamsRemoved signals.

+ + + + + + + A packetization method that can be used for a content. + + + + + Real-time Transport Protocol, as documented by RFC 3550. + + + + + + Raw media. + + + + + + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + + + + + + + +

The packetization method in use for this content.

+ + + + + diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml new file mode 100644 index 0000000..f88143f --- /dev/null +++ b/spec/Call_Content_Codec_Offer.xml @@ -0,0 +1,87 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + + This object represents an offer of a Codec payload mapping. + + + + + + The local codec mapping to send to the remote contacts and + to use in the Content.DRAFT. + + + + Accept the updated Codec mapping and update the local mapping. + + + + + The codecs given as the argument are invalid in some way. + + + + + + + + Reject the proposed update to the codecs + FIXME add error codes and strings here + + + + + +

Extra interfaces provided by this codec offer. This SHOULD + NOT include the CodecOffer interface itself, and cannot change + once the content has been created.

+ + + + + + A list of codecs the remote contact supports. + + + + + + The contact handle that this codec offer applies to. + + + + + + + diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml new file mode 100644 index 0000000..274d8b2 --- /dev/null +++ b/spec/Call_Content_Interface_Media.xml @@ -0,0 +1,331 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + + +

Interface to use by a software implementation of media + streaming. The reason behind splitting the members of this + interface out from the main Content.DRAFT interface is + that the software is not necessarily what controls the + media. An example of this is in GSM phones, where the CM just + tells the phone to dial a number and it does the audio routing + in a device specific hardware way and the CM does not need + to concern itself with codecs.

+ +

Codec negotiation

+ +

When a new Call.DRAFT channel + appears, whether it was requested or not, a CodecOffer.DRAFT + will either be waiting in the + CodecOffer property, or will + appear at some point via the + NewCodecOffer signal.

+ +

The RemoteContactCodecs + property on the codec offer lists the codecs which are + supported by the remote contact, and so will determine the + codecs that should be proposed by the local user's streaming + implementation. An empty list means all codecs can be proposed.

+ +

For incoming calls on protocols where codecs are proposed when + starting the call (for example, Jingle), + the RemoteContactCodecs + will contain information on the codecs that have already been + proposed by the remote contact, otherwise the codec map will + be the empty list.

+ +

The streaming implementation should look at the remote codec + map and the codecs known by the local user and call + CodecOffer.DRAFT.Accept + on the intersection of these two codec lists.

+ +

This means that in practice, outgoing calls will have a codec + offer pop up with no information in the RemoteContactCodecs, + so the local user will call Accept + with the list of all codecs supported. If this codec offer is + accepted, then CodecsChanged + will fire with the details of the codecs passed into + Accept. If + the call is incoming, then the RemoteContactCodecs + will contain details of the remote contact's codecs and the + local user will call Accept + with the codecs that both sides understand. After the codec + set is accepted, CodecsChanged + will fire to signal this change.

+ +

Protocols without codec negotiation

+ +

For protocols where the codecs are not negotiable, instead of + popping up the initial content's CodecOffer.DRAFT + object with an empty RemoteContactCodecs, + the CM should set the supported codec values to known codec + values in the said object's codec map.

+ +

Changing codecs mid-call

+ +

To update the codec list used mid-call, the + UpdateCodecs method should be + called with details of the new codec list. If this is + accepted, then CodecsChanged + will be emitted with the new codec set.

+ +

If the other side decides to update his or her codec list + during a call, a new CodecOffer.DRAFT + object will appear through + NewCodecOffer which should be + acted on as documented above.

+ + + + + + A description of a codec. + + + + Numeric identifier for the codec. This will be used as the PT in the + SDP or content description. + + + + + The name of the codec. + + + + + The clockrate of the codec. + + + + + Number of channels of the codec if applicable, otherwise 0. + + + + + Extra parameters for this codec. + + + + + + + A map from contact to the list of codecs he or she supports. + + + + A contact handle. + + + + + The codecs that the contact supports. + + + + + + + A codec offer and its corresponding remote contact codec map. + + + + The object path to the CodecOffer.DRAFT + + + + + The contact handle that this codec offer applies to. + + + + + The CodecOffer.DRAFT.RemoteContactCodecs property + of the codec offer. + + + + + + +

Emitted when the codecs in use change.

+ +

As well as acting as change notification for the + ContactCodecMap, emission of this + signal implies that the CodecOffer + property has changed to ('/', {}).

+ + + + A map from contact to his or her codecs. Each pair in this + map is added to the + ContactCodecMap property, + replacing any previous pair with that key. + + + + + A list of keys which were removed from the + ContactCodecMap, probably because + those contacts left the call. + + + + + + + Update the local codec mapping. This method should only be + used during an existing call to update the codec mapping. + + + + The codecs now supported by the local user. + + + + + + Raised when a CodecOffer.DRAFT + object exists and is referred to in the + CodecOffer property which + should be used instead of calling this method, or before + the content's initial CodecOffer.DRAFT + object has appeared. + + + + + + + +

A map from contact handles (including the local user's own handle) + to the codecs supported by that contact.

+ +

Change notification is via the + CodecsChanged signal.

+ + + + + +

Emitted when a new CodecOffer.DRAFT appears. The streaming + implementation MUST respond by calling the Accept or Reject method on the codec offer object.

+ +

Emission of this signal indicates that the + CodecOffer property has changed to + (Contact, Offer, Codecs).

+ + + + The contact the codec offer belongs to. + + + + + The object path of the new codec offer. This replaces any previous + codec offer. + + + + +

The CodecOffer.DRAFT.RemoteContactCodecs property + of the codec offer.

+ + + Having the RemoteContactCodecs + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. + + + + + + + +

The object path to the current + CodecOffer.DRAFT object, its + CodecOffer.DRAFT.RemoteContact and + CodecOffer.DRAFT.RemoteContactCodecs properties. + If the object path is "/" then there isn't an outstanding + codec offer, and the mapping MUST be empty.

+ + + Having the RemoteContact and + RemoteContactCodecs + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in + practice. + + +

Change notification is via the + NewCodecOffer (which replaces the + value of this property with a new codec offer), and + CodecsChanged (which implies that + there is no longer any active codec offer) signals.

+ + + + + diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml new file mode 100644 index 0000000..f926e03 --- /dev/null +++ b/spec/Call_Content_Interface_Mute.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) + + + +

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 + SetMuted, 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. + + + + + renamed from SetMuted to Mute + renamed back from Mute to SetMuted + + + True if the client has muted the content. + + + +

Inform the CM that the call content has been muted or unmuted by + the 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/Call_Stream.xml b/spec/Call_Stream.xml new file mode 100644 index 0000000..1d7b281 --- /dev/null +++ b/spec/Call_Stream.xml @@ -0,0 +1,261 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + + One stream inside a Content.DRAFT. + + + + + Set the stream to start or stop sending media from the local + user to other contacts. + + + + +

If True, the + LocalSendingState should + change to Sending_State_Sending, if it isn't + already.

+ +

If False, the + LocalSendingState should + change to Sending_State_None, if it isn't + already.

+ + + + + + + + + + +

Request that a remote contact stops or starts sending on + this stream.

+ +

The CanRequestReceiving + property defines whether the protocol allows the local user to + request the other side start sending on this stream.

+ + + + +

Contact from which sending is requested

+ + + + + +

If true, request that the given contact starts to send media. + If false, request that the given contact stops sending media.

+ + + + + + + + The request contact is valid but is not involved in this + stream. + + + + + The protocol does not allow the local user to request the + other side starts sending on this stream. + + + + + + + renamed from SendersChanged to MembersChanged + renamed from MembersChanged to RemoteMembersChanged + + Emitted when RemoteMembers changes. + + + + + A mapping from channel-specific handles to their updated sending + state, whose keys include at least the members who were added, + and the members whose states changed. + + + + + The channel-specific handles that were removed from the keys + of the RemoteMembers + property, as a result of the contact leaving this stream + + + + + + + Emitted when LocalSendingState changes. + + + + + The new value of + LocalSendingState. + + + + + + + Enum indicating whether a contact is sending media. + + + + + The contact is not sending media and has not been asked to + do so. + + + + + + The contact has been asked to start sending media. + + + + + + The contact is sending media. + + + + + + The contact has been asked to stop sending media. + + + + + + + A map from a contact to his or her sending state. + + + + The contact handle. + + + + + The sending state of the contact. + + + + + + + +

Extra interfaces provided by this stream, such as Stream.Interface.Media.DRAFT. + This SHOULD NOT include the Stream interface itself, and cannot + change once the stream has been created.

+ + + + + renamed from Senders + +

A map from remote contacts to their sending state. The + local user's sending state is shown in + LocalSendingState.

+ +

Sending_State_Pending_Send indicates + that another contact has asked the local user to send + media.

+ +

Other contacts' handles in this map indicate whether they are + sending media to the contacts in this stream. + Sending_State_Pending_Send indicates contacts who are not sending but + have been asked to do so.

+ + + + + +

The local user's sending state. Media sent on this stream + should be assumed to be received, directly or indirectly, by + every other contact in the + RemoteMembers mapping. Change + notification is given via the + LocalSendingStateChanged + signal.

+ + + Implementations of the first Call draft had the self handle + in the RemoteMembers (then + called Members) map and this showed that it's annoying + having to keep track of the self handle so that it can be + special-cased. + + +

A value of Sending_State_Pending_Send for + this property indicates that the other side requested the + local user start sending media, which can be done by calling + SetSending. When a call is + accepted, all initial contents with streams that have a + local sending state of + Sending_State_Pending_Send are + automatically set to sending. For example, on an incoming + call it means you need to Accept + to start the actual call, on an outgoing call it might mean + you need to call Accept + before actually starting the call.

+ + + + + + +

If true, the user can request that a remote contact starts + sending on this stream.

+ + Not all protocols allow the user to ask the + other side to start sending media. + + + + + diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml new file mode 100644 index 0000000..4818168 --- /dev/null +++ b/spec/Call_Stream_Endpoint.xml @@ -0,0 +1,182 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + +

This object represents an endpoint for a stream. In a one-to-one + call, there will be one (bidirectional) stream per content and + one endpoint per stream (as there is only one remote + contact). In a multi-user call there is a stream for each remote + contact and each stream has one endpoint as it refers to the one + physical machine on the other end of the stream.

+ +

The multiple endpoint use case appears when SIP call forking + is used. Unlike jingle call forking (which is just making + multiple jingle calls to different resources appear as one + call), SIP call forking is actually done at the server so you + have one stream to the remote contact and then and endpoint for + each SIP client to be called.

+ + + + + The ICE credentials used for all candidates. If each candidate + has different credentials, then this property SHOULD be ("", + ""). Per-candidate credentials are set in the + Candidate's + Candidate_Info a{sv}. + + + + + + + The username set. + + + + + The password set. + + + + Emitted when the remote ICE credentials for the endpoint are + set. If each candidate has different credentials, then this + signal will never be fired. + + + + + + A list of candidates for this endpoint. + + + + + + Emitted when remote candidates are added to the + RemoteCandidates property. + + + + The candidates that were added. + + + + + + + Emitted when a candidate is selected for use in the stream. + + + + The candidate that has been selected. + + + + + + + The candidate that has been selected for use to stream packets + to the remote contact. Change notification is given via the + the CandidateSelected signal. + + + + + + Set the value of + CandidateSelected. + + + + The candidate that has been selected. + + + + + + + + + + The stream state of the endpoint. + + + + + + Emitted when the StreamState + property changes. + + + + The new StreamState value. + + + + + + + Change the StreamState of the + endpoint. + + + + The requested stream state. + + + + + + + + + + + The transport type for the stream endpoint. + + + + + + diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml new file mode 100644 index 0000000..9e62c87 --- /dev/null +++ b/spec/Call_Stream_Interface_Media.xml @@ -0,0 +1,447 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 1) + + + + [FIXME] + +

ICE restarts

+ +

If the RemoteCredentialsSet + signal is fired during a call once it has been called before + whilst setting up the call for initial use, and the + credentials have changed, then there has been an ICE + restart. In such a case, the CM SHOULD also empty the remote + candidate list in the Endpoint.DRAFT.

+ +

If the CM does an ICE restart, then the + PleaseRestartICE signal is + emitted and the streaming implementation should then call + SetCredentials again.

+ +

For more information on ICE restarts see + RFC 5245 + section 9.1.1.1

+ + + + +

Used to set the username fragment and password for streams that have + global credentials.

+ + + + The username to use when authenticating on the stream. + + + + + The password to use when authenticating on the stream. + + + + + + +

Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:

+ +
+
Type (u)
+
type of candidate (host, srflx, prflx, relay)
+ +
Foundation (s)
+
the foundation of this candiate
+ +
Protocol (u)
+
Underlying protocol of the candidate (udp, tcp)
+ +
Priority (u)
+
Priority of the candidate
+ +
BaseIP (u)
+
Base IP of this candidate
+ +
Username (s)
+
Username of this candidate + (only if credentials are per candidate)
+ +
Password (s)
+
Password of this candidate + (only if credentials are per candidate)
+ +
RawUDPFallback (b)
+
Indicate whether this candidate may be used to provide a UDP + fallback
+
+ + + One of the well-known keys documented here, or an + implementation-specific key. + + + The value corresponding to that key. + + + + + A Stream Candidate. + + The component number. + + + The IP address to use. + + + The port number to use. + + + Additional information about the candidate. + + + + + + Add candidates to the + LocalCandidates property and + signal them to the remote contact(s). + + + + The candidates to be added. + + + + + + + This indicates to the CM that the initial batch of candidates + has been added. + + + + + WLM_8_5 was removed + + A transport that can be used for streaming. + + + + The stream transport type is unknown or not applicable + (for streams that do not have a configurable transport). + + + + + Raw UDP, with or without STUN. All streaming clients are assumed to + support this transport, so there is no handler capability token for + it in the Call.DRAFT interface. + [This corresponds to "none" or "stun" in the old Media.StreamHandler + interface.] + + + + + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] + + + + + Google Talk peer-to-peer connectivity establishment, as implemented + by libjingle 0.3. + [This corresponds to "gtalk-p2p" in the old Media.StreamHandler + interface.] + + + + + The transport used by Windows Live Messenger 2009 or later, which + resembles ICE draft 19. + [This corresponds to "wlm-2009" in the old Media.StreamHandler + interface.] + + + + + + Shared memory transport, as implemented by the GStreamer + shmsrc and shmsink plugins. + + + + + + Multicast transport. + + + + + + + The transport for this stream. + + + + + + [FIXME]. Change notification is via the + LocalCandidatesAdded signal. + + + + + + Emitted when local candidates are added to the + LocalCandidates property. + + + + Candidates that have been added. + + + + + + A username and password pair. + + + The username. + + + + The password. + + + + + + [FIXME]. Change notification is via the + LocalCredentialsChanged signal. + + + + + renamed from LocalCredentailsSet + + Emitted when the value of + LocalCredentials changes. + + + + + + + + Emitted when the value of + RelayInfo changes. + + + + + + + Emitted when the value of + STUNServers changes. + + + + + + +

The IP addresses of possible STUN servers to use for NAT + traversal, as dotted-quad IPv4 address literals or RFC2373 + IPv6 address literals. Change notification is via the + STUNServersChanged + signal. The IP addresses MUST NOT be given as DNS hostnames.

+ + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + + + + + + +

A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:

+ +
+
ip - s
+
The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + +
+ +
type - s
+
+

Either udp for UDP (UDP MUST be assumed if this + key is omitted), tcp for TCP, or + tls.

+ +

The precise meaning of this key depends on the + Transport property: if + Transport is ICE, tls means + TLS over TCP as referenced by ICE draft 19, and if + Transport is GTalk_P2P, tls means + a fake SSL session over TCP as implemented by libjingle.

+
+ +
port - q
+
The UDP or TCP port of the relay server as an ASCII unsigned + integer
+ +
username - s
+
The username to use
+ +
password - s
+
The password to use
+ +
component - u
+
The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + +
+
+ + +

An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.

+ + +

The type of relay server that this represents depends on + the value of the Transport + property. If Transport is ICE, this is a TURN server; + if Transport is GTalk_P2P, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.

+ +

If relaying is not possible for this stream, the list is + empty.

+ +

Change notification is given via the + RelayInfoChanged signal.

+ + + + + +

Signals that the initial information about STUN and Relay servers + has been retrieved, i.e. the + HasServerInfo property is + now true.

+ + + + + +

True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the + ServerInfoRetrieved signal.

+ + + Streaming implementations that can't cope with STUN and + relay servers being added later SHOULD wait for this + property to become true before proceeding. + + + + + + + Emitted when the Endpoints property + changes. + + + + Endpoints that were added. + + + + + Endpoints that no longer exist. + + + + + + +

The list of Endpoint.DRAFT objects that exist for this + stream.

+ +

Change notification is via the + EndpointsChanged signal.

+ + + + + + Emitted when the CM does an ICE restart to notify the + streaming implementation that it should call + SetCredentials again. + + + + + diff --git a/spec/Channel.xml b/spec/Channel.xml new file mode 100644 index 0000000..11d3e50 --- /dev/null +++ b/spec/Channel.xml @@ -0,0 +1,557 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

+ + + + + + +

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

+ +

For compatibility between older connection managers and newer + clients, if this is unavailable or is an empty string, + clients MUST use the result of calling + GetChannelType.

+ + + The GetAll method lets clients retrieve all properties in one + round-trip, which is desirable. + + +

When requesting a channel, the request MUST specify a channel + type, and the request MUST fail if the specified channel type + cannot be supplied.

+ + + Common sense. + + + + + + + +

Extra interfaces provided by this channel. This SHOULD NOT include + the channel type and the Channel interface itself, and cannot + change once the channel has been created.

+ +

For compatibility between older connection managers and newer + clients, if this is unavailable, or if this is an empty list and + ChannelType is an empty string, + clients MUST use the result of calling + GetInterfaces instead. If this is an + empty list but ChannelType is non-empty, clients SHOULD NOT call + GetInterfaces; this implies that connection managers that implement + the ChannelType property MUST also implement the Interfaces property + correctly.

+ + + The GetAll method lets clients retrieve all properties in one + round-trip, which is desirable. + + +

When requesting a channel with a particular value for this + property, the request must fail without side-effects unless the + connection manager expects to be able to provide a channel whose + interfaces include at least the interfaces requested.

+ + + + + + +

The handle (a representation for the identifier) of the contact, + chatroom, etc. with which this handle communicates. Its type + is given by the TargetHandleType + property.

+ +

This is fixed for the lifetime of the channel, so channels which + could potentially be used to communicate with multiple contacts, + and do not have an identity of their own (such as a Handle_Type_Room + handle), must have TargetHandleType set to Handle_Type_None and + TargetHandle set to 0.

+ +

Unlike in the telepathy-spec 0.16 API, there is no particular + uniqueness guarantee - there can be many channels with the same + (channel type, handle type, handle) tuple. This is necessary + to support conversation threads in XMPP and SIP, for example.

+ +

If this is present in a channel request, it must be nonzero, + TargetHandleType + MUST be present and not Handle_Type_None, and + TargetID MUST NOT be + present. Properties from + Addressing.DRAFT + MUST NOT be present.

+ +

The channel that satisfies the request MUST either:

+ +
    +
  • have the specified TargetHandle property; or
    • +
  • have TargetHandleType = + Handle_Type_None, TargetHandle = 0, and be configured such that + it could communicate with the specified handle in some other way + (e.g. have the requested contact handle in its Group + interface)
    • +
+ + + + + + + +

The string that would result from inspecting the + TargetHandle + property (i.e. the identifier in the IM protocol of the contact, + room, etc. with which this channel communicates), or the empty + string if the TargetHandle is 0.

+ + +

The presence of this property avoids the following race + condition:

+ +
    +
  • New channel C is signalled with target handle T
    • +
  • Client calls InspectHandles(CONTACT, + [T])
    • +
  • Channel C closes, removing the last reference to handle T
    • +
  • InspectHandles(CONTACT, + [T]) returns an error
    • +
+ + +

If this is present in a channel request, + TargetHandleType + MUST be present and not Handle_Type_None, and + TargetHandle MUST NOT be + 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 + to the given identifier, in the same way as if TargetHandle + had been part of the request instead.

+ + +

Requesting channels with a string identifier saves a round-trip + (the call to RequestHandles). It also allows the channel + dispatcher to accept a channel request for an account that is not + yet connected (and thus has no valid handles), bring the account + online, and pass on the same parameters to the new connection's + CreateChannel method.

+ + + + + + + +

The type of TargetHandle.

+ +

If this is omitted from a channel request, connection managers + SHOULD treat this as equivalent to Handle_Type_None.

+ +

If this is omitted or is Handle_Type_None, + TargetHandle and + TargetID MUST be omitted from the + request.

+ + + + + + Request that the channel be closed. This is not the case until + the Closed signal has been emitted, and + depending on the connection + manager this may simply remove you from the channel on the server, + rather than causing it to stop existing entirely. Some channels + such as contact list channels may not be closed. + + + + + + + This channel may never be closed, e.g. a contact list + + + + + This channel is not currently in a state where it can be closed, + e.g. a non-empty user-defined contact group + + + + + + + + Emitted when the channel has been closed. Method calls on the + channel are no longer valid after this signal has been emitted, + and the connection manager may then remove the object from the bus + at any point. + + + + + Use the ChannelType + property if possible. + + The interface name + + + Returns the interface name for the type of this channel. Clients + SHOULD use the ChannelType property + instead, falling back to this method only if necessary. + + + The GetAll method lets clients retrieve all properties in one + round-trip. + + + + + + Use the TargetHandleType + and TargetHandle properties if possible. + + + The same as TargetHandleType. + + + + + The same as TargetHandle. + + + + Returns the handle type and number if this channel represents a + communication with a particular contact, room or server-stored list, or + zero if it is transient and defined only by its contents. Clients + SHOULD use the TargetHandle and + TargetHandleType properties instead, + falling back to this method only if necessary. + + + The GetAll method lets clients retrieve all properties in one + round-trip. + + + + + + Use the Interfaces + property if possible. + + + An array of the D-Bus interface names + + + + Get the optional interfaces implemented by the channel. + Clients SHOULD use the Interfaces + property instead, falling back to this method only if necessary. + + + The GetAll method lets clients retrieve all properties in one + round-trip. + + + + + + (as stable API) + +

True if this channel was created in response to a local request, + such as a call to + Connection.RequestChannel + or + Connection.Interface.Requests.CreateChannel.

+ + +

The idea of this property is to distinguish between "incoming" + and "outgoing" channels, in a way that doesn't break down when + considering special cases like contact lists that are automatically + created on connection to the server, or chatrooms that an + IRC proxy/bouncer like irssi-proxy or bip was already in.

+ +

The reason we want to make that distinction is that UIs for + things that the user explicitly requested should start up + automatically, whereas for incoming messages and VoIP calls we + should first ask the user whether they want to open the messaging + UI or accept the call.

+ + +

If the channel was not explicitly requested (even if it was + created as a side-effect of a call to one of those functions, + e.g. because joining a Tube in a MUC context on XMPP implies + joining that MUC), then this property is false.

+ +

For compatibility with older connection managers, clients SHOULD + assume that this property is true if they see a channel announced + by the + Connection.NewChannel + signal with the suppress_handler parameter set to true.

+ + +

In a correct connection manager, the only way to get such a + channel is to request it.

+ + +

Clients MAY additionally assume that this property is false + if they see a channel announced by the NewChannel signal with the + suppress_handler parameter set to false.

+ + +

This is more controversial, since it's possible to get that + parameter set to false by requesting a channel. However, there's + no good reason to do so, and we've deprecated this practice.

+ +

In the particular case of the channel dispatcher, the only + side-effect of wrongly thinking a channel is unrequested + is likely to be that the user has to confirm that they want to + use it, so it seems fairly harmless to assume in the channel + dispatcher that channels with suppress_handler false are + indeed unrequested.

+ + +

It does not make sense for this property to be in channel + requests—it will always be true for channels returned by + CreateChannel, and callers of EnsureChannel cannot control whether an + existing channel was originally requested locally—so it MUST NOT + be accepted.

+ + + + + (as stable API) + +

The contact who initiated the channel; for instance, the contact + who invited the local user to a chatroom, or the contact who + initiated a call.

+ +

This does not necessarily represent the contact who + created the underlying protocol-level construct. For instance, if + Rob creates a chatroom, Will joins that chatroom, and Will invites Simon + to join it, then Simon will see Will as the InitiatorHandle of the + channel representing the chatroom.

+ + +

The room creator is generally a less useful piece of information + than the inviter, is less likely to be available at invitation + time (i.e. can't necessarily be an immutable property), and is + less likely to be available at all. The creator of a chatroom + is not currently available via Telepathy; if added in future, it + is likely to be made available as a property on the Chatroom + interface (bug 23151).

+ + +

For channels requested by the + local user, this MUST be the value of + Connection.SelfHandle + at the time the channel was created (i.e. not a channel-specific + handle).

+ + +

On some protocols, the SelfHandle may change (as signalled by + Connection.SelfHandleChanged), + but this property is immutable. Hence, locally-requested channels' + InitiatorHandle and InitiatorID may not match the current + SelfHandle; Requested can be used to + determine whether the channel was created locally.

+ + +

For channels requested by a remote user, this MUST be their handle. + If unavailable or not applicable, this MUST be 0 (for instance, + contact lists are not really initiated by anyone in particular, and + it's easy to imagine a protocol where chatroom invitations can be + anonymous).

+ +

For channels with the Group + interface, this SHOULD be the same + contact who is signalled as the "Actor" causing the self-handle + to be placed in the local-pending set.

+ +

This SHOULD NOT be a channel-specific handle, if possible.

+ +

It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.

+ + + + + (as stable API) + +

The string that would result from inspecting the + InitiatorHandle + property (i.e. the initiator's identifier in the IM protocol).

+ + +

The presence of this property avoids the following race + condition:

+ +
    +
  • New StreamedMedia channel C is signalled with initiator + handle I
    • +
  • Client calls InspectHandles(CONTACT, + [I])
    • +
  • Channel C closes, removing the last reference to handle I
    • +
  • InspectHandles(CONTACT, + [I]) returns an error
    • +
  • Client can indicate that a call was missed, but not who + called!
    • +
+ + +

It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.

+ + + + +

All communication in the Telepathy framework is carried out via channel + objects which are created and managed by connections. This interface must + be implemented by all channel objects, along with one single channel type, + such as Channel.Type.ContactList + which represents a list of people (such as a buddy list) or Channel.Type.Text which + represents a channel over which textual messages are sent and received.

+ +

Each Channel's object path MUST start with the object path of + its associated Connection, followed + by '/'. There MAY be any number of additional object-path components, + which clients MUST NOT attempt to parse.

+ + +

This ensures that Channel object paths are unique, even between + Connections and CMs, because Connection object paths are + guaranteed-unique via their link to the well-known bus name.

+ +

If all connection managers in use are known to comply with at least + spec version 0.17.10, then the Connection's object path can + even be determined from the Channel's without any additional + information, by taking the first 7 components.

+ + +

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

+ +
    +
  • ChannelType specifies the kind of + communication carried out on this channel;
    • +
  • TargetHandleType, + TargetHandle and + TargetID specify the entity with which + this channel communicates, such as the other party in a 1-1 call, or + the name of a multi-user chat room;
    • +
  • InitiatorHandle and + InitiatorID specify who created this + channel;
    • +
  • Requested indicates whether the local + user requested this channel, or whether it is an incoming call, a text + conversation started by a remote contact, a chatroom invitation, + etc.
    • +
+ +

Other optional Interfaces can be + implemented to indicate other available + functionality, such as Channel.Interface.Group + if the channel contains a number of contacts, Channel.Interface.Password + to indicate that a channel may have a password set to require entry, and + Channel.Interface.ChatState + for typing notifications. The interfaces implemented may not vary after + the channel has been created. These other interfaces (along with the + interface named by ChannelType) may + themselves specify immutable properties to be announced up-front along + with the properties on this interface.

+ +

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

+ +

Specific connection manager implementations may implement channel types and + interfaces which are not contained within this specification in order to + support further functionality. To aid interoperability between client and + connection manager implementations, the interfaces specified here should be + used wherever applicable, and new interfaces made protocol-independent + wherever possible. Because of the potential for 3rd party interfaces adding + methods or signals with conflicting names, the D-Bus interface names should + always be used to invoke methods and bind signals.

+ + + Previously we guaranteed that, for + any handle type other than Handle_Type_None, and for any channel type + and any handle, there would be no more than one channel with that + combination of channel type, handle type and handle. This guarantee + has now been removed in order to accommodate features like message + threads. + + + Previously we did not explicitly + guarantee that Channels' object paths had the Connection's object path + as a prefix. + + + + diff --git a/spec/Channel_Bundle.xml b/spec/Channel_Bundle.xml new file mode 100644 index 0000000..d211525 --- /dev/null +++ b/spec/Channel_Bundle.xml @@ -0,0 +1,48 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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. +

+ + + +

A group of related channels, which should all be dispatched to the + same handler if possible.

+ +

Bundles currently have no functionality of their own, so clients + SHOULD NOT examine this interface, but should instead treat the + bundle object-path as an opaque identifier. If more functionality is + added to bundles in future, this interface will be used for capability + discovery.

+ +

The lifetime of a bundle is defined by its component channels - + as long as one or more channels whose Bundle property is B + exist, the bundle B will also exist.

+ + + + + A list of the extra interfaces provided by this channel bundle. + + + + + + diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml new file mode 100644 index 0000000..6ec69a6 --- /dev/null +++ b/spec/Channel_Dispatch_Operation.xml @@ -0,0 +1,483 @@ + + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + +

A channel dispatch operation is an object in the ChannelDispatcher + representing a batch of unrequested channels being announced to + client + Approver + processes.

+ +

These objects can result from new incoming channels or channels + which are automatically created for some reason, but cannot result + from outgoing requests for channels.

+ +

More specifically, whenever the + Connection.Interface.Requests.NewChannels + signal contains channels whose + Requested + property is false, or whenever the + Connection.NewChannel + signal contains a channel with suppress_handler false, + one or more ChannelDispatchOperation objects are created for those + channels.

+ +

(If some channels in a NewChannels signal are in different bundles, + this is an error. The channel dispatcher SHOULD recover by treating + the NewChannels signal as if it had been several NewChannels signals + each containing one channel.)

+ +

First, the channel dispatcher SHOULD construct a list of all the + Handlers + that could handle all the channels (based on their HandlerChannelFilter + property), ordered by + priority in some implementation-dependent way. If there are handlers + which could handle all the channels, one channel dispatch operation + SHOULD be created for all the channels. If there are not, one channel + dispatch operation SHOULD be created for each channel, each with + a list of channel handlers that could handle that channel.

+ +

If no handler at all can handle a channel, the channel dispatcher + SHOULD terminate that channel instead of creating a channel dispatcher + for it. It is RECOMMENDED that the channel dispatcher closes + the channels using Channel.Interface.Destroyable.Destroy + if supported, or Channel.Close + otherwise. As a special case, the channel dispatcher SHOULD NOT close + ContactList + channels, and if Close fails, the channel dispatcher SHOULD ignore + that channel.

+ + +

ContactList channels are strange. We hope to replace them with + something better, such as an interface on the Connection, in a + future version of this specification.

+ + +

When listing channel handlers, priority SHOULD be given to + channel handlers that are already handling channels from the same + bundle.

+ +

If a handler with BypassApproval + = True could handle all of the channels in the dispatch + operation, then the channel dispatcher SHOULD call HandleChannels + on that handler, and (assuming the call succeeds) emit + Finished and stop processing those + channels without involving any approvers.

+ + +

Some channel types can be picked up "quietly" by an existing + channel handler. If a Text + channel is added to an existing bundle containing a StreamedMedia + channel, there shouldn't be + any approvers, flashing icons or notification bubbles, if the + the UI for the StreamedMedia channel can just add a text box + and display the message.

+ + +

Otherwise, the channel dispatcher SHOULD send the channel dispatch + operation to all relevant approvers (in parallel) and wait for an + approver to claim the channels or request that they are handled. + See + AddDispatchOperation + for more details on this.

+ +

Finally, if the approver requested it, the channel dispatcher SHOULD + send the channels to a handler.

+ + + + + A list of the extra interfaces provided by this channel dispatch + operation. This property cannot change. + + + + + + The Connection + with which the Channels are + associated. The well-known bus name to use can be derived from + this object path by removing the leading '/' and replacing all + subsequent '/' by '.'. This property cannot change. + + + + + + The Account + with which the Connection + and Channels are + associated. This property cannot change. + + + + + + The Channels + to be dispatched, and their properties. Change notification is via + the ChannelLost signal (channels + cannot be added to this property, only removed). + + + + + +

A channel has closed before it could be claimed or handled. If + this is emitted for the last remaining channel in a channel + dispatch operation, it MUST immediately be followed by + Finished.

+ +

This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their AddDispatchOperation + method.

+ + +

This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to ChannelLost and + Finished, + then download Channels (and + on error, perhaps assume that the operation has already + Finished).

+ + + + + + The Channel + that closed. + + + + + +

The name of a D-Bus error indicating why the channel closed. If + no better reason can be found, + org.freedesktop.Telepathy.Error.NotAvailable MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.

+ + + + + + A string associated with the D-Bus error. + + + + + + +

The well known bus names (starting with + org.freedesktop.Telepathy.Client.) of the possible + Handlers + for these channels. The channel dispatcher MUST place the most + preferred handlers first, according to some reasonable heuristic. + As a result, approvers SHOULD use the first handler by default.

+ +

The heuristic used to prioritize handlers SHOULD give a higher + priority to handlers that are already running.

+ + +

If, for instance, Empathy and Kopete have similar functionality, + and Empathy is running, we should prefer to send channels to it + rather than launching Kopete via service activation.

+ + + + + + +

Called by an approver to accept a channel bundle and request that + the given handler be used to handle it.

+ +

If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + Finished.

+ +

However, this method may fail because the dispatch has already been + completed and the object has already gone. If this occurs, it + indicates that another approver has asked for the bundle to be + handled by a particular handler. The approver MUST NOT attempt + to interact with the channels further in this case, unless it is + separately invoked as the handler.

+ +

Approvers which are also channel handlers SHOULD use + Claim instead + of HandleWith to request that they can handle a channel bundle + themselves.

+ +

(FIXME: list some possible errors)

+ +

If the channel handler raises an error from HandleChannels, + this method + MAY respond by raising that same error, even if it is not + specifically documented here.

+ + + + +

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

Called by an approver to claim channels for handling + internally. If this method is called successfully, the process + calling this method becomes the handler for the channel, but + does not have the HandleChannels + method called on it.

+ +

Clients that call Claim on channels but do not immediately + close them SHOULD implement the Handler interface and its + HandledChannels + property.

+ +

Approvers wishing to reject channels MUST call this method to + claim ownership of them, and MUST NOT call + Close + on the channels unless/until this method returns successfully.

+ + +

The channel dispatcher can't know how best to close arbitrary + channel types, so it leaves it up to the approver to do so. + For instance, for Text channels it is necessary + to acknowledge any messages that have already been displayed to + the user first - ideally, the approver would display and then + acknowledge the messages - or to call Channel.Interface.Destroyable.Destroy + if the destructive behaviour of that method is desired.

+ +

Similarly, an Approver for StreamedMedia channels can close the + channel with a reason (e.g. "busy") if desired. The channel + dispatcher, which is designed to have no specific knowledge + of particular channel types, can't do that.

+ + +

If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + Finished, in the same way as for + HandleWith.

+ +

This method may fail because the dispatch operation has already + been completed. Again, see HandleWith for more details. The approver + MUST NOT attempt to interact with the channels further in this + case.

+ +

(FIXME: list some other possible errors)

+ + + + + + At the time that Claim was called, this dispatch operation was + processing a call to HandleWith which has now succeeded, so + some Handler nominated by another approver is now responsible for + the channel. + + + + + + + + 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 + operation is no longer present and further methods must not be + called on it.

+ +

Approvers that have a user interface SHOULD stop notifying the user + about the channels in response to this signal; they MAY assume that + on errors, they would have received + ChannelLost first.

+ +

Its object path SHOULD NOT be reused for a subsequent dispatch + operation; the ChannelDispatcher MUST choose object paths + in a way that avoids immediate re-use.

+ + +

Otherwise, clients might accidentally call + HandleWith or + Claim on a new dispatch operation + instead of the one they intended to handle.

+ + +

This signal MUST NOT be emitted until all Approvers that were + invoked have returned (successfully or with an error) from + their AddDispatchOperation + method.

+ + +

This means that Approvers can connect to the ChannelLost signal + in a race-free way. Non-approver processes that discover + a channel dispatch operation in some way (such as observers) + will have to follow the usual "connect to signals then recover + state" model - first connect to + ChannelLost and + Finished, then download Channels + (and on error, perhaps assume that the operation has already + Finished).

+ + + + + + + diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml new file mode 100644 index 0000000..2dd000b --- /dev/null +++ b/spec/Channel_Dispatcher.xml @@ -0,0 +1,595 @@ + + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + +

The channel dispatcher is responsible for responding to new + channels and launching client processes to handle them. It also + provides functionality for client processes to request that new + channels are created.

+ +

If a channel dispatcher is running, it is responsible for dispatching + new channels on all + Connections + created by the + AccountManager. + Connections not created by the AccountManager are outside the scope + of the channel dispatcher.

+ + +

Connections created by standalone Telepathy clients + that do not intend to interact with the channel dispatcher + should be ignored - otherwise, the channel dispatcher would try + to launch handlers for channels that the standalone client + was already handling internally.

+ + +

The current channel dispatcher is defined to be the process that + owns the well-known bus name + org.freedesktop.Telepathy.ChannelDispatcher on + the session bus. This process MUST export an object with this + interface at the object path + /org/freedesktop/Telepathy/ChannelDispatcher.

+ +

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

+ +

There are three categories of client process defined by this + specification:

+ +
+
Observer
+

Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.

+ +
Approver
+
+

Approvers notify the user that new channels have been created, + and also select which channel handler will be used for the channel, + either by asking the user or by choosing the most appropriate + channel handler.

+
+ +
Handler
+
+

Each new channel or set of channels is passed to exactly one + handler as its final destination. A typical channel handler is a + user interface process handling channels of a particular type.

+
+
+ + + + + A list of the extra interfaces provided by this channel dispatcher. + + + + + +

Equivalent to calling + CreateChannelWithHints with an empty + Hints parameter.

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

A dictionary containing desirable properties.

+ +

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

+ + + + + +

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.

+ +

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

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

Equivalent to calling + EnsureChannelWithHints with an empty + Hints parameter.

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

A dictionary containing desirable properties.

+ +

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

+ + + + + +

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

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

+ + +

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

+ + + + + + 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, and also new enough to emit SucceededWithChannel + before the older Succeeded signal. + If False or missing, only the metadata-less + variants are supported. + + + + + + diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml new file mode 100644 index 0000000..be06f5c --- /dev/null +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -0,0 +1,140 @@ + + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + + + +

This interface allows users of the ChannelDispatcher to enumerate + all the pending dispatch operations, with change notification.

+ + +

The existence of the + DispatchOperations property allows a + newly started approver to pick up existing dispatch operations.

+ +

This is on a separate interface so clients that aren't interested + in doing this aren't woken up by its signals.

+ + + + + + + Details of a channel dispatch operation. + + + + + The object path of the + ChannelDispatchOperation. + + + + + +

Properties of the channel dispatch operation.

+ +

Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.

+ + +

The rationale is the same as for + Channel_Details.

+ + +

Each dictionary MUST contain at least the following keys:

+
    +
  • org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces
    • +
  • org.freedesktop.Telepathy.ChannelDispatchOperation.Connection
    • +
  • org.freedesktop.Telepathy.ChannelDispatchOperation.Account
    • +
  • org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers
    • +
+ + + + + + +

The list of ChannelDispatchOperation objects currently being + processed. Change notification is via the + NewDispatchOperation and + DispatchOperationFinished signals.

+ + + + + +

Emitted when a dispatch operation is added to + DispatchOperations.

+ + + + + The dispatch operation that was created. + + + + + + The same properties that would appear in the Properties member of + Dispatch_Operation_Details. + + + + + + + Emitted when a dispatch operation finishes (i.e. exactly once per + emission of ChannelDispatchOperation.Finished). + + + Strictly speaking this is redundant with + ChannelDispatchOperation.Finished, but it provides full + change-notification for the + DispatchOperations property. + + + + + + The dispatch operation that was closed. + + + + + + + diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml new file mode 100644 index 0000000..5bbca17 --- /dev/null +++ b/spec/Channel_Future.xml @@ -0,0 +1,68 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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 Channel interface + in future. It should be considered to + be conceptually part of the core Channel interface, but without + API or ABI guarantees.

+ + +

If we add new functionality to the Channel interface, libraries + that use generated code (notably telepathy-glib) will have it as + part of their ABI forever, meaning we can't make incompatible + changes. By using this interface as a staging area for future + Channel functionality, we can try out new properties, signals + and methods as application-specific extensions, then merge them + into the core Channel interface when we have enough implementation + experience to declare them to be stable.

+ +

The name is by analogy to Python's __future__ + pseudo-module.

+ + + + + (in Channel.FUTURE + pseudo-interface) + +

The + ChannelBundle.DRAFT + to which this channel belongs.

+ +

A channel's Bundle property can never change.

+ +

Older connection managers might not have this property. Clients + (particularly the channel dispatcher) SHOULD recover by considering + each channel to be in a bundle containing only that channel, + distinct from all other bundles, which has no additional + interfaces.

+ + + + + + diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml new file mode 100644 index 0000000..edf975e --- /dev/null +++ b/spec/Channel_Handler.xml @@ -0,0 +1,78 @@ + + + Copyright (C) 2007-2008 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.

+ + + + Clients should implement Client.Handler + instead. + + + +

An interface exported by Mission Control 4 client applications which + are able to handle incoming channels.

+ + + + + + Called when a channel handler should handle a new channel. + + + + + + The bus name of the connection and channel + + + + + + The object-path of the connection that owns the channel + + + + + + The channel type + + + + + + The object-path of the channel + + + + + The type of the handle that the channel communicates + with, or 0 if there is no associated handle + + + + The handle that the channel communicates with, + or 0 if there is no associated handle + + + + + + + + + diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml new file mode 100644 index 0000000..494fd7b --- /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_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml new file mode 100644 index 0000000..ef3a3b8 --- /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.

+ + + + (as stable API) + + +

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

+ + + + + 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_Call_State.xml b/spec/Channel_Interface_Call_State.xml new file mode 100644 index 0000000..b0aea59 --- /dev/null +++ b/spec/Channel_Interface_Call_State.xml @@ -0,0 +1,147 @@ + + + Copyright (C) 2008 Collabora Limited + Copyright (C) 2008 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.

+ + + + + +

An interface for streamed media channels that can indicate call + progress or call states. The presence of this interface is no guarantee + that call states will actually be signalled (for instance, SIP + implementations are not guaranteed to generate status 180 Ringing, so a + call can be accepted without the Ringing flag ever having been set; + similarly, Jingle implementations are not guaranteed to send + <ringing/>).

+ +

To notify the other participant in the call that they are on hold, + see Hold.

+ + + + + + Get the current call states for all contacts involved in this call. + + + + + The current call states. Participants where the call state flags + would be 0 (all unset) may be omitted from this mapping. + + + + + + + Emitted when the state of a member of the channel has changed. + + + + + An integer handle for the contact. + + + + + + The new state for this contact. + + + + + + + A map from contacts to call states. + + + + A contact involved in this call. + + + + State flags for the given contact. + + + + + + A set of flags representing call states. + + + + + The contact has been alerted about the call but has not responded + (e.g. 180 Ringing in SIP). + + + + + + The contact is temporarily unavailable, and the call has been placed + in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). + + + + + + The contact has placed the call on hold, and will not receive + media from the local user or any other participants until they + unhold the call again. + + + + + + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. + + + + + + Progress has been made in placing the outgoing call, but the + destination contact may not have been made aware of the call yet + (so the Ringing state is not appropriate). This corresponds to SIP's + status code 183 Session Progress, and could be used when the + outgoing call has reached a gateway, for instance. + + + + + + + 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_Interface_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml new file mode 100644 index 0000000..27515d2 --- /dev/null +++ b/spec/Channel_Interface_Chat_State.xml @@ -0,0 +1,144 @@ + + + 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 +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.

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

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

+ +

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

+ +

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

+ + +

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

+ +

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

+ + + + + + + + The new state. + + + + Set the local state and notify other members of the channel that it + has changed. + + + + + + + + + + + An integer handle for the contact. + + + + + The new state of this contact. + + + + Emitted when the state of a member of the channel has changed. + This includes local state. + + + + + + The contact has effectively ceased participating in the chat. + + + + + The contact has not been active for some time. + + + + + The contact is actively participating in the chat. + + + + + The contact has paused composing a message. + + + + + The contact is composing a message to be sent to the chat. + + + + +

An interface for channels for receiving notifications of remote contacts' + state, and for notifying remote contacts of the local state.

+ +

Clients should assume that a contact's state is Channel_Chat_State_Inactive + unless they receive a notification otherwise.

+ +

The Channel_Chat_State_Gone state is treated differently to other states:

+
    +
  • It may not be used for multi-user chats
    • +
  • It may not be explicitly sent
    • +
  • It should be automatically sent when the channel is closed
    • +
  • It must not be sent to the peer if a channel is closed without being used
    • +
  • Receiving it must not cause a new channel to be opened
    • +
+ +

The different states are defined by XEP-0085, but may be applied to any suitable protocol.

+ + + + diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml new file mode 100644 index 0000000..abda59e --- /dev/null +++ b/spec/Channel_Interface_Conference.xml @@ -0,0 +1,628 @@ + + + Copyright © 2009 Collabora Limited + 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.

+ + + (as stable API) + + + + +

An interface for multi-user conference channels that can "continue + from" one or more individual channels. This could be used to invite + other contacts to an existing 1-1 text conversation, combine two phone + calls into one conference call, and so on, with roughly the same API in + each case.

+ + +

This interface addresses freedesktop.org bug + #24906 (GSM-compatible conference calls) and bug + #24939 (upgrading calls and chats to multi-user). + See those bugs for more rationale and use cases.

+ + +

Existing channels are upgraded by requesting a new channel of the same + ChannelType, + listing the channels to be merged into the new conference in the + InitialChannels property of the request. + If InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, + ad-hoc conferences to a set of contacts may be created by requesting a + channel, specifying + InitialInviteeHandles and/or + InitialInviteeIDs to be the contacts in + question. A request may specify these alongside + InitialChannels, to simultaneously + upgrade a channel to a conference and invite others to join it.

+ +

Channels with this interface MAY also implement MergeableConference.DRAFT + to support merging more 1-1 channels into an ongoing conference. + Similarly, 1-1 channels MAY implement Splittable.DRAFT to + support being broken out of a Conference channel.

+ +

The Group interface on Conference channels MAY use + channel-specific handles for participants; clients SHOULD support + both Conferences that have channel-specific handles, and those that + do not.

+ + +

In the GSM case, the Conference's Group interface MAY have + channel-specific handles, to represent the fact that the same + phone number may be in a conference twice (for instance, it could be + the number of a corporate switchboard).

+ +

In the XMPP case, the Conference's Group interface SHOULD have + channel-specific handles, to reflect the fact that the participants + have MUC-specific identities, and the user might also be able to see + their global identities, or not.

+ +

In most other cases, including MSN and link-local XMPP, the + Conference's Group interface SHOULD NOT have channel-specific + handles, since users' identities are always visible.

+ + +

Connection managers implementing channels with this interface + MUST NOT allow the object paths of channels that could be merged + into a Conference to be re-used, unless the channel re-using the + object path is equivalent to the channel that previously used it.

+ + +

If you upgrade some channels into a conference, and then close + the original channels, InitialChannels + (which is immutable) will contain paths to channels which no longer + exist. This implies that you should not re-use channel object paths, + unless future incarnations of the path are equivalent.

+ +

For instance, on protocols where you can only have + zero or one 1-1 text channels with Emily at one time, it would + be OK to re-use the same object path for every 1-1 text channel + with Emily; but on protocols where this is not true, it would + be misleading.

+ + +

Examples of usage

+ +

A pair of 1-1 GSM calls C1 and C2 can be merged + into a single conference call by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Call, + ...InitialChannels: [C1, C2] + }) +
+ +

which returns a new channel Cn implementing the conference + interface. (As a quirk of GSM, both 1-1 will cease to function normally + until they are Split + from the conference, or the conference ends.)

+ +

An XMPP 1-1 conversation C3 (with + chris@example.com, say) can be continued in a newly created + multi-user chatroom by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3] + }) +
+ +

Or, to invite emily@example.net to join the newly-created MUC + at the same time:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3], + ...InitialInviteeIDs: ['emily@example.net'] + }) +
+ +

To continue C3 in a particular multi-user + chatroom (rather than the implementation inventing a unique name for + the room), call:

+ +
+ EnsureChannel({ + ...ChannelType: ...Text, + ...TargetHandleType: ...Room, + ...TargetID: 'telepathy@conf.example.com', + ...InitialChannels: [C3] + }) +
+ +

Note the use of EnsureChannel — if a channel for + telepathy@conf.example.com is already open, this SHOULD be + equivalent to inviting chris@example.com to the existing + channel.

+ +

In the above cases, the text channel C3 SHOULD remain open + and fully functional (until explicitly closed by a client); new + incoming 1-1 messages from chris@example.com SHOULD appear in + C3, and messages sent using C3 MUST be relayed + only to chris@example.com.

+ + +

If there is an open 1-1 text channel with a contact, in every + other situation new messages will appear in that channel. Given + that the old channel remains open — which is the least surprising + behaviour, and eases us towards a beautiful world where channels + never close themselves — it stands to reason that it should be + where new messages from Chris should appear. On MSN, creating a + conference from C3 should migrate the underlying + switchboard from C3 to the new channel; this is an + implementation detail, and should not affect the representation on + D-Bus. With a suitable change of terminology, Skype has the same + behaviour.

+ +

If the current handler of that channel doesn't want this to happen + (maybe it transformed the existing tab into the group chat window, + and so there'd be no UI element still around to show new messages), + then it should just Close the + old 1-1 channel; it'll respawn if necessary.

+ + +

Either of the XMPP cases could work for Call channels, to + upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases + could in principle work for link-local XMPP (XEP-0174).

+ +

XMPP and MSN do not natively have a concept of merging two or more + channels C1, C2... into one channel, Cn. However, the GSM-style + merging API can be supported on XMPP and MSN, as an API short-cut + for upgrading C1 into a conference Cn (which invites the + TargetHandle of C1 into Cn), then immediately inviting the + TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

+ +

Sample RequestableChannelClasses

+ +

A GSM connection might advertise the following channel class for + conference calls:

+ +
+ +( Fixed = {
+    ...ChannelType: + ...StreamedMedia
+  },
+  Allowed = [ InitialChannels, + InitialAudio + ]
+) + +
+ +

This indicates support for starting audio-only conference calls by + merging two or more existing channels (since + InitialInviteeHandles and + InitialInviteeIDs are not allowed).

+ +

An XMPP connection might advertise the following classes for ad-hoc + multi-user text chats:

+ +
+ +( Fixed = {
+    ...ChannelType: + ...Text
+  },
+  Allowed = [ InitialChannels, + InitialInviteeHandles, + InitialInviteeIDs, + InvitationMessage + ]
+),
+( Fixed = {
+    ...ChannelType: + ...Text,
+    ...TargetHandleType: + Room
+  },
+  Allowed = [ TargetHandle, + TargetID,
+              InitialChannels, + InitialInviteeHandles, + InitialInviteeIDs, + InvitationMessage + ]
+) + +
+ +

The first class indicates support for starting ad-hoc (nameless) chat + rooms, upgraded from existing 1-1 channels and/or inviting new + contacts, along with a message to be sent along with the invitations. + The second indicates support for upgrading to a particular named chat + room.

+ + + + +

The individual Channels that + are continued by this conference, which have the same ChannelType as this one, but with TargetHandleType = CONTACT.

+ +

This property MUST NOT be requestable; instead, the + InitialChannels property may be + specified when requesting a channel.

+ + +

This is consistent with requesting + InitialInviteeHandles and + InitialInviteeIDs, rather than + requesting Group.Members + and some hypothetical ID version of that property.

+ + +

Change notification is via the + ChannelMerged and + ChannelRemoved signals.

+ + + + + +

Emitted when a new channel is added to the value of + Channels.

+ + + + The channel that was added to + Channels. + + + + A new channel-specific handle for the TargetHandle of + Channel, as will appear in + OriginalChannels, or 0 if a + global handle is used for + Channel's TargetHandle on the Group interface + of this channel. + + + + Channel's immutable properties. + + + + + +

Emitted when a channel is removed from the value of + Channels, either because it closed + or because it was split using the Splittable.DRAFT.Split method.

+ +

If a channel is removed because it was closed, Closed should be emitted + before this signal.

+ + + + The channel that was removed from + Channels. + + + + + Additional information about the removal, which may include + the same well-known keys as the Details argument of + MembersChangedDetailed, with the same semantics. + + + + + + +

The initial value of Channels.

+ +

This property SHOULD be requestable. Omitting it from a request is + equivalent to providing it with an empty list as value. Requests + where its value has at least two channel paths SHOULD be expected to + succeed on any implementation of this interface. If + InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, then requests with zero + or one channel paths SHOULD also succeed; otherwise, clients SHOULD + NOT make requests with zero or one paths for this property.

+ + +

In GSM, a pair of calls can be merged into a conference, but you + can't start a conference call from zero or one existing calls. In + XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 + channel into a chatroom; however, on these protocols, it is also + possible to fake GSM-style merging by upgrading the first channel, + then inviting the targets of all the other channels into it.

+ + +

If possible, the Channels' states SHOULD + NOT be altered by merging them into a conference. However, depending on + the protocol, the Channels MAY be placed in a "frozen" state by placing + them in this property's value or by calling + MergeableConference.DRAFT.Merge on them.

+ + +

In Jingle, nothing special will happen to merged calls. UIs MAY + automatically place calls on hold before merging them, if that is + the desired behaviour; this SHOULD always work. Not doing + an implicit hold/unhold seems to preserve least-astonishment.

+ +

In GSM, the calls that are merged go into a state similar to + Hold, but they cannot be unheld, only split from the conference + call using Channel.Interface.Splittable.DRAFT.Split.

+ + +

Depending on the protocol, it might be signalled to remote users + that this channel is a continuation of all the requested channels, + or that it is only a continuation of the first channel in the + list.

+ + +

In MSN, the conference steals the underlying switchboard (protocol + construct) from one of its component channels, so the conference + appears to remote users to be a continuation of that channel and no + other. The connection manager has to make some arbitrary choice, so + we arbitrarily mandate that it SHOULD choose the first channel in + the list as the one to continue.

+ + + + + + +

A list of additional contacts invited to this conference when it + was created.

+ +

If it is possible to invite new contacts when creating a conference + (as opposed to merging several channels into one new conference + channel), this property SHOULD be requestable, and appear in the allowed + properties in RequestableChannelClasses. Otherwise, this property + SHOULD NOT be requestable, and its value SHOULD always be the empty + list.

+ + +

On GSM you have to place a 1-1 call before you can merge it into a + conference; on the other hand, you can invite new contacts to XMPP + Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a + 1-1 channel with them first.

+ + +

If included in a request, the given contacts are automatically + invited into the new channel, as if they had been added with + Group.AddMembers(InitialInviteeHandles, + InvitationMessage) immediately after + the channel was created.

+ + +

This is a simple convenience API for the common case that a UI + upgrades a 1-1 chat to a multi-user chat solely in order to invite + someone else to participate.

+ + +

If the local user was not the initiator of this channel, the + Group.SelfHandle SHOULD appear in the value of this + property, together with any other contacts invited at the same time + (if that information is known).

+ +

InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be + combined in a single request.

+ + +

For example, if you have a 1-1 channel C1 with Rob, and you want + to invite Sjoerd to join the discussion, you can do so by + requesting a channel with InitialChannels=[C1] and + InitialInviteeHandles=[sjoerd], + or InitialChannels=[C1] and + InitialInviteeIDs=["sjoerd@example.com"].

+ + +

If a request includes some combination of InitialInviteeHandles, + InitialInviteeIDs and InitialChannels, then the value of + InitialInviteeHandles on the resulting channel SHOULD be the union of + the handles from InitialInviteeHandles, the handles corresponding + to the InitialInviteeIDs, and the target handles of the + InitialChannels, with any duplicate handles removed. Because this + property is immutable, its value SHOULD be computed before the + channel is announced via the NewChannels signal.

+ + +

This simplifies identification of new channels in clients - they + only have to look at one of the properties, not both. For example, + after either of the requests mentioned above, the NewChannels + signal would announce the channel with InitialChannels=[C1], + InitialInviteeHandles=[rob, sjoerd], and + InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].

+ + + + + + +

A list of additional contacts invited to this conference when it + was created.

+ +

This property SHOULD be requestable if and only if + InitialInviteeHandles is requestable. + Its semantics are the same, except that it takes a list of the + string representations of contact handles; invitations are sent to + any contact present in either or both of these properties.

+ +

When a channel is created, the values of InitialInviteeHandles and + InitialInviteeIDs MUST correspond to each other. In particular, this + means that the value of InitialInviteeIDs will include the TargetID + of each channel in InitialChannels, and the ID corresponding to each + handle in InitialInviteeHandles.

+ + + + + +

The message that was sent to the + InitialInviteeHandles when they were + invited.

+ +

This property SHOULD be requestable, and appear in the allowed + properties in RequestableChannelClasses, in protocols where + invitations can have an accompanying text message.

+ + +

This allows invitations with a message to be sent when using + InitialInviteeHandles or + InitialInviteeIDs.

+ + +

If the local user was not the initiator of this channel, the + message with which they were invited (if any) SHOULD appear in the + value of this property.

+ + + + + +

On GSM conference calls, it is possible to have the same phone + number in a conference twice; for instance, it could be the number of + a corporate switchboard. This is represented using channel-specific + handles; whether or not a channel uses channel-specific handles is + reported in Group.GroupFlags. + The Group.HandleOwners + property specifies the mapping from opaque channel-specific handles + to actual numbers; this property specifies the original 1-1 channel + corresponding to each channel-specific handle in the conference.

+ +

In protocols where this situation cannot arise, such as XMPP, + this property MAY remain empty.

+ +

For example, consider this situation:

+ +
    +
  1. Place a call (with path /call/to/simon) to the contact + +441234567890 (which is assigned the handle h, + say), and ask to be put through to Simon McVittie;
    2. +
  2. Put that call on hold;
    3. +
  3. Place another call (with path /call/to/jonny) to + +441234567890, and ask to be put + through to Jonny Lamb;
    4. +
  4. Request a new channel with + InitialChannels: + ['/call/to/simon', '/call/to/jonny'].
    5. +
+ +

The new channel will have the following properties, for some handles + s and j:

+ +
+ {
+ ...Group.GroupFlags: + Channel_Specific_Handles | (other flags),
+ ...Group.Members: + [self_handle, s, j],
+ ...Group.HandleOwners: + { s: h, j: h },
+ ...InitialChannels: + ['/call/to/simon', '/call/to/jonny'],
+ ...Channels: + ['/call/to/simon', '/call/to/jonny'],
+ ...OriginalChannels: + { s: '/call/to/simon', j: '/call/to/jonny' },
+ # ...standard properties like ChannelType: Group elided...
+ } +
+ +

Change notification is via the + ChannelMerged and + ChannelRemoved signals: if + Channel_Specific_Handle in the former is non-zero, this + property SHOULD be updated to map that handle to the merged channel's + path.

+ + + + + + + A channel-specific handle for a participant in this conference. + + + + + The object path of Channels + representing the original 1-1 channel with + Channel_Specific_Handle. + + + + + A mapping from members of a conference to the original 1-1 channel with + that contact, if any. See + OriginalChannels for details. + + + + diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml new file mode 100644 index 0000000..d74ea6f --- /dev/null +++ b/spec/Channel_Interface_DTMF.xml @@ -0,0 +1,342 @@ + + + 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 +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.

+ + + + + + + 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 + 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. + + + + 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 + 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 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. Deprecated, since stream IDs + are ignored. + + + + + There are no eligible audio streams. + + + + + DTMF tones are already being played. + + + + + + + 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 + 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. + + + + + + + + The characters [pPxXwW,] must + also be supported. + + +

A string representation of one or more DTMF + events. Implementations of this method MUST support all of the + following characters in this string:

+ +
    +
  • the digits 0-9, letters A-D and a-d, and symbols '*' and '#' + correspond to the members of DTMF_Event
    • + +
  • any of 'p', 'P', 'x', 'X' or ',' (comma) results in an + implementation-defined pause, typically for 3 seconds
    • + +
  • 'w' or 'W' waits for the user to continue, by stopping + interpretation of the string, and if there is more to be played, + emitting the TonesDeferred signal + with the rest of the string as its argument: see that signal + for details
    • +
+ + + +

Send multiple DTMF events to all eligible streams in the channel. + Each tone will be played for an implementation-defined number of + milliseconds (typically 250ms), followed by a gap before the next tone + is played (typically 100ms). The + duration and gap are 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.

+ +

The tone and gap lengths may need to vary for interoperability, + according to the protocol and other implementations' ability to + recognise tones. At the time of writing, GStreamer uses a + minimum of 250ms tones and 100ms gaps when playing in-band DTMF + in the normal audio stream, or 70ms tones and 50ms gaps when + encoding DTMF as audio/telephone-event.

+ + +

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

+ + + + + + The supplied Tones string was invalid. + + + + + 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).

+ + + + + + +

The tones waiting for the user to continue, if any.

+ +

When this property is set to a non-empty value, + TonesDeferred is emitted. + When any tones are played (i.e. whenever + SendingTones is emitted), + this property is reset to the empty string.

+ + + + + + + The new non-empty value of + DeferredTones. + + +

Emitted when 'w' or 'W', indicating "wait for the user to continue", + is encountered while playing a DTMF string queued by + MultipleTones or + InitialTones. Any queued DTMF events + after the 'w', which have not yet been played, are placed in the + DeferredTones property and copied + into this signal's argument.

+ +

When the channel handler is ready to continue, it MAY pass the + value of DeferredTones to + MultipleTones, to resume sending. + Alternatively, it MAY ignore the deferred tones, or even play + different tones instead. Any deferred tones are discarded the next + time a tone is played.

+ +

This signal SHOULD NOT be emitted if there is nothing left to play, + i.e. if the 'w' was the last character in the DTMF string.

+ + + + + + + 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 + + + 1 + + + 2 + + + 3 + + + 4 + + + 5 + + + 6 + + + 7 + + + 8 + + + 9 + + + * + + + # + + + A + + + B + + + C + + + D + + + + + diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml new file mode 100644 index 0000000..ce55923 --- /dev/null +++ b/spec/Channel_Interface_Destroyable.xml @@ -0,0 +1,82 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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.

+ + + + + (as stable API) + + +

This interface exists to support channels where + Channel.Close + is insufficiently destructive. At the moment this means + Channel.Type.Text, + but the existence of this interface means that unsupported channels + can be terminated in a non-channel-type-specific way.

+ + + + +

Close the channel abruptly, possibly with loss of data. The + connection manager MUST NOT re-create the channel unless/until + more events occur.

+ + +

The main motivating situation for this method is that when a Text + channel with pending messages is closed with Close, it comes back + as an incoming channel (to avoid a race between Close and an + incoming message). If Destroy is called on a Text channel, the CM + should delete all pending messages and close the channel, and + the channel shouldn't be re-created until/unless another message + arrives.

+ + +

Most clients SHOULD call + Channel.Close + instead. However, if a client explicitly intends to destroy the + channel with possible loss of data, it SHOULD call this method + if this interface is supported (according to the + Channel.Interfaces + property), falling back to Close if not.

+ +

In particular, channel dispatchers SHOULD use this method if + available when terminating channels that cannot be handled + correctly (for instance, if no handler has been installed for + a channel type, or if the handler crashes repeatedly).

+ +

Connection managers do not need to implement this interface on + channels where Close and Destroy would be equivalent.

+ + +

Callers need to be able to fall back to Close in any case.

+ + + + + + + diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml new file mode 100644 index 0000000..92de9c5 --- /dev/null +++ b/spec/Channel_Interface_Group.xml @@ -0,0 +1,1166 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

+ + + + + + A structure representing a contact whose attempt to + join a group is to be confirmed by the local user using + AddMembers. + + + The contact to be added to the group + + + + + The contact requesting or causing the change + + + + + The reason for the change + + + + + A human-readable message from the Actor, or an empty string + if there is no message + + + + + + + + An array of contact handles to invite to the channel + + + + + A string message, which can be blank if desired + + + +

Invite all the given contacts into the channel, or accept requests for + channel membership for contacts on the pending local list.

+ +

A message may be provided along with the request, which will be sent + to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and + CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT + GroupFlags to see in which cases this + message should be provided.

+ +

Attempting to add contacts who are already members is allowed; + connection managers must silently accept this, without error.

+ + + + + + + + + + + + + + + + Use GetAll on the D-Bus + Properties D-Bus interface to get properties including Members, + RemotePendingMembers and LocalPendingMembers instead, falling back to + this method and GetLocalPendingMembersWithInfo if necessary. + + + + + array of handles of current members + + + + + array of handles of local pending members + + + + + array of handles of remote pending members + + + + Returns arrays of all current, local and remote pending channel + members. + + + + + + + + + + + The AddMembers method can be used to + add or invite members who are + not already in the local pending list (which is always valid). + + + + + The RemoveMembers method can be used + to remove channel members + (removing those on the pending local list is always valid). + + + + + The RemoveMembers method can be used + on people on the remote + pending list. + + + + + A message may be sent to the server when calling + AddMembers on + contacts who are not currently pending members. + + + + + A message may be sent to the server when calling + RemoveMembers on + contacts who are currently channel members. + + + + + A message may be sent to the server when calling + AddMembers on + contacts who are locally pending. + + + + + A message may be sent to the server when calling + RemoveMembers on + contacts who are locally pending. + + + + + A message may be sent to the server when calling + RemoveMembers on + contacts who are remote pending. + + + + +

+ The members of this group have handles which are specific to + this channel, and are not valid as general-purpose handles on + the connection. Depending on the channel, it may be possible to + check the HandleOwners property or + call GetHandleOwners to find the + owners of these handles, which should be done if you wish to (e.g.) + subscribe to the contact's presence. +

+ +

+ Connection managers must ensure that any given handle is not + simultaneously a general-purpose handle and a channel-specific + handle. +

+ + + + + Placing a contact in multiple groups of this type is not allowed + and will raise NotAvailable (on services where contacts may only + be in one user-defined group, user-defined groups will have + this flag). + + + + + In rooms with channel specific handles (ie Channel_Specific_Handles + flag is set), this flag indicates that no handle owners are + available, apart from the owner of the + SelfHandle. + + + This used to be an important optimization to avoid repeated + GetHandleOwners calls, before we introduced the + HandleOwners property and + HandleOwnersChanged signal. + + + + + + This flag indicates that all the properties introduced in + specification 0.17.6 are fully supported. + + + + + Indicates that MembersChangedDetailed + will be emitted for changes to this group's members in addition to + MembersChanged. + Clients can then connect to the former and ignore emission of the + latter. This flag's state MUST NOT change over the lifetime of a + channel. + + + If it were allowed to change, client bindings would have to always + connect to MembersChanged just in case the flag ever went away (and + generally be unnecessarily complicated), which would mostly negate + the point of having this flag in the first place. + + + + + + + A message may be sent to the server when calling + RemoveMembers on + the SelfHandle. + + + This would be set for XMPP Multi-User Chat or IRC channels, + but not for a typical implementation of streamed media calls. + + + + + + + + An integer representing the bitwise-OR of flags on this + channel. The user interface can use this to present information about + which operations are currently valid. Change notification is via + the GroupFlagsChanged signal. + + For backwards compatibility, + clients should fall back to calling GetGroupFlags if + Channel_Group_Flag_Properties is not present. + + + + + + The value of the GroupFlags property + + + + Returns the value of the GroupFlags property. + + Use GetAll on the D-Bus + Properties D-Bus interface to get properties including GroupFlags + instead, falling back to this method if necessary. + + + + + + + + + A map from channel-specific handles to their owners. + + For backwards compatibility, + clients should fall back to calling GetHandleOwners if + Channel_Group_Flag_Properties is not present. + + + + A nonzero channel-specific handle + + + + + The global handle that owns the corresponding channel-specific + handle, or 0 if this could not be determined + + + + + + + A map from channel-specific handles to their owners, including + at least all of the channel-specific handles in this channel's members, + local-pending or remote-pending sets as keys. Any handle not in + the keys of this mapping is not channel-specific in this channel. + Handles which are channel-specific, but for which the owner is + unknown, MUST appear in this mapping with 0 as owner. Change + notification is via the + HandleOwnersChanged signal. + + + + + + + Emitted whenever the HandleOwners + property changes. + + This signal should not be relied on + unless Channel_Group_Flag_Properties is present. + + + + A map from channel-specific handles to their owners, in which the + keys include all the handles that were added to the keys of the + HandleOwners property, and all the handles in that property whose + owner has changed + + + + + The channel-specific handles that were removed from the keys of the + HandleOwners property, as a result of the contact leaving this group + in a previous MembersChanged signal + + + + + + + + A list of integer handles representing members of the channel + + + + + An array of integer handles representing the owner handles of + the given room members, in the same order, or 0 if the + owner is not available + + + + If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on + the channel, then the handles of the group members are specific + to this channel, and are not meaningful in a connection-wide + context such as contact lists. This method allows you to find + the owner of the handle if it can be discovered in this channel, + or 0 if the owner is not available. + + Clients should use the + HandleOwners property and HandleOwnersChanged signal if + Channel_Group_Flag_Properties is present. + + + + + + + This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag, + so handles in this channel are globally meaningful and calling + this method is not necessary + + + + + One of the given handles is not a member + + + + + + + + + Returns the To_Be_Added handle (only) for each structure in the + LocalPendingMembers property. + + Use the LocalPendingMembers + property, if Channel_Group_Flag_Properties is present. + + + + + + + + + + Returns the LocalPendingMembers property. + + Use the LocalPendingMembers + property, if Channel_Group_Flag_Properties is present. + + + An array of structs containing: +
    +
  • + A handle representing the contact requesting channel membership +
    • +
  • + A handle representing the contact making the request, or 0 if + unknown +
    • +
  • + The reason for the request: one of the values of + Channel_Group_Change_Reason +
    • +
  • + A string message containing the reason for the request if any (or + blank if none) +
    • +
+ + + + + + + + + + + An array of structs containing handles representing contacts + requesting channel membership and awaiting local approval with + AddMembers. + + If Channel_Group_Flag_Properties is + not present, clients should fall back to using the + deprecated GetLocalPendingMembersWithInfo method, or fall back + from that to the deprecated GetAllMembers method. + + + + + The members of this channel. + + If Channel_Group_Flag_Properties + is not set, fall back to calling GetAllMembers. + + + + + + Returns the Members property. + + Use the Members + property, if Channel_Group_Flag_Properties is present. + + + + + + + + + An array of handles representing contacts who have been + invited to the channel and are awaiting remote approval. + + If Channel_Group_Flag_Properties + is not set, fall back to calling GetAllMembers. + + + + + + Returns an array of handles representing contacts who have been + invited to the channel and are awaiting remote approval. + + Use the + RemotePendingMembers + property, if Channel_Group_Flag_Properties is present. + + + + + + + + + Emitted whenever the SelfHandle property + changes. + + This signal should not be relied on + unless Channel_Group_Flag_Properties is present. + + + + The new value of the SelfHandle property. + + + + + + + The handle for the user on this channel (which can also be a + local or remote pending member), or 0 if the user is not a member at + all (which is likely to be the case, for instance, on ContactList + channels). Note that this is different from the result of + Connection.GetSelfHandle + on some protocols, so the value of this handle should + always be used with the methods of this interface. + + For backwards compatibility, + clients should fall back to calling GetSelfHandle if + Channel_Group_Flag_Properties is not present. + + + + + + Returns the value of the SelfHandle + property. + + Clients should retrieve the + SelfHandle property using GetAll instead, + if Channel_Group_Flag_Properties is present. + + + + + + + + + + A bitwise OR of the flags which have been set + + + + + A bitwise OR of the flags which have been cleared + + + + Emitted when the flags as returned by + GetGroupFlags are changed. + The user interface should be updated as appropriate. + + + + + +

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

+ + + + +

No reason was provided for this change.

+ +

In particular, this reason SHOULD be used when representing + users joining a named chatroom in the usual way, users leaving + a chatroom by their own request, and normal termination of a + StreamedMedia call by the remote user.

+ +

If the SelfHandle is removed from + a group for this reason and the actor is not the SelfHandle, the + equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Terminated.

+ +

If the SelfHandle is removed from a group for this reason and + the actor is also the SelfHandle, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cancelled.

+ + + + +

The change is due to a user going offline. Also used when + user is already offline, but this wasn't known previously.

+ +

If a one-to-one StreamedMedia + call fails because the contact being called is offline, the + connection manager SHOULD indicate this by removing both the + SelfHandle and the other contact's + handle from the Group interface with reason Offline.

+ + + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + + +

If a handle is removed from a group for this reason, the + equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Offline.

+ + + + +

The change is due to a kick operation.

+ +

If the SelfHandle is removed + from a group for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Channel.Kicked. +

+ + + + +

The change is due to a busy indication.

+ +

If a one-to-one StreamedMedia + call fails because the contact being called is busy, the + connection manager SHOULD indicate this by removing both the + SelfHandle and the other contact's + handle from the Group interface with reason Busy.

+ + + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + + +

If the SelfHandle is removed + from a group for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Busy. +

+ + + + + The change is due to an invitation. This reason SHOULD only be used + when contacts are added to the remote-pending set (to indicate that + the contact has been invited) or to the members (to indicate that + the contact has accepted the invitation). + + + Otherwise, what would it mean? + + + + + +

The change is due to a kick+ban operation.

+ +

If the SelfHandle is removed + from a group for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Channel.Banned. +

+ + + + + The change is due to an error occurring. + + + + +

The change is because the requested contact does not exist.

+ +

For instance, if the user invites a nonexistent contact to a + chatroom or attempts to call a nonexistent contact, this could + be indicated by the CM adding that contact's handle to + remote-pending for reason None or Invited, then removing it for + reason Invalid_Contact. In the case of a 1-1 StreamedMedia + call, the CM SHOULD remove the self handle from the Group + in the same signal.

+ + + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + + +

If a contact is removed from a group for this reason, the + equivalent D-Bus error is + org.freedesktop.Telepathy.Error.DoesNotExist. +

+ + + + +

The change is because the requested contact did not respond.

+ +

If a one-to-one StreamedMedia + call fails because the contact being called did not respond, or the + local user did not respond to an incoming call, the + connection manager SHOULD indicate this by removing both the + SelfHandle and the other contact's + handle from the Group interface with reason No_Answer.

+ + + Documenting existing practice. + + +

If a contact is removed from a group for this reason, the + equivalent D-Bus error is + org.freedesktop.Telepathy.Error.NoAnswer. +

+ + + + +

The change is because a contact's unique identifier changed. + There must be exactly one handle in the removed set and exactly + one handle in one of the added sets. The Renamed + signal on the + Renaming + interface will have been emitted for the same handles, + shortly before this MembersChanged signal is emitted.

+ + + + +

The change is because there was no permission to contact the + requested handle.

+ +

If a contact is removed from a group for this reason, the + equivalent D-Bus error is + org.freedesktop.Telepathy.Error.PermissionDenied. +

+ + + + +

If members are removed with this reason code, the change is + because the group has split into unconnected parts which can only + communicate within themselves (e.g. netsplits on IRC use this + reason code). +

+

+ If members are added with this reason code, the change is because + unconnected parts of the group have rejoined. If this channel + carries messages (e.g. Text + or Tubes + channels) applications must + assume that the contacts being added are likely to have missed some + messages as a result of the separation, and that the contacts + in the group are likely to have missed some messages from the + contacts being added. +

+

Note that from the added contacts' perspective, they have been + in the group all along, and the contacts we indicate to be in + the group (including the local user) have just rejoined + the group with reason Separated. Application protocols in Tubes + should be prepared to cope with this situation. +

+ +

The SelfHandle SHOULD NOT be + removed from channels with this reason.

+ + + + + + + + A string message from the server, or blank if not + + + + + A list of members added to the channel + + + + + A list of members removed from the channel + + + + + A list of members who are pending local approval + + + + + A list of members who are pending remote approval + + + + + The contact handle of the person who made the change, or 0 + if not known + + + + + A reason for the change + + + +

Emitted when contacts join any of the three lists (members, local + pending or remote pending) or when they leave any of the three lists. + There may also be a message from the server regarding this change, + which may be displayed to the user if desired.

+ +

All channel-specific handles that are mentioned in this signal + MUST be represented in the value of the + HandleOwners property. + In practice, this will mean that + HandleOwnersChanged is + emitted before emitting a MembersChanged signal in which + channel-specific handles are added, but that it is emitted + after emitting a MembersChanged signal in which + channel-specific handles are removed.

+ +

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

+ + + + + + A map from handles to the corresponding normalized string identifier. + + + + + + A nonzero handle + + + + + The same string that would be returned by InspectHandles + for this handle. + + + + + + + + A list of members added to the channel + + + + + A list of members removed from the channel + + + + + A list of members who are pending local approval + + + + + A list of members who are pending remote approval + + + + +

Information about the change, which may include the following + well-known keys:

+ +
+
actor (u — Contact_Handle)
+
The contact handle of the person who made the change; 0 or + omitted if unknown or not applicable.
+ +
change-reason (u — Channel_Group_Change_Reason)
+
A reason for the change.
+ +
contact-ids (a{us} — Handle_Identifier_Map)
+
+

The string identifiers for handles mentioned in this signal, to + give clients the minimal information necessary to react to the + event without waiting for round-trips. Connection managers + SHOULD include the identifiers for members added to the group and + for the actor (if any); they MAY omit the identifiers for handles + which have been removed from the group.

+ + +

On IRC, an event such as a netsplit could cause the vast + majority of a channel to leave. Given that clients should + already know the identifiers of a channel's members, including + potentially hundreds of strings in the netsplit signal is + unnecessary.

+ + +

Clients MUST NOT assume that the presence or absence of a + handle in this mapping is meaningful. This mapping is merely + an optimization for round-trip reduction, and connection + managers MAY add additional handles, omit some handles, or + omit the mapping completely.

+
+ +
message (s)
+
A string message from the server regarding the change
+ +
error (s — DBus_Error_Name)
+
A (possibly implementation-specific) DBus error describing the + change, providing more specific information than the + Channel_Group_Change_Reason enum allows. This + MUST only be present if it is strictly more informative than + 'change-reason'; if present, 'change-reason' MUST be set to the + closest available reason. + + + A SIP connection manager might want to signal "402 Payment + required" as something more specific than Error or + Permission_Denied so that a SIP-aware UI could handle it + specially; including a namespaced error permits this to be done + without Channel_Group_Change_Reason being + extended to encompass every error any CM ever wants to report. + +
+ +
debug-message (s)
+
Debugging information on the change. SHOULD NOT be shown to + users in normal circumstances.
+
+ + + +

Emitted when contacts join any of the three lists (members, local + pending or remote pending) or when they leave any of the three + lists. This signal provides a superset of the information provided by + MembersChanged; + if the channel's GroupFlags + contains Members_Changed_Detailed, then clients may listen exclusively + to this signal in preference to that signal.

+ +

All channel-specific handles that are mentioned in this signal + MUST be represented in the value of the + HandleOwners property. In practice, + this will mean that + HandleOwnersChanged is emitted + before emitting a MembersChangedDetailed signal in which + channel-specific handles are added, but that it is emitted + after emitting a MembersChangedDetailed signal in which + channel-specific handles are removed.

+ +

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

+ + + + + + + + An array of contact handles to remove from the channel + + + + + A string message, which can be blank if desired + + + +

Requests the removal of contacts from a channel, reject their + request for channel membership on the pending local list, or + rescind their invitation on the pending remote list.

+ +

If the SelfHandle is in a Group, + it can be removed via this method, in order to leave the group + gracefully. This is the recommended way to leave a chatroom, close + or reject a StreamedMedia + call, and so on.

+ +

Accordingly, connection managers SHOULD support + doing this, regardless of the value of + GroupFlags. + If doing so fails with PermissionDenied, this is considered to a bug + in the connection manager, but clients MUST recover by falling back + to closing the channel with the Close + method.

+ +

Removing any contact from the local pending list is always + allowed. Removing contacts other than the + SelfHandle from the channel's members + is allowed if and only if Channel_Group_Flag_Can_Remove is in the + GroupFlags, + while removing contacts other than the + SelfHandle from the remote pending list + is allowed if and only if Channel_Group_Flag_Can_Rescind is in the + GroupFlags.

+ +

A message may be provided along with the request, which will be + sent to the server if supported. See the + Channel_Group_Flag_Message_Remove, + Channel_Group_Flag_Message_Depart, + Channel_Group_Flag_Message_Reject and + Channel_Group_Flag_Message_Rescind + GroupFlags to see in which cases this + message should be provided.

+ + + + + + + + + + + + + + An array of contact handles to remove from the channel + + + + + A string message, which can be blank if desired + + + + + A reason for the change + + + + As RemoveMembers, but a reason code may + be provided where + appropriate. The reason code may be ignored if the underlying + protocol is unable to represent the given reason. + + + + + + + + + + The provided reason code was invalid. + + + + + + +

Interface for channels which have multiple members, and where the members + of the channel can change during its lifetime. Your presence in the channel + cannot be presumed by the channel's existence (for example, a channel you + may request membership of but your request may not be granted).

+ +

This interface implements three lists: a list of current members + (Members), and two lists of local pending + and remote pending members + (LocalPendingMembers and + RemotePendingMembers, respectively). + Contacts on the remote + pending list have been invited to the channel, but the remote user has not + accepted the invitation. Contacts on the local pending list have requested + membership of the channel, but the local user of the framework must accept + their request before they may join. A single contact should never appear on + more than one of the three lists. The lists are empty when the channel is + created, and the MembersChanged signal + (and, if the channel's GroupFlags contains + Members_Changed_Detailed, the + MembersChangedDetailed signal) + should be emitted when information + is retrieved from the server, or changes occur.

+ +

If the MembersChanged or + MembersChangedDetailed signal indicates + that the SelfHandle has been removed from + the channel, and the channel subsequently emits Closed, + clients SHOULD consider the details given in the MembersChanged or + MembersChangedDetailed signal to be the reason why the channel closed.

+ +

Addition of members to the channel may be requested by using + AddMembers. If + remote acknowledgement is required, use of the AddMembers method will cause + users to appear on the remote pending list. If no acknowledgement is + required, AddMembers will add contacts to the member list directly. If a + contact is awaiting authorisation on the local pending list, AddMembers + will grant their membership request.

+ +

Removal of contacts from the channel may be requested by using + RemoveMembers. If a contact is awaiting + authorisation on the local pending + list, RemoveMembers will refuse their membership request. If a contact is + on the remote pending list but has not yet accepted the invitation, + RemoveMembers will rescind the request if possible.

+ +

It should not be presumed that the requester of a channel implementing this + interface is immediately granted membership, or indeed that they are a + member at all, unless they appear in the list. They may, for instance, + be placed into the remote pending list until a connection has been + established or the request acknowledged remotely.

+ +

If the local user joins a Group channel whose members or other state + cannot be discovered until the user joins (e.g. many chat room + implementations), the connection manager should ensure that the channel + is, as far as possible, in a consistent state before adding the local + contact to the members set; until this happens, the local contact should + be in the remote-pending set. For instance, if the connection manager + queries the server to find out the initial members list for the + channel, it should leave the local contact in the remote-pending set + until it has finished receiving the initial members list. +

+ +

If the protocol provides no reliable way to tell whether the complete + initial members list has been received yet, the connection manager + should make a best-effort attempt to wait for the full list + (in the worst case, waiting for a suitable arbitrary timeout) + rather than requiring user interfaces to do so on its behalf.

+ + + + diff --git a/spec/Channel_Interface_HTML.xml b/spec/Channel_Interface_HTML.xml new file mode 100644 index 0000000..ad86867 --- /dev/null +++ b/spec/Channel_Interface_HTML.xml @@ -0,0 +1,86 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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 version, not API-stable) + + +

This interface extends the Messages interface to support + capability discovery, so clients can decide what subset of HTML + is supported.

+ +

(However, the capability discovery mechanism has not been written + yet, so this interface MUST NOT be used. It exists only to + indicate what direction we intend to go in.)

+ + +

XMPP supports all of XHTML-IM, and SIP (at least theoretically) + supports all of XHTML. However, many protocols are more limited - + for instance, in MSN you can only set font properties for a + whole message at a time. We should not mislead users into thinking + they can send MSN messages where individual words are emphasized.

+ + +

If this interface is present, clients MAY send XHTML formatted text + in message parts with type "text/html", and SHOULD interpret + "text/html" message parts received in reply.

+ +

Client authors SHOULD pay careful attention to the security + considerations in XEP-0071, "XHTML-IM", to avoid exposing client users + to security risks. Clients MUST NOT assume that connection managers + will filter messages to remove unsafe HTML.

+ + +

Connection managers are the components in Telepathy that are most + likely to be exploitable by a remote attacker to run malicious code + (since they are network-facing), so any filtering that the CM does + might be subverted.

+ + +

To avoid misleading users, clients SHOULD only present UI for the + subset of HTML that is indicated to be supported by this + interface. It follows that clients SHOULD NOT send unsupported + markup to the connection manager. However, even if the connection + manager cannot send arbitrary XHTML, it MUST cope gracefully + with being given arbitrary XHTML by a client.

+ + +

Connection managers should be lenient in what they receive.

+ + +

Clients MUST NOT send HTML that is not well-formed XML, but + connection managers MAY signal HTML that is malformed or invalid. + Clients SHOULD attempt to parse messages as XHTML, but fall back + to using a permissive "tag-soup" HTML parser if that fails. + (FIXME: or should the presence of this interface imply that the + CM fixes up "text/html" to be XHTML? In practice that would result + in all the CMs having to link against libxml2 or something... the + rationale above no longer applies here, since dropping a malformed + message is "safe")

+ + + + + diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml new file mode 100644 index 0000000..ef5a08f --- /dev/null +++ b/spec/Channel_Interface_Hold.xml @@ -0,0 +1,222 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005-2008 Nokia Corporation + Copyright (C) 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. + + + + + + + + first API-stable version + + +

Interface for channels where you may put the channel on hold. + This only makes sense for channels where + you are streaming media to or from the members. (To see whether the + other participant has put you on hold, see CallState.)

+ +

If you place a channel on hold, this indicates that you do not wish + to be sent media streams by any of its members and will be ignoring + any media streams you continue to receive. It also requests that the + connection manager free up any resources that are only needed for + an actively used channel (e.g. in a GSM or PBX call, it will be + necessary to place an active call on hold before you can start + another call).

+ + + + + Return whether the local user has placed the channel on hold. + + + + + The state of the channel + + + + + + The reason why the channel is in that state + + + + + + + Emitted to indicate that the hold state has changed for this channel. + This may occur as a consequence of you requesting a change with + RequestHold, or the state changing as a + result of a request from + another process. + + + + + The state of the channel + + + + + + The reason for the state change + + + + + + + The hold state of a channel. + + + + + All streams are unheld (the call is active). New channels SHOULD + have this hold state. + + + + + + All streams are held (the call is on hold) + + + + + + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + + + + + + The connection manager is attempting to move to state Held, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are on hold. + + + + + + + The reason for a change to the Local_Hold_State. Clients MUST + treat unknown values as equivalent to Local_Hold_State_Reason_None. + + + + + The reason cannot be described by any of the predefined values + (connection managers SHOULD avoid this reason, but clients MUST + handle it gracefully) + + + + + + The change is in response to a user request + + + + + + The change is because some resource was not available + + + + + + + + A boolean indicating whether or not the channel should be on hold + + + + +

Request that the channel be put on hold (be instructed not to send + any media streams to you) or be taken off hold.

+ +

If the connection manager can immediately tell that the requested + state change could not possibly succeed, this method SHOULD + return the NotAvailable error. If the requested state is the + same as the current state, this method SHOULD return successfully + without doing anything.

+ +

Otherwise, this method SHOULD immediately set the hold state to + Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold + (as appropriate), emitting + HoldStateChanged if this is a change, + and return successfully.

+ +

The eventual success or failure of the request is indicated by a + subsequent HoldStateChanged signal, changing the hold state to + Local_Hold_State_Held or Local_Hold_State_Unheld.

+ +

If the channel has multiple streams, and the connection manager + succeeds in changing the hold state of one stream but fails to + change the hold state of another, it SHOULD attempt to revert + all streams to their previous hold states.

+ +

The following state transitions SHOULD be used, where + appropriate:

+ +
    +
  • Successful hold: + (Unheld, any reason) → (Pending_Hold, Requested) → + (Held, Requested) +
    • +
  • Successful unhold: + (Held, any reason) → (Pending_Unhold, Requested) → + (Unheld, Requested) +
    • +
  • Attempting to unhold fails at the first attempt to acquire a + resource: + (Held, any reason) → (Pending_Unhold, Requested) → + (Held, Resource_Not_Available) +
    • +
  • Attempting to unhold acquires one resource, but fails to acquire + a second, and takes time to release the first: + (Held, any reason) → (Pending_Unhold, Requested) → + (Pending_Hold, Resource_Not_Available) → + (Held, Resource_Not_Available) +
    • +
+ + + + + + + + The requested hold state cannot be achieved; for example, + if only a limited number of channels can be in the "not on hold" + state, attempts to exceed this number will raise NotAvailable. + + + + + + + + diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml new file mode 100644 index 0000000..242c952 --- /dev/null +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -0,0 +1,235 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

+ + + + + + +

An interface for signalling a channel containing synchronised media + sessions which can contain an arbitrary number of streams. The + presence of this interface on a Channel indicates that the connection + manager will not carry out the actual streaming for this channel, + and that the client handling the channel is responsible for doing + so; in most cases we recommend doing this by using the + telepathy-farsight library.

+ + +

Streaming audio and (particularly) video requires a high level of + integration with the UI, and having the connection manager act as + a proxy would be likely to introduce unacceptable latency. As a + result, audio/video streaming is offloaded into the client + where possible, as an exception to the general design of + Telepathy.

+ + +

The negotiation interface is based on the API of the + Farsight library. + This, in turn, is based upon the IETF MMusic ICE drafts, where + connections are established by signalling potential connection + candidates to the peer until a usable connection is found, and + codecs are negotiated with an SDP-style offer and answer. However, + the principles should be applicable to other media streaming methods + and the API re-used without difficulty.

+ +

Note that the naming conventions used in the MediaStreamHandler + and MediaSessionHandler interfaces are rather confusing; methods + have signal-like names and signals have method-like names, due to + the API being based rather too closely on that of Farsight. This + is for historical reasons and will be fixed in a future release + of the Telepathy specification.

+ + + + The type of a media session. Currently, the only supported + value is "rtp". + + + + A struct representing a active session handler. + + The object path of the session handler, which is on the + same bus name as the channel. + + + The media session's type + + + + + + + Returns all currently active session handlers on this channel + as a list of (session_handler_path, type). + + + + + + + Object path of the new Media.SessionHandler + object + + + + + String indicating type of session, eg "rtp" + + + + Signal that a session handler object has been created. The client + should create a session object and create streams for the streams + within. + + + + + Use the NATTraversal + property on the Media.StreamHandler, if available; use this + as a fallback. + + A string indicating the NAT traversal techniques employed by the + streams within this channel if they do not have a NATTraversal + property. The possible values are the same as for the NATTraversal + property on the streams. + + + + + Use the STUNServers + property on the Media.StreamHandler, if available; use this + as a fallback. + + The IP address or hostname of the STUN server to use for NAT traversal + if the individual streams do not specify one. + + + + + Use the STUNServers + property on the Media.StreamHandler, if available; use this + as a fallback. + + The UDP port number to use on the provided STUN server. + + + + + XMPP connection managers + supporting the Google Talk relay server SHOULD make the necessary + HTTP requests to find a username and password, and use those + to populate the RelayInfo + property on the Media.StreamHandler. + + The authentication token for use with the Google Talk peer-to-peer relay + server. + + + + + +

The client can implement streaming for streams whose NATTraversal + property is gtalk-p2p.

+ + + + + +

The client can implement streaming for streams whose NATTraversal + property is ice-udp.

+ + + + + +

The client can implement streaming for streams whose NATTraversal + property is wlm-8.5.

+ + + + + +

The client can implement streaming for streams whose NATTraversal + property is wlm-2009.

+ + + + + +

The client supports media streaming with H264 (etc.).

+ +

This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/subtype or video/subtype, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.

+ + +

For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + video/h264 on StreamedMedia channels.

+ + +

For example, a client could advertise support for + Speex, Theora and H264 by having three + handler capability tokens, + org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex, + org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora and + org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264, + in its Capabilities + property.

+ +

Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.

+ + +

This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.

+ + + + + + + diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml new file mode 100644 index 0000000..cd606c1 --- /dev/null +++ b/spec/Channel_Interface_Mergeable_Conference.xml @@ -0,0 +1,110 @@ + + + Copyright © 2009 Collabora Limited + 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 multi-user conference channels that can have + additional individual channels merged into them after they are + created.

+ + +

This interface addresses part of freedesktop.org bug + #24906 (GSM-compatible conference calls). GSM is currently + the only protocol known to implement this; PBXs might implement + it too.

+ +

It might be made into a mandatory-to-implement part of Conference, + or kept as a separate interface, when stabilized.

+ + + + + +

Request that the given channel be incorporated into this + channel.

+ +

The given channel SHOULD be added to Conference.Channels if and only if the + underlying protocol signals the merge in some way. It MUST NOT be + added to Conference.InitialChannels (to preserve + immutability).

+ + +

In GSM it is possible to merge additional calls into an ongoing + conference.

+ +

In XMPP this method could be implemented to merge a 1-1 Text + channel into a MUC Text channel by inviting the peer from the Text + channel into the MUC, or to merge a 1-1 Jingle call into a Muji + call by inviting the peer from the Jingle call into the Muji call. + (MUC and Muji channels are both implemented by XMPP MUCs, with + Handle_Type_Room.)

+ + + + + +

A channel with the same ChannelType + as this one, but with TargetHandleType = CONTACT.

+ + + + + + + The given channel isn't suitable for merging into this one: for + instance, it might have the wrong channel type or handle type. + + + + + It will never be possible to merge channels into this particular + conference. + + + + + The given channel is theoretically suitable for merging into this + one, but that's not currently possible for some reason (for + instance, this SHOULD be raised if a limit on the number of + channels in a conference is exceeded). + [FIXME: PermissionDenied?] + + + + + + + diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml new file mode 100644 index 0000000..62e8384 --- /dev/null +++ b/spec/Channel_Interface_Messages.xml @@ -0,0 +1,1433 @@ + + + Copyright © 2008–2010 Collabora Ltd. + Copyright © 2008–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.

+ + + + (as stable API) + + +

This interface extends the Text + interface to support more general messages, including:

+ +
    +
  • messages with attachments (like MIME multipart/mixed)
    • +
  • groups of alternatives (like MIME multipart/alternative)
    • +
  • delivery reports (which replace Text.SendError), + addding support for protocols where the message content is not echoed + back to the sender on failure and for receiving positive + acknowledgements, as well as ensuring that incoming delivery reports + are not lost if no client is handling the channel yet;
    • +
  • any extra types of message we need in future
    • +
+ +

Incoming messages, outgoing messages, and delivery reports are all + represented as lists of Message_Part structures, + with a format reminiscent of e-mail. Messages are sent by calling + SendMessage; outgoing messages are + announced to other clients which may be interested in the channel by + the MessageSent signal. Incoming + messages and delivery reports are signalled by + MessageReceived, and are stored in the + the PendingMessages property until + acknowledged by calling Text.AcknowledgePendingMessages. + Only the Handler + for a channel should acknowledge messages; Observers + (such as loggers) and Approvers + for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.

+ + +

If observers were allowed to acknowledge messages, then messages + might have been acknowledged before the handler even got to see the + channel, and hence could not be shown to the user.

+ + +

If this interface is present, clients that support it SHOULD + listen for the MessageSent and + MessageReceived signals, and + ignore the Sent, + SendError + and Received + signals on the Text interface (which are guaranteed to duplicate + signals from this interface).

+ +

Although this specification supports formatted (rich-text) + messages with unformatted alternatives, implementations SHOULD NOT + attempt to send formatted messages until the Telepathy specification + has also been extended to cover capability discovery for message + formatting.

+ + + We intend to expose all rich-text messages as XHTML-IM, but on some + protocols, formatting is an extremely limited subset of that format + (e.g. there are protocols where foreground/background colours, font + and size can be set, but only for entire messages). + Until we can tell UIs what controls to offer to the user, it's + unfriendly to offer the user controls that may have no effect. + + + + + +

A list of MIME types supported by this channel, with more preferred + MIME types appearing earlier in the list. The list MAY include "*/*" + to indicate that attachments with arbitrary MIME types can be sent. + This list MUST NOT be empty, since all Messages implementations + MUST accept messages containing a single "text/plain" part.

+ +

Items in this list MUST be normalized to lower-case.

+ +

Some examples of how this property interacts with the + MessagePartSupportFlags:

+ +
+
A simple IM implementation: only plain text messages are + allowed
+
SupportedContentTypes = ['text/plain'], + MessagePartSupportFlags = 0
+ +
Formatted text with a plain text alternative is allowed (see the + HTML interface draft)
+
SupportedContentTypes = ['text/html', 'text/plain'], + MessagePartSupportFlags = 0
+ +
JPEG or PNG images may be sent, but without any attached + text
+
SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = 0
+ +
Unformatted text to which an optional JPEG or PNG image may be + attached
+
SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = One_Attachment
+ +
Formatted text to which arbitrarily many images may be + attached
+
SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg', + 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments
+ +
A full SIP implementation: arbitrary MIME messages are + allowed
+
SupportedContentTypes = ['*/*'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments
+
+ + + + + + This supersedes GetMessageTypes; fall back to that method for + compatibility with older connection managers. + + +

A list of message types which may be sent on this channel.

+ + + + + + Flags indicating the level of support for message parts on this + channel. + + + + + +

Flags indicating the level of support for message parts on this + channel. They are designed such that setting more flags always + implies that the channel has more capabilities.

+ +

If no flags are set, this indicates that messages may contain + a single message part whose content-type is any of the types + from SupportedContentTypes, possibly with some alternatives.

+ +

There is no flag indicating support for alternatives. This is + because the SendMessage implementation can always accept messages + containing alternatives, even if the underlying protocol does not, + by deleting all alternatives except the first (most preferred) + that is supported.

+ + + Each of the flags so far implies the previous flag, so we could + have used a simple enumeration here; however, we've defined + the message-part support indicator as a flag set for future + expansion. + + +

See SupportedContentTypes for some + examples.

+ + + + + SendMessage will accept messages + containing a textual message body, + plus a single attachment of any type listed in the + SupportedContentTypes property. It does not make sense for this + flag to be set if Message_Part_Support_Flag_Data_Only is not also set + (because the connection manager can trivially provide an empty text + part if necessary). + + + + + SendMessage will accept messages containing a textual message body, + plus an arbitrary number of attachments of any type listed in the + SupportedContentTypes property. It does not make sense for this + flag to be set if Message_Part_Support_Flag_One_Attachment is not + also set. + + + + + + +

Part of a message's content. In practice, this mapping never + appears in isolation: incoming messages are represented by a list of + Message_Part mappings in the + MessageReceived signal, and outgoing + messages are passed to SendMessage as + a list of these mappings.

+ +

The first part of the message contains "headers", which refer + to the entire message. The second and subsequent parts contain the + message's content, including plain text, formatted text and/or + attached files. Well-known keys for the header and body parts are + defined by the Message_Header_Key and + Message_Body_Key types, respectively. It is an + error for a connection manager to put keys referring to the message + as a whole in the second or subsequent Message_Part, or keys intended + for body parts in the first Message_Part; clients MUST recover from + this error by ignoring these mis-placed keys.

+ + +

Instead of representing messages as aa{sv} where the first + dictionary is special (a dictionary of headers), we could have + used a signature like (a{sv}aa{sv}) to separate out the headers + and the body parts.

+ +

However, this would make access to the messages more awkward. + In Python, the syntax for access to a header field would remain + message[0]['message-type'], but access to a body + field in the second body part would change from + message[2]['content'] to message[1][1]['content']. In + GLib, the message would change from being a + GPtrArray(GHashTable) to being a + GValueArray(GHashTable, GPtrArray(GHashTable)) which + is rather inconvenient to dereference.

+ + +

In any group of parts with the same non-empty value for the + alternative key (which represent alternative versions of the + same content), more faithful versions of the intended message MUST + come before less faithful versions (note that this order is the + opposite of MIME multipart/alternative parts). Clients + SHOULD display the first alternative that they understand.

+ + +

Specifying the preference order means that if the underlying + protocol doesn't support alternatives, the CM can safely delete + everything apart from the first supported alternative when + sending messages.

+ +

The order is the reverse of MIME because MIME's rationale for + placing the "plainest" part first (legibility in pre-MIME UAs) + does not apply to us, and placing the most preferred part + first simplifies display (a client can iterate the message + in order, display the first alternative that it understands, + and skip displaying all subsequent parts with the same + "alternative" key).

+ + +

Clients SHOULD present all parts that are not redundant + alternatives in the order they appear in this array, possibly + excluding parts that are referenced by another displayed part. + It is implementation-specific how the parts are presented to the + user.

+ + +

This allows CMs to assume that all parts are actually shown to + the user, even if they are not explicitly referenced - we do + not yet recommend formatted text, and there is no way for + plain text to reference an attachment since it has no concept of + markup or references. This also forces clients to do something + sensible with messages that consist entirely of "attachments", + with no "body" at all.

+ +

For instance, when displaying the above example, a client that + understands the HTML part should display the JPEG image once, + between the two lines "Here is a photo of my cat:" and + "Isn't it cute?"; it may additionally present the image in some + way for a second time, after "Isn't it cute?", or may choose + not to.

+ +

A client that does not understand HTML, displaying the same + message, should display the plain-text part, followed by the JPEG + image.

+ + +

Connection managers, clients and extensions to this specification + SHOULD NOT include Handles as values in a + Message_Part, except for message-sender in the + header.

+ + +

Reference-counting handles in clients becomes problematic if + the channel proxy cannot know whether particular map values + are handles or not.

+ + +

Example messages

+ +

A rich-text message, with an embedded image, might be represented + as:

+ + 
+[
+  {
+    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+    'message-sender': 42,
+    'message-sent': 1210067943,
+    'message-received': 1210067947,
+    'message-type': 0,              # = Channel_Text_Message_Type_Normal
+    'pending-message-id': 437,
+  },
+  { 'alternative': 'main',
+    'content-type': 'text/html',
+    'content': 'Here is a photo of my cat:<br />' +
+               '<img src="cid:catphoto" alt="lol!" />' +
+               '<br />Isn't it cute?',
+  },
+  { 'alternative': 'main',
+    'content-type': 'text/plain',
+    'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
+  },
+  { 'identifier': 'catphoto',
+    'content-type': 'image/jpeg',
+    'size': 101000,
+    'needs-retrieval': True,
+  },
+]
+ +

telepathy-ring, Nokia's GSM connection manager, represents vCards + sent via SMS as:

+ + 
+[
+  {
+    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+    'message-sender': 42,
+    'message-sent': 1210067943,
+    'message-received': 1210067947,
+    'message-type': 0,              # = Channel_Text_Message_Type_Normal
+    'pending-message-id': 437,
+  },
+  { 'content-type': 'text/x-vcard',
+    'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
+  },
+]
+ +

Delivery reports

+ +
+

Delivery reports are also represented as messages with the + message-type header mapping to + Channel_Text_Message_Type Delivery_Report. + Delivery reports SHOULD contain the message-sender header, + mapping to the intended recipient of the original message, if + possible; other headers specific to delivery reports are defined by + the Delivery_Report_Header_Key type. The second + and subsequent parts, if present, are a human-readable report from + the IM service.

+ +

For backwards- and forwards-compatibility, whenever a delivery + error report is signalled—that is, with delivery-status + mapping to Delivery_Status Temporarily_Failed or + Permanently_Failed—SendError + SHOULD also be emitted; whenever SendError + is emitted, a delivery report MUST also be signalled. + Delivery report messages on this interface MUST be represented in + emissions of Received + as messages with the Non_Text_Content + Channel_Text_Message_Flags; clients which + understand this interface SHOULD ignore the SendError signal in + favour of listening for delivery reports, as mentioned in the + introduction.

+ +

The result of attempting to send delivery reports using + SendMessage is currently + undefined.

+ +

Example delivery reports

+ +
+
A minimal delivery report indicating permanent failure of the + sent message whose token was + b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown + reason
+ 
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]
+ +
A delivery report where the failed message is echoed back to the + sender rather than being referenced by ID, and the failure reason + is that this protocol cannot send messages to offline contacts + such as the contact with handle 123
+ 
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Temporarily_Failed,
+'delivery-error': Channel_Text_Send_Error_Offline,
+'delivery-echo':
+    [{ # header of original message
+    'message-sender': 1,
+    'message-sent': 1210067943,
+    },
+    { # body of original message
+    'content-type': 'text/plain',
+    'content': 'Hello, world!',
+    }]
+  ],
+
+# no body
+]
+ +
A maximally complex delivery report: the server reports a + bilingual human-readable failure message because the user sent + a message "Hello, world!" with token + b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact + with handle 123, but that handle represents a contact who does not + actually exist
+ 
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+'delivery-echo':
+    [{ # header of original message
+    'message-sender': 1,
+    'message-sent': 1210067943,
+    },
+    { # body of original message
+    'content-type': 'text/plain',
+    'content': 'Hello, world!',
+    }]
+  ],
+},
+{ # message from server (alternative in English)
+'alternative': '404',
+'content-type': 'text/plain',
+'lang': 'en',
+'content': 'I have no contact with that name',
+},
+{ # message from server (alternative in German)
+'alternative': '404'.
+'content-type': 'text/plain',
+'lang': 'de',
+'content', 'Ich habe keinen Kontakt mit diesem Namen',
+}
+]
+ +
A minimal delivery report indicating successful delivery + of the sent message whose token was + b9a991bd-8845-4d7f-a704-215186f43bb4
+ 
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Delivered,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]
+ +
+ +
+ + + + + A key, which SHOULD be one of the well-known keys specified by + Message_Header_Key, + Message_Body_Key or + Delivery_Report_Header_Key if possible. + + + + + + The value corresponding to the given key, which SHOULD be one of the + specified types for well-known keys. + + + + + + + + Removed protocol-token—which had never been implemented—and + respecified message-token not to have unimplementable + uniqueness guarantees. + + + +

Well-known keys for the first Message_Part of a + message, which contains metadata about the message as a whole, along + with the corresponding value types. Some keys make sense for both + incoming and outgoing messages, while others are only meaningful for + one or the other.

+ +
+
message-token (s - + Protocol_Message_Token) +
+
+

An opaque identifier for the message, as used by the + underlying protocol. For outgoing messages, this SHOULD be + globally unique; for incoming messages, this is not + guaranteed to uniquely identify a message, even within the + scope of a single channel or contact; the only guarantee + made is that two messages with different message-token + headers are different messages.

+ +

Clients wishing to determine whether a new message with the + scrollback header matches a previously-logged message + with the same message-token SHOULD compare the + message's sender, contents, message-sent or + message-received timestamp, etc. Note that, in XMPP, + the server only supplies a timestamp for scrollback messages, + not for messages received while you are in a room; thus, + non-scrollback messages will lack a message-sent + timestamp.

+ + +

In practice, most protocols do not provide globally-unique + identifiers for messages. Connection managers, being + stateless, do not have the necessary information — namely, IM + logs — to generate reliable unique tokens for messages.

+ +

For instance, some XMPP clients (including Gabble) stamp + messages they send with unique identifiers, but others number + outgoing messages in a conversation from 1 upwards.

+ +
+ +
message-sent (x - Unix_Timestamp64)
+
The time the message was sent (if unavailable, the time + it arrived at a central server MAY be used). Omitted if no + reasonable approximation is available; SHOULD always be present + on outgoing messages.
+ +
message-received (x - Unix_Timestamp64)
+
The time the message was received locally. SHOULD always + be present.
+ +
message-sender (u - Contact_Handle)
+
The contact who sent the message. If 0 or omitted, the contact + who sent the message could not be determined.
+ +
message-sender-id (s)
+
The identifier of the contact who sent the message, + i.e. the result of calling InspectHandles + on message-sender. If omitted, clients MUST + fall back to looking at message-sender.
+ +
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, + Channel_Text_Message_Type_Normal MUST be assumed. MAY + be omitted for normal chat messages.
+ +
supersedes (s – Protocol_Message_Token)
+
If present, this message supersedes a previous message, + identified by its protocol-token or + message-token header. The user interface MAY, for + example, choose to replace the superseded message with this + message, or grey out the superseded message. + + Skype, for example, allows the user to amend + messages they have already sent (to correct typos, + etc.). +
+ +
pending-message-id (u - Message_ID)
+
The incoming message ID. This MUST NOT be present on outgoing + messages. Clients SHOULD NOT store this key - it is only valid + for as long as the message remains unacknowledged.
+ +
interface (s - DBus_Interface)
+
This message is specific to the given interface, which is + neither Text nor Messages. It SHOULD be ignored if that + interface is not supported. (Note that an 'interface' key + can also appear on the second and subsequent parts, where + it indicates that that part (only) should be ignored if + unsupported.)
+ +
scrollback (b)
+
If present and true, the incoming message was part of a + replay of message history (this matches the Scrollback flag in + Channel_Text_Message_Flags). This flag + does not make sense on outgoing messages and SHOULD NOT + appear there.
+ +
rescued (b)
+
If present and true, the incoming message has been seen in + a previous channel during the lifetime of the Connection, + but had not been acknowledged when that channel closed, causing + an identical channel (in which the message now appears) to open. + This matches the Rescued flag in + Channel_Text_Message_Flags; it + does not make sense on outgoing messages, and SHOULD NOT + appear there.
+
+ + + + + + + +

Well-known keys for the second and subsequent + Message_Parts of a message, which contain the + message content, along with the corresponding value types.

+ +
+
identifier (s — + Protocol_Content_Identifier)
+
An opaque identifier for this part. + Parts of a message MAY reference other parts by treating + this identifier as if it were a MIME Content-ID and using + the cid: URI scheme.
+ +
alternative (s)
+
+

If present, this part of the message is an alternative for + all other parts with the same value for "alternative". + Clients SHOULD only display one of them (this is expected to + be used for XHTML messages in a future version of this + specification).

+ +

If omitted, this part is not an alternative for any other + part.

+ +

Parts of a message MAY reference the group of alternatives + as a whole (i.e. a reference to whichever of them is chosen) + by treating this identifier as if it were the MIME Content-ID + of a multipart/alternative part, and using the cid: URI + scheme.

+
+ +
content-type (s)
+
+

The MIME type of this part. See the documentation + for MessageReceived and + MessageSent for notes on the + special status of "text/plain" parts.

+ +

Connection managers MUST NOT signal parts without a + 'content-type' key; if a protocol provides no way to determine + the MIME type, the connection manager is responsible for + guessing it, but MAY fall back to "text/plain" for text and + "application/octet-stream" for non-text.

+ +

Clients MUST ignore parts without a 'content-type' key, which + are reserved for future expansion.

+ +

When sending messages, clients SHOULD normalize the + content-type to lower case, but connection managers SHOULD NOT + rely on this. When signalling sent or received messages, + connection managers MUST normalize the content-type to lower + case.

+
+ +
lang (s)
+
The natural language of this part, identified by a + RFC 3066 language tag. + + + XMPP allows alternative-selection by language as well as + by content-type. + +
+ +
size (u)
+
The size in bytes (if needs-retrieval is true, this MAY be an + estimated or approximate size). SHOULD be omitted if 'content' + is provided. + + + There's no point in providing the size if you're already + providing all the content. + +
+ +
thumbnail (b)
+
+

This part is a thumbnail. To represent an image together with + its thumbnail in a single message, there should be one part for + the full image followed by a part for the thumbnail (following + the “more complete versions first” requirement), with the same + 'alternative' value. For example:

+ + 
+[ ... ,
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg',
+    'size': 150000,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg'
+    'size': 1024,
+    'thumbnail': True,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  ...
+]
+
+ +
needs-retrieval (b)
+
If false or omitted, the connection + manager already holds this part in memory. If present and true, + this part must be retrieved on demand (like MIME's + message/external-body) by a mechanism to be defined later. + + The mechanism was meant to be + GetPendingMessageContent, but + that didn't work out. It's worth leaving the header in in + preparation for a future mechanism. + +
+ +
truncated (b)
+
The content available via the 'content' key has been truncated + by the server or connection manager (equivalent to + Channel_Text_Message_Flag_Truncated in the Text interface). +
+ +
content (s or ay)
+
The part's content, if it is available and + sufficiently small to include here (implies that + 'needs-retrieval' is false or omitted). Otherwise, omitted. + If the part is human-readable text or HTML, the value for this + key MUST be a UTF-8 string (D-Bus signature 's'). + If the part is not text, the value MUST be a byte-array + (D-Bus signature 'ay'). If the part is a text-based format + that is not the main body of the message (e.g. an iCalendar + or an attached XML document), the value SHOULD be a UTF-8 string, + transcoding from another charset to UTF-8 if necessary, but + MAY be a byte-array (of unspecified character set) if + transcoding fails or the source charset is not known.
+ + + +
interface (s - DBus_Interface)
+
This part is specific to the given interface, which is + neither Text nor Messages. It SHOULD be ignored if that + interface is not supported. (Note that an 'interface' key + can also appear on the first part, where it indicates that the + entire message should be ignored if unsupported.)
+
+ + + + + + +

Well-known keys for the first Message_Part of a + delivery report, along with the corresponding value types. Some of + these are special-cases of headers defined by + Message_Header_Key.

+ +
+
message-sender (u - Contact_Handle, as + defined by Message_Header_Key)
+
MUST be the intended recipient of the original message, if + available (zero or omitted if the intended recipient is + unavailable or is not a contact, e.g. a chatroom), even if the + delivery report actually came from an intermediate server.
+ +
message-type (u - Channel_Text_Message_Type, + as defined by Message_Header_Key)
+
MUST be Channel_Text_Message_Type_Delivery_Report.
+ +
delivery-status (u - Delivery_Status)
+
The status of the message. All delivery reports MUST contain + this key in the first Message_Part.
+ +
delivery-token (s - Protocol_Message_Token)
+ +
+

An identifier for the message to which this delivery report + refers. MUST NOT be an empty string. Omitted if not + available.

+ +

Clients may match this against the token produced by the + SendMessage method and MessageSent signal. A status report + with no token could match any sent message, and a sent + message with an empty token could match any status report. + If multiple sent messages match, clients SHOULD use some + reasonable heuristic.

+ + + In an ideal world, we could unambiguously match reports + against messages; however, deployed protocols are not ideal, + and not all reports and messages can be matched. + +
+ +
delivery-error (u - + Channel_Text_Send_Error)
+
+ The reason for the failure. MUST be omitted if this was a + successful delivery; SHOULD be omitted if it would be + Channel_Text_Send_Error_Unknown. +
+ +
delivery-dbus-error (s - + DBus_Error_Name)
+
+ The reason for the failure, specified as a (possibly + implementation-specific) D-Bus error. MUST be omitted if this was + a successful delivery. If set, the 'delivery-error' key SHOULD be + set to the closest available value. +
+ +
delivery-error-message (s)
+
+ Debugging information on why the message could not be delivered. + MUST be omitted if this was a successful delivery; MAY always be + omitted. +
+ +
delivery-echo (aa{sv} - Message_Part[])
+
+

The message content, as defined by the Messages interface. + Omitted if no content is available. Content MAY have been + truncated, message parts MAY have been removed, and message + parts MAY have had their content removed (i.e. the message part + metadata is present, but the 'content' key is not).

+ + + Some protocols, like XMPP, echo the failing message back to + the sender. This is sometimes the only way to match it + against the sent message, so we include it here. + +
+ +
+ + + + + + This type is only used by + GetPendingMessageContent, which is + unimplemented and deprecated. + + + + The index of a message part within a message. + + + + + + + This structure is only used by + GetPendingMessageContent, which is + unimplemented and deprecated. + + + A mapping from message part indexes to their content, as returned by + GetPendingMessageContent. + + + + + Indexes into the array of Message_Parts that + represents a message. The "headers" part (which is not a valid + argument to GetPendingMessageContent) is considered to be part 0, + so the valid part numbers start at 1 (for the second message part). + + + + + + The message part's content. The variant MUST contain either type + 's' or 'ay' (UTF-8 text string, or byte array), following the + same rules as for the value of the 'content' key in + the Message_Part mappings. + + + + + + +

An opaque token used to identify messages in the underlying. + protocol. As a special case, the empty string indicates that there + is no particular identification for a message.

+ +

CM implementations SHOULD use an identifier expected to be unique, + such as a UUID, for outgoing messages (if possible).

+ +

Some protocols can only track a limited number of messages + in a small message-ID space (SMS messages are identified by a single + byte), and some implementations send non-unique identifiers (some + XMPP clients use very simple message IDs, such as an incrementing + integer that resets to 1 at the beginning of each connection). As a + result, clients MUST NOT assume that protocol tokens will not be + re-used.

+ +

In particular, clients SHOULD use a heuristic to assign delivery + reports to messages, such as matching on message content or + timestamp (if available), or assuming that the delivery report + refers to the most recent message with that ID.

+ + + + + +

A protocol-specific identifier for a blob of content, as used for + the identifier key in a Message_Part. The + same identifier MAY be re-used if the same content, byte-for-byte, + appears as a part of several messages.

+ + +

On XMPP, these identifiers might be Content-IDs for custom + smileys implemented using XEP-0232 Bits of + Binary; the same smiley might well appear in multiple + messages.

+ + + + + + +

Submit a message to the server for sending. + If this method returns successfully, the message has been submitted + to the server and the MessageSent + signal is emitted. A corresponding + Sent + signal on the Text interface MUST also be emitted.

+ +

This method MUST return before the MessageSent signal is + emitted.

+ + +

This means that the process sending the message is the first + to see the Protocol_Message_Token, and can + relate the message to the corresponding + MessageSent signal by comparing + message tokens (if supported by the protocol).

+ + +

If this method fails, message submission to the server has failed + and no signal on this interface (or the Text interface) is + emitted.

+ +

If this method succeeds, message submission to the server has + succeeded, but the message has not necessarily reached its intended + recipient. If a delivery failure is detected later, this is + signalled by receiving a message whose message-type + header maps to + Channel_Text_Message_Type_Delivery_Report. + Similarly, if delivery is detected to have been successful + (which is not possible in all protocols), a successful delivery + report will be signalled.

+ + + + + The message content, including any attachments or alternatives. + This MUST NOT include the following headers, or any others that + do not make sense for a client to specify: + message-sender, message-sender-id, + message-sent, message-received, + pending-message-id. + + + + + Flags affecting how the message is sent. The channel MAY ignore some + or all flags, depending on + DeliveryReportingSupport; the flags + that were handled by the CM are provided in + MessageSent. + + + + + + An opaque token used to match any incoming delivery or failure + reports against this message, or an empty string if the message + is not readily identifiable. + + + + + + + The requested message is malformed and cannot be sent. + + + + + + + + + + + Flags altering the way a message is sent. The "most usual" action + should always be to have these flags unset. Some indication of which + flags are supported is provided by the + DeliveryReportingSupport property. + + + + +

Provide a successful delivery report if possible, even if this is + not the default for this protocol. Ignored if delivery reports are + not possible on this protocol.

+ + +

In some protocols, like XMPP, it is not conventional to request + or send positive delivery notifications.

+ + +

Delivery failure reports SHOULD always be sent, but if this flag + is present, the connection manager MAY also try harder to obtain + failed delivery reports or allow them to be matched to outgoing + messages.

+ + + + + + +

Provide a delivery report when the message is read by the + recipient, even if this is not the default for this protocol. + Ignored if read reports are not possible on this protocol.

+ + + + + + +

Provide a delivery report when the message is deleted by the + recipient, even if this is not the default for this protocol. + Ignored if such reports are not possible on this protocol.

+ + + + + + +

Signals that a message has been submitted for sending. This + MUST be emitted exactly once per emission of the Sent + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter if this interface is present, as mentioned + in the introduction.

+ +

This SHOULD be emitted as soon as the CM determines it's + theoretically possible to send the message (e.g. the parameters are + supported and correct).

+ + +

This signal allows a process that is not the caller of + SendMessage to log sent messages.

+ + + + + +

The message content (see Message_Part for full + details). If the message that was passed to + SendMessage has a formatted text + part that the connection manager recognises, but no + text/plain alternative, the CM MUST use the formatted text + part to generate a text/plain alternative which is also + included in this signal argument.

+ +

The connection manager SHOULD include the + message-sender, message-sender-id and + message-sent headers in the representation of the + message that is signalled here. If the channel has + channel-specific handles, the message-sender and + message-sender-id SHOULD reflect the sender that + other contacts will see.

+ +

If the connection manager can predict that the message will be + altered during transmission, this argument SHOULD reflect what + other contacts will receive, rather than being a copy of the + argument to SendMessage (if the message is truncated, + formatting or alternatives are dropped, etc., then the edited + version SHOULD appear in this signal).

+ + + + + +

Flags affecting how the message was sent. The flags might be a + subset of those passed to SendMessage if the caller requested + unsupported flags.

+ + + + + + An opaque token used to match any incoming delivery or failure + reports against this message, or an empty string if the message + is not readily identifiable. + + + + + + +

A list of incoming messages that have neither been acknowledged nor + rejected. This list is a more detailed version of the one returned + by Text.ListPendingMessages, + and contains the same messages, uniquely identified by the same + pending message IDs. Its items can be removed using + Text.AcknowledgePendingMessages.

+ +

Change notification is via + MessageReceived and + PendingMessagesRemoved.

+ + + + + + The messages with the given IDs have been removed from the + PendingMessages list. Clients SHOULD NOT + attempt to acknowledge those messages. + + + This completes change notification for the PendingMessages property + (previously, there was change notification when pending messages + were added, but not when they were removed). + + + + + + The messages that have been removed from the pending message list. + + + + + + + This method has never been implemented, and in any case would have been + impossible to use correctly when multiple clients (such as a logger and + the handler) are interested in a text channel. See freedesktop.org + bug #26417 for more details. + + + Retrieve the content of one or more parts of a pending message. + Note that this function may take a considerable amount of time + to return if the part's 'needs-retrieval' flag is true; consider + extending the default D-Bus method call timeout. Additional API is + likely to be added in future, to stream large message parts. + + + + + The ID of a pending message + + + + + + The desired entries in the array of message parts, identified by + their position. The "headers" part (which is not a valid argument + to this method) is considered to be part 0, so the valid part + numbers start at 1 (for the second Message_Part). + + + + + +

The content of the requested parts. The keys in this mapping + are positions in the array of message parts; the values are + either of type 's' or 'ay' (UTF-8 text string, or byte array), + following the same rules as for the value of the 'content' key in + the Message_Part mappings.

+ +

If the one of the requested part numbers was greater than zero + but referred to a part that had no content (i.e. it had no + 'content-type' key or no 'content' key), it is simply omitted from + this mapping; this is not considered to be an error condition.

+ + + + + + + Either there is no pending message with the given message ID, + or one of the part numbers given was 0 or too large. + + + + + + + + + + + Signals that a message has been received and added to the pending + messages queue. This MUST be emitted exactly once per emission of the + Received + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter in favour of this signal if this interface is + present, as mentioned in the introduction. + + + + +

The message content, including any attachments or alternatives. If + the incoming message contains formatted text without a plain text + alternative, the connection manager MUST generate a + text/plain alternative from the formatted text, and + include it in this message (both here, and in the + PendingMessages property).

+ + + + + + +

The status of a message as indicated by a delivery report.

+ +

If this enum is extended in future specifications, this should + only be to add new, non-overlapping conditions (i.e. all failures + should still be signalled as either Temporarily_Failed + or Permanently_Failed). If additional detail is required (e.g. + distinguishing between the various types of permanent failure) this + will be done using additional + Delivery_Report_Header_Keys.

+ + + + + The message's disposition is unknown. + Clients SHOULD consider all messages to have status + Delivery_Status_Unknown unless otherwise specified; connection + managers SHOULD NOT signal this delivery status explicitly. + + + + + + The message has been delivered to the intended recipient. + + + + + + Delivery of the message has failed. Clients SHOULD notify the user, + but MAY automatically try sending another copy of the message. + + + Similar to errors with type="wait" in XMPP; analogous to + 4xx errors in SMTP. + + + + + + + Delivery of the message has failed. Clients SHOULD NOT try again + unless by specific user action. If the user does not modify the + message or alter configuration before re-sending, this error is + likely to happen again. + + + Similar to errors with type="cancel", type="modify" + or type="auth" in XMPP; analogous to 5xx errors in SMTP. + + + + + + + An intermediate server has accepted the message but the message + has not been yet delivered to the ultimate recipient. The + connection manager might send a Failed report or Delivered report + later. + + + Similar to "202 Accepted" success code in SIP; analogous to + 251 and 252 responses in SMTP. + + + + + + + + The message has been read by the intended recipient. + + + + + + + The message has been deleted by the intended recipient. This MAY be + signalled on its own if the message is deleted without being read, or + after Read if the message was read before being deleted. + + + + + + + Flags indicating the level of support for delivery reporting on this + channel, as found on the + DeliveryReportingSupport property. Any + future flags added to this set will conform to the + convention that the presence of an extra flag implies that + more operations will succeed. Note that CMs may always provide more + reports than are requested in the + Message_Sending_Flags passed to + SendMessage. + + + If senders want delivery reports, they should ask for them. If they + don't want delivery reports, they can just ignore them, so there's no + need to have capability discovery for what will happen if a delivery + report isn't requested. + + + + + + Clients MAY expect to receive negative delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + + + + + + Clients MAY expect to receive positive delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + + + + + + + Clients MAY expect to receive Delivery_Status + Read reports if Message_Sending_Flag_Report_Read + is specified when sending. + + + + + + + Clients MAY expect to receive Delivery_Status + Deleted reports if Message_Sending_Flag_Report_Deleted + is specified when sending. + + + + + + + A bitfield indicating features supported by this channel. + + + + + + diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml new file mode 100644 index 0000000..4e201dd --- /dev/null +++ b/spec/Channel_Interface_Password.xml @@ -0,0 +1,104 @@ + + + +Copyright © 2005-2009 Collabora Limited +Copyright © 2005-2009 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 +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. + + + + + + + The ProvidePassword method must be + called now for the user to join the channel + + + + + + + An integer with the logical OR of all the flags set + (values of ChannelPasswordFlags) + + + + Returns the bitwise-OR of the flags relevant to the password on this + channel. The user interface can use this to present information about + which operations are currently valid. + + + + + + + + + + A bitwise OR of the flags which have been set + + + + + A bitwise OR of the flags which have been cleared + + + + Emitted when the flags as returned by + GetPasswordFlags are changed. + The user interface should be updated as appropriate. + + + + + + The password + + + + + A boolean indicating whether or not the password was correct + + + + Provide the password so that the channel can be joined. Must be + called with the correct password in order for channel joining to + proceed if the 'provide' password flag is set. + + + + + + + + +

Interface for channels that may have a password set that users need + to provide before being able to join, or may be able to view or change + once they have joined the channel.

+ +

The GetPasswordFlags method and the + associated PasswordFlagsChanged + signal indicate whether the channel has a password, whether the user + must now provide it to join, and whether it can be viewed or changed + by the user.

+ + + + diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml new file mode 100644 index 0000000..ffdf4a9 --- /dev/null +++ b/spec/Channel_Interface_Room.xml @@ -0,0 +1,373 @@ + + + + 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 1) + + +

Different IM protocols use a variety of ways to name chat rooms. The + simplest example is perhaps IRC, where chat rooms have short, + persistent, human-readable string names, and are generally global + across the network. Skype chat rooms have persistent string names, so + you can leave and re-join a room, but these names are opaque unique + identifiers. MSN chat rooms are unnamed, and you can only join one by + being invited. And XMPP wins the coveted “most complicated chat rooms” + prize: chat rooms may be hosted by different servers with different DNS + names; normally they have human-readable names, except that all MUCs on + Google Talk's conference server have UUIDs as names, and XEP-0045 §10.1.4 + Requesting a Unique Room Name defines a protocol for + requesting a unique, opaque room name on the server.

+ +

This interface intends to support and differentiate these mechanisms + more clearly than the TargetHandleType + and TargetID + properties can alone. It initially contains a pair of properties used + to represent the human-readable parts of a + Room_Handle's identifier, if any. The above examples + for different protocols are represented as follows:

+ +
    +
  • The IRC channel #telepathy on Freenode is represented by a + channel with properties + TargetHandleType + = Room, + TargetID + = "#telepathy", + RoomID = "#telepathy", + Server = "", indicating + that the room has a human-readable identifier, and is not confined to + a particular server on the network. + + + Actually, IRC supports creating “local” channels specific to the + server they are created on. These channels have identifiers + starting with & rather than #. These could be + represented by setting Server + appropriately. + +
    • + +
  • A Skype group chat with opaque identifier 0xdeadbeef has + TargetHandleType + = Room, + TargetID + = "0xdeadbeef", + RoomID = "", + Server = "", indicating + that the room has an identifier but no human-readable name. +
    • + +
  • An MSN group chat has + TargetHandleType + = None, + RoomID = "", + Server = "", indicating + that the room has neither an identifier (so it cannot be re-joined + later) nor a human-readable name. +
    • + +
  • A standard Jabber multi-user chat + jdev@conference.jabber.org has + TargetHandleType + = Room, + TargetID + = "jdev@conference.jabber.org", + RoomID = "jdev", + Server = "conference.jabber.org". +
    • + +
  • A Google Talk private MUC private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com has + TargetHandleType + = Room, + TargetID + = "private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com", + RoomID = "", + Server = + "groupchat.google.com", indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. +
    • + +
  • Similarly, a XEP-0045 §10.1.4 uniquely-named room + lrcgsnthzvwm@conference.jabber.org has + TargetHandleType + = Room, + TargetID + = "lrcgsnthzvwm@conference.jabber.org", + RoomID = "", + Server = + "conference.jabber.org", indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. +
    • +
+ +

Requestable channel classes

+ +

If the connection supports joining text chat rooms by unique + identifier, like Skype, it should advertise a + Requestable_Channel_Class matching:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: Room,
+          },
+  Allowed = [ ...TargetID,
+              ...TargetHandle,
+            ]
+)
+ +

Channel requests must specify either TargetID or TargetHandle.

+ +

If, like IRC, the room identifiers are also human-readable, the + RCCs should also include RoomID in Allowed_Properties:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: Room,
+          },
+  Allowed = [ ...TargetID,
+              ...TargetHandle,
+              ...RoomID
+            ]
+),
+
+( Fixed = { ...ChannelType: ...Text
+          },
+  Allowed = [ ...RoomID,
+            ]
+)
+ +

Requests may specify the RoomID in place of + TargetID or + TargetHandle + . Note how RoomID appears + in Allowed_Properties of a different RCC because + when TargetHandleType is omitted (or is None), both + TargetHandle and + TargetID must also be omitted. + RoomID is allowed in conjuction + with + TargetID or + TargetHandle + in some situations, as explained below in the Requesting room + channels section. +

+ +

If rooms may be on different servers, Server + should also be included in the allowed properties, but + CMs MUST use a reasonable default + Server if not explicitly + specified in a channel request. The CM's default server MAY + be configurable by a connection parameter specified on a + RequestConnection call, similarly to how the + fallback conference server is specified on jabber connections in + gabble.

+ +

If the protocol supports unnamed rooms, RoomID + should be fixed to the empty string, and + TargetHandleType + should be None:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: None,
+            ...RoomID: "",
+          },
+  Allowed = [ ]
+)
+ +

Requesting room channels

+ +

When explicitly joining a room, the CM cannot know whether the room + ID is unique or not. As a result, if this is the case, adding an + empty string RoomID into the channel + request will ensure the CM knows. For example:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...TargetHandleType: Room,
+  ...TargetID: "qwerasdfzxcv@conference.jabber.org",
+  ...RoomID: ""
+}
+ +

If RoomID features in + Allowed_Properties then the only value allowed in conjunction + with TargetID + or TargetHandle + is the empty string. Requests with conflicting + TargetID + and RoomID properties + will fail with InvalidArgument.

+ +

To create a XEP-0045 §10.1.4 uniquely-named room channel + on the conference.jabber.org server, then the following channel + request should be made:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...RoomID: ""
+  ...Server: "conference.jabber.org"
+}
+
+ +

If everything is successful, then when the channel request is + satisfied, a new channel will appear with the following properties:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...TargetHandleType: Room,
+  ...TargetID: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
+  ...RoomID: ""
+  ...Server: "conference.jabber.org"
+}
+
+ +

The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) + and then created a room with such a name on the said server. The empty + RoomID property shows that the room name + is not human-readable.

+ + + + + +

The human-readable identifier of a chat room. Note that if + non-empty, this property (and perhaps also + Server) should be sufficient in + a channel request to join the room. XMPP MUCs have a room name + concept which is more like a topic, except more + persistent. This D-Bus property is not this + XMPP room name, but the bit before the @ in the room jid.

+ +

This property cannot change during the lifetime of the channel. It + should appear in the Allowed_Properties of a + Requestable_Channel_Class for the connection if + rooms on this connection have human-readable names, and can be joined + by name.

+ + + + + +

For protocols with a concept of chatrooms on multiple servers with + different DNS names (like XMPP), the DNS name of the server hosting + this channel (for example, "conference.jabber.org" or + "groupchat.google.com"). For other protocols, the empty + string.

+ +

This property cannot change during the lifetime of the channel. It + should appear in the Allowed_Properties of a + Requestable_Channel_Class for the connection if + and only if non-empty values are supported.

+ + + + + + A struct representing the subject of a room channel. + + + + A human-readable description of the current subject of + conversation in the channel, similar to /topic in IRC. + + + + + A normalized contact ID representing who last modified the + subject, or the empty string if it is not known. + + + + + A unix timestamp indicating when the subject was last modified. + + + + + + +

The subject on the room such as the topic in an IRC channel, + or the room name in XMPP MUCs. In protocols which do not support + subjects (like MSN), this property should be ("", "", 0).

+ + This property replaces the subject, subject-contact, and + subject-timestamp Telepathy properties of Text channels, as Telepathy + properties are soon to be deprecated completely. + +

This property may change during the lifetime of the channel and + MUST not be included in a channel request.

+ + + + + + diff --git a/spec/Channel_Interface_SASL_Authentication.xml b/spec/Channel_Interface_SASL_Authentication.xml new file mode 100644 index 0000000..38568b1 --- /dev/null +++ b/spec/Channel_Interface_SASL_Authentication.xml @@ -0,0 +1,704 @@ + + + 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 stable API) + + +

A channel interface for SASL authentication, + as defined by + RFC 4422. + When this interface appears on a ServerAuthentication + channel, it represents authentication with the server. In future, + it could also be used to authenticate with secondary services, + or even to authenticate end-to-end connections with contacts. As a result, + this interface does not REQUIRE ServerAuthentication to allow for a potential future + Channel.Type.PeerAuthentication interface.

+ +

In any protocol that requires a password, the connection manager can + use this channel to let a user interface carry out a simple SASL-like + handshake with it, as a way to get the user's credentials + interactively. This can be used to connect to protocols that may + require a password, without requiring that the password is saved in + the Account.Parameters.

+ +

In some protocols, such as XMPP, authentication with the server + is also carried out using SASL. In these protocols, a channel with this + interface can provide a simple 1:1 mapping of the SASL negotiations + taking place in the protocol, allowing more advanced clients to + perform authentication via SASL mechanisms not known to the + connection manager.

+ + +

By providing SASL directly when the protocol supports it, we can + use mechanisms like Kerberos or Google's X-GOOGLE-TOKEN + without specific support in the connection manager.

+ + +

For channels managed by a + ChannelDispatcher, + only the channel's Handler may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.

+ + +

There can only be one Handler, which is a good fit for SASL's + 1-1 conversation between a client and a server.

+ + + + + +

A SASL mechanism, as defined by + RFC 4422 + and registered in + the + IANA registry of SASL mechanisms, or an unregistered + SASL mechanism such as X-GOOGLE-TOKEN used in the + same contexts.

+ +

As a special case, pseudo-mechanisms starting with + X-TELEPATHY- are defined by this specification. + Use of these pseudo-mechanisms indicates that the user's credentials + are to be passed to the connection manager, which will then use + them for authentication with the service, either by implementing + the client side of some SASL mechanisms itself or by using a + non-SASL protocol. The only such pseudo-mechanism currently + defined is X-TELEPATHY-PASSWORD.

+ +

The X-TELEPATHY-PASSWORD mechanism is extremely + simple:

+ +
    +
  • The client MUST call + StartMechanismWithData, with + Initial_Data set to the password encoded in UTF-8. + For simplicity, calling StartMechanism + followed by calling Respond is not + allowed in this mechanism.
    • + +
  • The connection manager uses the password, together with + authentication details from the Connection parameters, to + authenticate itself to the server.
    • + +
  • When the connection manager finishes its attempt to authenticate + to the server, the channel's state changes to + either SASL_Status_Server_Succeeded or + SASL_Status_Server_Failed as appropriate.
    • +
+ + + + + +

The SASL mechanisms as offered by the server, plus any + pseudo-SASL mechanisms supported by the connection manager for + credentials transfer. For instance, in a protocol that + natively uses SASL (like XMPP), this might be + [ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", + "SCRAM-SHA-1" ].

+ +

To make it possible to implement a very simple password-querying + user interface without knowledge of any particular SASL mechanism, + implementations of this interface MUST implement the + pseudo-mechanism X-TELEPATHY-PASSWORD, unless none + of the available mechanisms use a password at all.

+ + + + + +

If true, StartMechanismWithData + can be expected to work for SASL mechanisms not starting with + X-TELEPATHY- (this is the case in most, but not all, + protocols). If false, StartMechanism + must be used instead.

+ +

This property does not affect the X-TELEPATHY- + pseudo-mechanisms such as X-TELEPATHY-PASSWORD, + which can use + StartMechanismWithData regardless + of the value of this property.

+ + + + + +

If true, StartMechanism and (if + supported) StartMechanismWithData + can be expected to work when in one of the Failed states. If + false, the only thing you can do after failure is to close the + channel.

+ + +

Retrying isn't required to work, although some protocols and + implementations allow it.

+ + + + + + + The current status of this channel. + Change notification is via the + SASLStatusChanged signal. + + + + + +

The reason for the SASLStatus, or + an empty string if the state is neither + Server_Failed nor Client_Failed.

+ +

In particular, an ordinary authentication failure (as would + be produced for an incorrect password) SHOULD be represented by + AuthenticationFailed, + cancellation by the user's request SHOULD be represented + by Cancelled, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + ServiceConfused.

+ +

If this interface appears on a ServerAuthentication + channel, and connection to the server fails with an authentication + failure, this error code SHOULD be copied into the + Connection.ConnectionError + signal.

+ + + + + +

If SASLError is non-empty, + any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + Connection.ConnectionError.

+ +

If this interface appears on a ServerAuthentication + channel, and connection to the server fails with an authentication + failure, these details SHOULD be copied into the + Connection.ConnectionError + signal.

+ + + + + +

The identity for which authorization is being attempted, + typically the 'account' from the RequestConnection + parameters, normalized and formatted according to the + conventions used for SASL in this protocol.

+ + +

The normalization used for SASL might not be the same + normalization used elsewhere: for instance, in a protocol + with email-like identifiers such as XMPP or SIP, the user + "juliet@example.com" might have to authenticate to the + example.com server via SASL PLAIN as "juliet".

+ + +

This is usually achieved by using the authorization identity for + authentication, but an advanced Handler could offer the option + to authenticate under a different identity.

+ +

The terminology used here is that the authorization identity + is who you want to act as, and the authentication identity is + used to prove that you may do so. For instance, if Juliet is + authorized to access a role account, "sysadmin@example.com", + and act on its behalf, it might be possible to authenticate + as "juliet@example.com" with her own password, but request to + be authorized as "sysadmin@example.com" instead of her own + account. See + RFC + 4422 §3.4.1 for more details.

+ + +

In SASL the authorization identity is normally guessed from + the authentication identity, but the information available + to the connection manager is the identity for which + authorization is required, such as the desired JID in XMPP, + so that's what we signal to UIs; it's up to the UI to + choose whether to authenticate as the authorization identity + or some other identity.

+ +

As a concrete example, the "sysadmin" XMPP account mentioned + above would have { 'account': 'sysadmin@example.com' } + in its Parameters, and this property would also be + 'sysadmin@example.com'. A simple Handler would + merely prompt for sysadmin@example.com's password, + and use that JID as both the authorization and authentication + identity, which might result in SASL PLAIN authentication with the + initial response + '\000sysadmin@example.com\000root'.

+ +

A more advanced Handler might also ask for an authentication + identity, defaulting to 'sysadmin@example.com'; if Juliet + provided authentication identity 'juliet@example.com' and + password 'romeo', the Handler might perform SASL PLAIN + authentication using the initial response + 'sysadmin@example.com\000juliet@example.com\000romeo'.

+ + + + + + +

The default username for use with SASL mechanisms that deal + with a "simple username" (as defined in RFC 4422). If + such a SASL mechanism is in use, clients SHOULD default to + using the DefaultUsername; also, if the client uses + the DefaultUsername, it SHOULD assume that the authorization + identity AuthorizationIdentity + will be derived from it by the server.

+ + +

In XMPP, + servers typically expect "user@example.com" to + authenticate with username "user"; this was a SHOULD in RFC 3920.

+ +

3920bis + weakens that SHOULD to "in the absence of local information + provided by the server, an XMPP client SHOULD assume that + the authentication identity for such a SASL mechanism is the + combination of a user name and password, where the simple + user name is the localpart of the user's JID".

+ + +

For example, in the simple case, if the user connects with + RequestConnection({ + account: "user@example.com" }) and use PLAIN with + password "password", he or she should authenticate like so: + "\0user\0password" and the channel will look like + this:

+ +
{ "...DefaultUsername": "user",
+  "...AuthorizationIdentity": "user@example.com }
+
+ +

In the complex case, if the same user is using his or her + sysadmin powers to log in as the "announcements" role address, + he or she would connect with RequestConnection({ + account: "announcements@example.com" }) and the SASL + channel would look like this:

+ +
{ "...DefaultUsername": "announcements",
+  "...AuthorizationIdentity": "announcements@example.com }
+
+ +

A sufficiently elaborate UI could give the opportunity + to override the username from "announcements" to "user". + The user's simple username is still "user", and the password is + still "password", but this time he or she is trying to authorize + to act as announcements@example.com, so the UI would + have to perform SASL PLAIN with this string: + "announcements@example.com\0user\0password", where + "announcements@example.com" is the + AuthorizationIdentity.

+ + + + + +

The default realm (as defined in + RFC + 2831) to use for authentication, if the server does not + supply one.

+ + +

The server is not required to provide a realm; if it doesn't, + the client is expected to ask the user or provide a sensible + default, typically the requested DNS name of the server. + In some implementations of DIGEST-MD5, the + server does not specify a realm, but expects that the client + will choose a particular default, and authentication will + fail if the client's default is different. Connection + managers for protocols where this occurs are more easily able + to work around these implementations than a generic client + would be.

+ + + + + + + + The chosen mechanism. + + + +

Start an authentication try using Mechanism, without + sending initial data (an "initial response" as defined in RFC + 4422).

+ + +

This method is appropriate for mechanisms where the client + cannot send anything until it receives a challenge from the + server, such as + DIGEST-MD5 + in "initial authentication" mode.

+ + + + + + + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + CanTryAgain is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + AbortSASL and wait for + SASL_Status_Client_Failed before starting another attempt. + + + + + + The server or connection manager doesn't implement the given + SASL mechanism. Choose a SASL mechanism from + AvailableMechanisms, or abort + authentication if none of them are suitable. + + + + + + + + + The chosen mechanism. + + + + + Initial data (an "initial response" in RFC 4422's terminology) to send + with the mechanism. + + + +

Start an authentication try using Mechanism, and send + Initial_Data as the "initial response" defined in + RFC 4422 + §3.3.

+ + +

This method is appropriate for mechanisms where the client may + send data first, such as PLAIN, or must send data + first, such as + DIGEST-MD5 + in "subsequent authentication" mode.

+ +

Having two methods allows any mechanism where it makes a difference + to distinguish between the absence of an initial response + (StartMechanism) and a zero-byte + initial response (StartMechanismWithData, with Initial_Data + empty).

+ + +

If the HasInitialData + property is false, this indicates that the underlying protocol + does not make it possible to send initial data. In such protocols, + this method may only be used for the X-TELEPATHY- + pseudo-mechanisms (such as X-TELEPATHY-PASSWORD), + and will fail if used with an ordinary SASL mechanism.

+ + +

For instance, the IRC SASL extension implemented in Charybdis and + Atheme does not support initial data - the first message in the + exchange only carries the mechanism. This is significant if using + DIGEST-MD5, + which cannot be used in the faster "subsequent authentication" + mode on a protocol not supporting initial data.

+ + + + + + + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + CanTryAgain is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + AbortSASL and wait for + SASL_Status_Client_Failed before starting another attempt. + + + + + + The server or connection manager doesn't implement the given + SASL mechanism (choose one from + AvailableMechanisms, or abort + authentication if none of them are suitable), or doesn't allow + initial data to be sent (as indicated by + HasInitialData; call + StartMechanism instead). + + + + + + + + + The response data. + + + +

Send a response to the the last challenge received via + NewChallenge.

+ + + + + + Either the state is not In_Progress, or no challenge has been + received yet, or you have already responded to the last challenge. + + + + + + + + +

If the channel's status is SASL_Status_Server_Succeeded, + this method confirms successful authentication and advances + the status of the channel to SASL_Status_Succeeded.

+ +

If the channel's status is SASL_Status_In_Progress, calling this + method indicates that the last + NewChallenge signal was in fact + additional data sent after a successful SASL negotiation, and + declares that from the client's point of view, authentication + was successful. This advances the state of the channel to + SASL_Status_Client_Accepted.

+ +

In mechanisms where the server authenticates itself to the client, + calling this method indicates that the client considers this to have + been successful. In the case of ServerAuthentication + channels, this means that the connection manager MAY continue to + connect, and MAY advance the Connection.Status to Connected.

+ + + + + + Either the state is neither In_Progress nor Server_Succeeded, or no + challenge has been received yet, or you have already responded to + the last challenge. + + + + + + + + + + Reason for abort. + + + + + Debug message for abort. + + + +

Abort the current authentication try.

+ +

If the current status is SASL_Status_Server_Failed or + SASL_Status_Client_Failed, this method returns successfully, but has + no further effect. If the current status is SASL_Status_Succeeded + or SASL_Status_Client_Accepted then NotAvailable is raised. + Otherwise, it changes the channel's state to + SASL_Status_Client_Failed, with an appropriate error name and + reason code.

+ + + + + The current state is either Succeeded or Client_Accepted. + + + + + + + + Emitted when the status of the channel changes. + + + + The new value of SASLStatus. + + + + + The new value of SASLError. + + + + + The new value of SASLErrorDetails. + + + + + + +

Emitted when a new challenge is received from the server, or when + a message indicating successful authentication and containing + additional data is received from the server.

+ +

When the channel's handler is ready to proceed, it should respond + to the challenge by calling Respond, + or respond to the additional data by calling + AcceptSASL. Alternatively, it may call + AbortSASL to abort authentication.

+ + + + The challenge data or additional data from the server. + + + + + + +

A reason why SASL authentication was aborted by the client.

+ + + + + The server sent an invalid challenge or data. + + + + + The user aborted the authentication. + + + + + + + + The initial state. The Handler SHOULD either + call AbortSASL, or connect to the + NewChallenge signal then call + StartMechanism or + StartMechanismWithData. + + + + + The challenge/response exchange is in progress. The Handler SHOULD + call either Respond or + AcceptSASL exactly once per emission + of NewChallenge, or call + AbortSASL at any time. + + + + + The server has indicated successful authentication, and the + connection manager is waiting for confirmation from the Handler. + The Handler must call either AcceptSASL or + AbortSASL to indicate whether it + considers authentication to have been successful. + + + + + The Handler has indicated successful authentication, and the + connection manager is waiting for confirmation from the server. + The state will progress to either Succeeded or Server_Failed when + confirmation is received. + + + + + Everyone is happy (the server sent success, and the client has called + AcceptSASL). Connection to the server + will proceed as soon as this state is reached. The Handler SHOULD + call Close + to close the channel. + + + + + The server has indicated an authentication failure. + If CanTryAgain is true, + the client may try to authenticate again, by calling + StartMechanism or + StartMechanismWithData again. + Otherwise, it should give up completely, by calling Close + on the channel. + + + + + The client has indicated an authentication failure. The + possible actions are the same as for Server_Failed. + + + + + + + diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml new file mode 100644 index 0000000..4cfe3f2 --- /dev/null +++ b/spec/Channel_Interface_SMS.xml @@ -0,0 +1,179 @@ + + + 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.

+ +

The presence of this interface on a channel does not imply that + messages will be delivered via SMS.

+ +

This interface MAY appear in the + Interfaces property + of channels where SMSChannel would be + immutable and false. It SHOULD appear on channels where + SMSChannel is immutable and true, and + also on channels where SMSChannel is + mutable (i.e. channels that might fall back to sending SMS at any + time, such as on MSN).

+ +

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.

+ + + + + + + +

If TRUE, messages sent and received on this channel are transmitted + via SMS.

+ +

If this property is included in the channel request, the + Connection Manager MUST return an appropriate channel (i.e. if TRUE + the channel must be for SMSes, if FALSE it must not), or else fail + to provide the requested channel with the + NotCapable + error.

+ +

For example, to explicitly request an SMS channel to a contact. + You might construct a channel request like:

+ + 
{
+  Channel.Type: Channel.Type.Text,
+  Channel.TargetHandleType: Handle_Type_Contact,
+  Channel.TargetID: escher.cat,
+  Channel.Interface.SMS.SMSChannel: True,
+}
+ + + Some protocols allow us to send SMSes to a remote contact, without + knowing the phone number to which those SMSes will be sent. This + provides a mechanism to request such channels. + + +

If this property is not included in the channel request, the + Connection Manager MAY return an SMS channel if that is the most + appropriate medium (i.e. if the channel target is a phone + number).

+ + + To some types of identifiers (i.e. phone numbers) it only makes + sense to return an SMS channel, this is what happens currently with + telepathy-ring. We don't want to break this behaviour when we are + not explicit about the type of channel we want. Alternatively, for + protocols where there is an SMS fallback for IM messages, it's + possible that we don't care what sort of channel we get, and simply + want notification of the transport. + + +

Some protocols have a fallback to deliver IM messages via SMS. + On these protocols, the Connection Manager SHOULD set the property + value as appropriate, and notify its change with + SMSChannelChanged.

+ + + Protocols such as MSN can fall back to delivering IM messages via + SMS. Where possible we want clients to be able to inform the user + that their messages are going to be redirected to the remote + contact's phone. + + + + + + + + + The new value for SMSChannel. + + + + This signal indicates a change in the + SMSChannel property. + + + + diff --git a/spec/Channel_Interface_Securable.xml b/spec/Channel_Interface_Securable.xml new file mode 100644 index 0000000..d9d9713 --- /dev/null +++ b/spec/Channel_Interface_Securable.xml @@ -0,0 +1,78 @@ + + + Copyright (C) 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 stable API + + + +

This interface exists to expose security information about + Channels. The two + properties are sometimes immutable and can be used to make + decisions on how cautious to be about transferring sensitive + data. The special case of ServerAuthentication + channels is one example of where the two properties are + immutable.

+ +

For example, clients MAY use these properties to decide + whether the PLAIN mechanism is acceptable for a + SASLAuthentication + channel.

+ + + + +

True if this channel occurs over an encrypted + connection. This does not imply that steps + have been taken to avoid man-in-the-middle attacks.

+ + +

For future support for RFC 5056 Channel + Binding it is desirable to be able to use some SASL + mechanisms over an encrypted connection to an unverified peer, + which can prove that it is the desired destination during + the SASL negotiation.

+ + + + + + +

True if this channel occurs over a connection that is + protected against tampering, and has been verified to be with + the desired destination: for instance, one where TLS was + previously negotiated, and the TLS certificate has been + verified against a configured certificate authority or + accepted by the user.

+ + + + + + diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml new file mode 100644 index 0000000..787397b --- /dev/null +++ b/spec/Channel_Interface_Service_Point.xml @@ -0,0 +1,86 @@ + + + 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.

+ + + (as stable API) + + +

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 a service point, the CM MUST set the + Service_Point_Type field to None; for instance, + this will be the case for ordinary calls. + + + + + +

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_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml new file mode 100644 index 0000000..760c134 --- /dev/null +++ b/spec/Channel_Interface_Splittable.xml @@ -0,0 +1,71 @@ + + + Copyright © 2009 Collabora Limited + 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 channels that can be made conceptually part of a + Conference, and can then be detached from that + conference.

+ + +

This interface addresses part of freedesktop.org bug + #24906 (GSM-compatible conference calls). GSM is currently + the only protocol known to implement this; PBXs might implement + it too.

+ + + + + +

Request that this channel is removed from any + Conference of which it is a part.

+ +

This implies that the media streams within the conference are put on + hold and the media streams within the member channel leaving the + conference are unheld.

+ + + + + + This channel isn't in a conference. + + + + + This channel is in a conference but can't currently be split away + from it. + + + + + + + diff --git a/spec/Channel_Interface_Transfer.xml b/spec/Channel_Interface_Transfer.xml new file mode 100644 index 0000000..02591c1 --- /dev/null +++ b/spec/Channel_Interface_Transfer.xml @@ -0,0 +1,53 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + + The handle of the member to transfer + + + + + The handle of the destination contact + + + + Request that the given channel member instead connects to a different + contact ID. + + + + + + + + + + + An interface for channels where you may request that one of the members + connects to somewhere else instead. + + + + diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml new file mode 100644 index 0000000..858a15d --- /dev/null +++ b/spec/Channel_Interface_Tube.xml @@ -0,0 +1,258 @@ + + + Copyright © 2008-2009 Collabora Limited + 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. + + + + +

A tube is a mechanism for arbitrary data transfer between + two or more IM users, used to allow applications on the users' + systems to communicate without having to establish network + connections themselves. Currently, two types of tube exist: + Channel.Type.DBusTube and + Channel.Type.StreamTube. This interface contains + the properties, signals and methods common to both types of tube; + you can only create channels of a specific tube type, not of this + type. A tube channel contains exactly one tube; if you need several + tubes, you have to create several tube channels.

+ +

Tube channels can be requested for Handle_Type + Contact (for 1-1 communication) or Room (to communicate with others in + the room simultaneously).

+ +

As an exception to the usual handling of capabilities, connection managers + for protocols with capability discovery (such as XMPP) SHOULD advertise the + capability representing each Tube type that they support + (Channel.Type.DBusTube and/or + Channel.Type.StreamTube) + even if no client has indicated via + UpdateCapabilities + that such a tube is supported. They SHOULD also allow clients to offer tubes with any + Service or + ServiceName + to any contact which supports the corresponding tube capability.

+ + +

This lowers the barrier to entry for those writing new tube + applications, and preserves interoperability with older versions of + the Telepathy stack which did not support rich capabilities.

+ + + + + +

Each tube has a dictionary of arbitrary parameters. Parameters are + commonly used to bootstrap legacy protocols where you can't + negotiate parameters in-band. The allowable keys, + types and values are defined by the service, but connection managers + must support the value being a string (D-Bus type 's'), + array of bytes (D-Bus type 'ay'), unsigned integer (D-Bus + type 'u'), integer (D-Bus type 'i') and boolean + (D-Bus type 'b').

+ +

When the tube is offered, the parameters are transmitted with the + offer and appear as a property of the incoming tube for other + participants.

+ +

For example, a stream tube for Service + "smb" (Server Message Block over TCP/IP) might + use the following properties, as defined in DNS SRV (RFC 2782) + Service Types:

+ + 
+{ 'u': 'some-username',
+  'p': 'top-secret-password',
+  'path': '/etc/passwd',
+}
+ +

When requesting a tube with + CreateChannel, + this property MUST NOT be included in the request; instead, it is set + when StreamTube.Offer + or DBusTube.Offer + (as appropriate) is called. Its value is undefined until the tube is + offered; once set, its value MUST NOT change.

+ +

When receiving an incoming tube, this property is immutable and so advertised in the + NewChannels + signal.

+ + + + + +

State of the tube in this channel.

+ +

When requesting a tube with + CreateChannel, + this property MUST NOT be included in the request.

+ + + + + + + The initiator offered the tube. The tube is waiting to be + accepted/closed locally. If the client accepts the tube, the tube's + state will be Open. + + + + + The tube is waiting to be accepted/closed remotely. If the + recipient accepts the tube, the tube's state will be Open. + + + + + The initiator offered the tube and the recipient accepted it. The + tube is open for traffic. The tube's state stays in this state until + it is closed. + + + + + The tube channel has been requested but the tube is not yet offered. + The client should offer the tube to the recipient and the tube's + state will be Remote_Pending. The method used to offer the tube + depends on the tube type. + + + + + + + Emitted when the state of the tube channel changes. Valid state + transitions are documented with Tube_Channel_State. + + + + The new state of the tube. + + + + + + + + A Unix socket. The address variant contains a byte-array, signature 'ay', + containing the path of the socket. + + + + + + An abstract Unix socket. The address variant contains a byte-array, + signature 'ay', containing the path of the socket including the + leading null byte. + + + + + + An IPv4 socket. The address variant contains a Socket_Address_IPv4, + i.e. a structure with signature (sq) + in which the string is an IPv4 dotted-quad address literal + (and must not be a DNS name), while the 16-bit unsigned integer is + the port number. + + + + + + An IPv6 socket. The address variant contains a Socket_Address_IPv6, + i.e. a structure with signature (sq) + in which the string is an IPv6 address literal as specified in + RFC2373 (and must not be a DNS name), while the 16-bit unsigned + integer is the port number. + + + + + + + + + The IP or Unix socket can be accessed by any local user (e.g. + a Unix socket that accepts all local connections, or an IP socket + listening on 127.0.0.1 (or ::1) or rejecting connections not from + that address). The associated variant must be ignored. + + + + + May only be used on IP sockets. The associated variant must contain + a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the string form of an IP address of the appropriate + version, and a port number. The socket can only be accessed if the + connecting process has that address and port number; all other + connections will be rejected. + + + + This has never been implemented. + If you want to share a service to your whole LAN, Telepathy is + not the way to do it. + + May only be used on IP sockets. The associated variant must contain + a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with + signature (sy), containing the string form of an + IP address of the appropriate version, and a prefix length "n". + The socket can only be accessed if the first n bits of the + connecting address match the first n bits of the given address. + + + + +

May only be used on UNIX sockets. + The connecting process must send a byte when + it first connects, which is not considered to be part of the data + stream. If the operating system uses sendmsg() with SCM_CREDS or + SCM_CREDENTIALS to pass credentials over sockets, the connecting + process must do so if possible; if not, it must still send the + byte.

+ +

The listening process will disconnect the connection unless it + can determine by OS-specific means that the connecting process + has the same user ID as the listening process.

+ +

The associated variant must be ignored.

+ + + + + + + + diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml new file mode 100644 index 0000000..1a9c397 --- /dev/null +++ b/spec/Channel_Request.xml @@ -0,0 +1,300 @@ + + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + +

A channel request is an object in the ChannelDispatcher representing + an ongoing request for some channels to be created or found. There + can be any number of ChannelRequest objects at the same time.

+ +

Its well-known bus name is the same as that of the ChannelDispatcher, + "org.freedesktop.Telepathy.ChannelDispatcher".

+ + +

See + ChannelDispatcher.CreateChannel + for rationale for ChannelRequest being a separate object.

+ + +

A channel request can be cancelled by any client (not just the one + that requested it). This means that the ChannelDispatcher will + Close + the resulting channel, or refrain from requesting it at all, rather + than dispatching it to a handler.

+ + + + + The Account + on which this request was made. This property cannot change. + + + + + +

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

+ +

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

+ + + + + +

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.

+ +

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

+ + + + + +

An array of dictionaries containing desirable properties for + the channel or channels to be created.

+ + +

This is an array so that we could add a CreateChannels method in + future without redefining the API of ChannelRequest.

+ + +

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

+ + + + + + A list of the extra interfaces provided by this channel request. + This property cannot change. + + + + + +

Proceed with the channel request.

+ + +

The client that created this object calls this method + when it has connected signal handlers for + Succeeded and + Failed.

+ + +

Clients other than the client which created the ChannelRequest + MUST NOT call this method.

+ +

This method SHOULD return immediately; on success, the request + might still fail, but this will be indicated asynchronously + by the Failed signal.

+ +

Proceed cannot fail, unless clients have got the life-cycle + of a ChannelRequest seriously wrong (e.g. a client calls this + method twice, or a client that did not create the ChannelRequest + calls this method). If it fails, clients SHOULD assume that the + whole ChannelRequest has become useless.

+ + + + + + This method has already been called, so it is no longer + available. Stop calling it. + + + + + + + +

Cancel the channel request. The precise effect depends on the + current progress of the request.

+ +

If the connection manager has not already been asked to create + a channel, then Failed is emitted + immediately, and the channel request is removed.

+ +

If the connection manager has already been asked to create a + channel but has not produced one yet (e.g. if Connection.Interface.Requests.CreateChannel + has been called, but has not yet returned), then the + ChannelDispatcher will remember that the request has been cancelled. + When the channel appears, it will be closed (if it was newly + created and can be closed), and will not be dispatched to a + handler.

+ +

If the connection manager has already returned a channel, but the + channel has not yet been dispatched to a handler + then the channel dispatcher will not dispatch that + channel to a handler. If the channel was newly created for this + request, the channel dispatcher will close it with Close; + otherwise, the channel dispatcher will ignore it. In either case, + Failed will be emitted when processing + has been completed.

+ +

If Failed is emitted in response to + this method, the error SHOULD be + org.freedesktop.Telepathy.Error.Cancelled.

+ +

If the channel has already been dispatched to a handler, then + it's too late to call this method, and the channel request will + no longer exist.

+ + + + + +

The channel request has failed. It is no longer present, + and further methods must not be called on it.

+ + + + +

The name of a D-Bus error. This can come from various sources, + including the error raised by CreateChannel, + or an error generated + to represent failure to establish the Connection.

+ + + + + + If the first argument of the D-Bus error message was a string, + that string. Otherwise, an empty string. + + + + + + +

The channel request has succeeded. It is no longer present, + and further methods must not be called on it.

+ + + + + + +

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. Clients SHOULD namespace hint names by having them + start with a reversed domain name, in the same way as D-Bus + interface names.

+ + 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 does not currently interpret any of these + hints: they are solely for communication between cooperating + clients. If hints that do affect the channel dispatcher are added in + future, their names will start with an appropriate reversed domain + name (e.g. org.freedesktop.Telepathy for hints defined + by this specification, or an appropriate vendor name for third-party + plugins).

+ +

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.

+ + + + + + +

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

+ +

This signal MUST be emitted if the + ChannelDispatcher's + SupportsRequestHints + property is true. If supported, it MUST be emitted before + the Succeeded signal.

+ + + + +

The Connection owning the channel.

+ + + + + +

A subset of the Connection's properties, currently unused. + This parameter may be used in future.

+ + + + + +

The channel which has been created.

+ + + + + +

The same immutable properties of the Channel that would appear + in a NewChannels signal.

+ + + + + + + + diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml new file mode 100644 index 0000000..039c1f9 --- /dev/null +++ b/spec/Channel_Type_Call.xml @@ -0,0 +1,1429 @@ + + + Copyright © 2009-2010 Collabora Limited + Copyright © 2009-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 1) + + + +

A channel type for making audio and video calls. Call + channels supersede the old StreamedMedia + channel type. Call channels are much more flexible than its + predecessor and allow more than two participants.

+ +

Handlers are advised against executing all the media + signalling, codec and candidate negotiation themselves but + instead use a helper library such as telepathy-farsight + which when given a new Call channel will set up the + transports and codecs and create GStreamer pads which + can be added to the handler UI. This is useful as it means + the handler does not have to worry how exactly the + connection between the call participants is being made.

+ +

The TargetHandle and + TargetID + properties in a Call channel refer to the contact that the + user initially called, or which contact initially called the + user. Even in a conference call, where there are multiple + contacts in the call, these properties refer to the + initial contact, who might have left the conference since + then. As a result, handlers should not rely on these + properties.

+ +

Contents

+ +

Content.DRAFT + objects represent the actual media that forms the Call (for + example an audio content and a video content). Calls always + have one or more Content objects associated with them. As a + result, a new Call channel request MUST have either + InitialAudio=True, or + InitialVideo=True, or both, + as the Requestable Channel Classes will document.

+ +

Content.DRAFT objects have + one or more stream associated with them. More information on + these streams and how to maniuplate them can be found on the + Content.DRAFT + interface page.

+ +

Outgoing calls

+ +

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

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

As always, TargetHandle may be used + in place of + TargetID + if the contact's handle is already known. To make an audio + and video call, the handler should also specify + InitialVideo The + connection manager SHOULD return a channel whose immutable + properties contain the local user as the InitiatorHandle, the + remote contact as the TargetHandle, + Requested = + True (indicating the call is outgoing).

+ +

After a new Call channel is requested, the + CallState property will be + Call_State_Pending_Initiator. As the local + user is the initiator, the call must be accepted by the handler + by calling the Accept method. + At this point, CallState changes + to Call_State_Pending_Receiver which signifies + that the call is ringing, waiting for the remote contact to + accept the call. All changes to + CallState property are signalled + using the CallStateChanged + signal.

+ +

When the call is accepted by the remote contact, the + CallStateChanged signal fires + again to show that CallState = + Call_State_Accepted.

+ +

At this point telepathy-farsight + will signal that a pad is available for the handler to show + in the user interface.

+ +
Missed calls
+ +

If the remote contact does not accept the call in time, then + the call can be terminated by the server. Note that this only + happens in some protocols. Most XMPP clients, for example, do + not do this and rely on the call initiator terminating the call. + A missed call is shown in a Call channel by the + CallState property changing to + Call_State_Ended, and the + CallStateReason property changing + to (remote contact, + Call_State_Change_Reason_No_Answer, "").

+ +
Rejected calls
+ +

If the remote contact decides he or she does not feel like + talking to the local user, he or she can reject his or her + incoming call. This will be shown in the Call channel by + CallState changing to + Call_State_Ended and the + CallStateReason property + changing to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Incoming calls

+ +

When an incoming call occurs, something like the following + NewChannels + signal will occur:

+ +
+ 
+NewChannels([
+  /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
+  {
+    ...ChannelType: ...Call.DRAFT,
+    ...TargetHandleType: Contact,
+    ...TargetID: 'foo@example.com',
+    ...TargetHandle: 42,
+    ...Requested: False,
+    ...InitialAudio: True,
+    ...InitialVideo: True,
+    ...InitialAudioName: "audio",
+    ...InitialVideoName: "video",
+    ...MutableContents: True,
+  }])
+ +

The InitialAudio and + InitialVideo properties show that + the call has been started with two contents: one for audio + streaming and one for video streaming. The + InitialAudioName and + InitialVideoName properties also + show that the aforementioned audio and video contents have names + "audio" and "video".

+ +

Once the handler has notified the local user that there is an + incoming call waiting for acceptance, the handler should call + SetRinging to let the CM know. + The new channel should also be given to telepathy-farsight to + work out how the two participants will connect together. + telepathy-farsight will call the appropriate methods on the call's + Content.DRAFTs + to negotiate codecs and transports.

+ +

To pick up the call, the handler should call + Accept. The + CallState property changes to + Call_State_Accepted and once media is + being transferred, telepathy-farsight will notify the + handler of a new pad to be shown to the local user in the + UI

+ +

To reject the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and the + CallStateReason property will + change to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Ongoing calls

+ +
Adding and removing contents
+ +

When a call is open, new contents can be added as long as the + CM supports it. The + MutableContents property will let + the handler know whether further contents can be added or + existing contents removed. An example of this is starting a + voice call between a contact and then adding a video content. + To do this, the should call + AddContent like this:

+ +
+ 
AddContent("video",
+           Media_Stream_Type_Video)
+
+ +

Assuming no errors, the new video content will be added to + the call. telepathy-farsight will pick up the new content and + perform the transport and codec negotiation automatically. + telpathy-farsight will signal when the video is ready to + show in the handler's user interface.

+ +

A similar method is used for removing contents from a call, + except that the Remove method + is on the Content.DRAFT object.

+ +
Ending the call
+ +

To end the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Cancelled").

+ +

If the other participant hangs up first then the + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated").

+ +

Multi-party calls

+ + [TODO] + +

Call states

+ +

There are many combinations of the + CallState and + CallStateReason properties which + mean different things. Here is a table to try to make these + meanings clearer:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RequestedCallStateCallStateReasonMeaning
ActorReasonDBus_Reason
TrueCall_State_Pending_InitiatorSelf handleCall_State_Change_Reason_User_Requested""The outgoing call channel is waiting for the local user to call Accept.
TrueCall_State_Pending_ReceiverSelf handleCall_State_Change_Reason_User_Requested""The outgoing call is waiting for the remote contact to pick up the call.
FalseCall_State_Pending_Receiver0Call_State_Change_Reason_Unknown""The incoming call is waiting for the local user to call Accept on the call.
TrueCall_State_AcceptedRemote contact handleCall_State_Change_Reason_User_Requested""The remote contact accepted the outgoing call.
FalseCall_State_AcceptedSelf handleCall_State_Change_Reason_User_Requested""The local user accepted the incoming call.
True or FalseCall_State_EndedSelf handleCall_State_Change_Reason_User_RequestedCancelledThe local user hung up the incoming or outgoing call.
True or FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedTerminatedThe remote contact hung up the incoming or outgoing call.
TrueCall_State_EndedRemote contact handleCall_State_Change_Reason_No_Answer""The outgoing call was not picked up and the call ended.
FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedPickedUpElsewhereThe incoming call was ended because it was picked up elsewhere.
+ +

Requestable channel classes

+ +

The RequestableChannelClasses + for Call.DRAFT channels + can be:

+ +
+ 
+[( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialVideo: True
+          },
+  Allowed = [ ...InitialVideoName,
+              ...InitialAudio,
+              ...InitialAudioName
+            ]
+),
+( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialAudio: True
+          },
+  Allowed = [ ...InitialAudioName,
+              ...InitialVideo,
+              ...InitialVideoName
+            ]
+)]
+ +

Clients aren't allowed to make outgoing calls that have + neither initial audio nor initial video. Clearly, CMs + which don't support video should leave out the first class and + omit InitialVideo from the second + class, and vice versa for CMs without audio support.

+ +

Handlers should not close Call.DRAFT channels + without first calling Hangup on + the channel. If a Call handler crashes, the ChannelDispatcher will call + Close on the + channel which SHOULD also imply a call to + Hangup(Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated", "") before + actually closing the channel.

+ + + + + renamed from Ringing + +

Indicate that the local user has been alerted about the incoming + call.

+ +

This method is only useful if the + channel's Requested + property is False, and + the CallState is + Call_State_Pending_Receiver (an incoming + call waiting on the local user to pick up). While this is + the case, this method SHOULD change the + CallFlags to include + Call_Flags_Locally_Ringing, and notify the + remote contact that the local user has been alerted (if the + protocol implements this); repeated calls to this method + SHOULD succeed, but have no further effect.

+ +

In all other states, this method SHOULD fail with the error + NotAvailable.

+ + + + + + The call was Requested, so ringing does not make sense. + + + + + The call is no longer in state + Call_State_Pending_Receiver. + + + + + + + +

For incoming calls in state + Call_State_Pending_Receiver, accept the + incoming call; this changes the + CallState to + Call_State_Accepted.

+ +

For outgoing calls in state + Call_State_Pending_Initiator, actually + call the remote contact; this changes the + CallState to + Call_State_Pending_Receiver.

+ +

Otherwise, this method SHOULD fail with the error NotAvailable.

+ +

This method should be called exactly once per Call, by whatever + client (user interface) is handling the channel.

+ +

When this method is called, for each Content.DRAFT whose + Disposition is + Call_Content_Disposition_Initial, any + streams where the LocalSendingState + is Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending(True) had been called.

+ + + + + + The call is not in one of the states where this method makes sense. + + + + + + + + Request that the call is ended. All contents will be removed + from the Call so that the + Contents property will be the + empty list. + + + + + A generic hangup reason. + + + + + + A more specific reason for the call hangup, if one is available, or + an empty string otherwise. + + + + + + A human-readable message to be sent to the remote contact(s). + + + XMPP Jingle allows calls to be terminated with a human-readable + message. + + + + + + + + The call has already been ended. + + + + + + + + Request that a new Content.DRAFT of type + Content_Type is added to the Call. Handlers should check the + value of the MutableContents + property before trying to add another content as it might not + be allowed. + + + +

The suggested name of the content to add.

+ + + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. + + +

If there is already a content with the same name as this + property then a sensible suffix should be added. For example, + if this argument is "audio" but a content of the same name + already exists, a sensible suffix such as " (1)" is appended + to name the new content "audio (1)". A further content with the + name "audio" would then be named "audio (2)".

+ + + + + + The media stream type of the content to be added to the + call. + + + + + Path to the newly-created Call.Content.DRAFT object. + + + + + + + The media stream type given is invalid. + + + + + The media stream type requested is not implemented by the + CM. + + + + + The content type requested cannot be added to this + call. Examples of why this might be the case include + because a second video stream cannot be added, or a + content cannot be added when the content set isn't + mutable. + + + + + + + +

Emitted when a new Content.DRAFT is added to the call.

+ + + + Path to the newly-created Content.DRAFT object. + + + + + + +

Emitted when a Content.DRAFT is removed from the call.

+ + + + The Content.DRAFT which was removed. + + + + + + +

The list of Content.DRAFT objects that + are part of this call. Change notification is via the + ContentAdded and + ContentRemoved signals. +

+ + + + + +

The state of a call, as a whole.

+ +

The allowed transitions are:

+ +
    +
  • Pending_Initiator → Pending_Receiver (for outgoing calls, + when Accept is called)
    • +
  • Pending_Receiver → Accepted (for incoming calls, when + Accept is called; for outgoing + calls to a contact, when the remote contact accepts the call; + for joining a conference call, when the local user successfully + joins the conference)
    • +
  • Accepted → Pending_Receiver (when transferred to another + contact)
    • +
  • any state → Ended (when the call is terminated normally, or + when an error occurs)
    • +
+ +

Clients MAY consider unknown values from this enum to be an + error - additional values will not be defined after the Call + specification is declared to be stable.

+ + + + + The call state is not known. This call state MUST NOT appear as a + value of the CallState property, but + MAY be used by client code to represent calls whose state is as yet + unknown. + + + + + The initiator of the call hasn't accepted the call yet. This state + only makes sense for outgoing calls, where it means that the local + user has not yet sent any signalling messages to the remote user(s), + and will not do so until Accept is + called. + + + + + The receiver (the contact being called) hasn't accepted the call yet. + + + + + The contact being called has accepted the call. + + + + + The call has ended, either via normal termination or an error. + + + + + + + A set of flags representing the status of the call as a whole, + providing more specific information than the + CallState. Many of these flags only make + sense in a particular state. + + + + + The local contact has been alerted about the call but has not + responded; if possible, the remote contact(s) have been informed of + this fact. This flag only makes sense on incoming calls in + state Call_State_Pending_Receiver. It SHOULD + be set when SetRinging is + called successfully, and unset when the state changes. + + + + + + The contact is temporarily unavailable, and the call has been placed + in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). + This flag only makes sense on outgoing 1-1 calls in + state Call_State_Pending_Receiver. It SHOULD be + set or unset according to informational messages from other + contacts. + + + + + + The call has been put on hold by the local user, e.g. using + the Hold interface. This flag SHOULD only be set + if there is at least one Content, and all Contents are + locally held; it makes sense on calls in state + Call_State_Pending_Receiver + or Call_State_Accepted. + + + Otherwise, in transient situations where some but not all contents + are on hold, UIs would falsely indicate that the call as a whole + is on hold, which could lead to the user saying something they'll + regret, while under the impression that the other contacts can't + hear them! + + + + + + + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. This flag only makes sense on outgoing calls, in state + Call_State_Pending_Receiver or + Call_State_Accepted. It SHOULD be set or unset + according to informational messages from other contacts. + + + + + + Progress has been made in placing the outgoing call, but the + contact may not have been made aware of the call yet + (so the Ringing state is not appropriate). This corresponds to SIP's + status code 183 Session Progress, and could be used when the + outgoing call has reached a gateway, for instance. + This flag only makes sense on outgoing calls in state + Call_State_Pending_Receiver, and SHOULD be set + or unset according to informational messages from servers, gateways + and other infrastructure. + + + + + + This flag only occurs when the CallState is Ended. The call with + this flag set has ended, but not all resources corresponding to the + call have been freed yet. + + Depending on the protocol there might be some audible feedback while + the clearing flag is set. + + + In calls following the ITU-T Q.931 standard there is a period of + time between the call ending and the underlying channel being + completely free for re-use. + + + + + + + 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. + + + + + + +

A map used to provide optional extensible details for the + CallState, + CallFlags and/or + CallStateReason.

+ +

Well-known keys and their corresponding value types include:

+ +
+
hangup-message - s
+
An optional human-readable message sent when the call was ended, + corresponding to the Message argument to the + Hangup method. This is only + applicable when the call state is Call_State_Ended. + + XMPP Jingle can send such messages. + +
+ +
queue-message - s
+
An optional human-readable message sent when the local contact + is being held in a queue. This is only applicable when + Call_Flags_Queued is in the call flags. + + SIP 182 notifications can have human-readable messages attached. + +
+ +
debug-message - s
+
A message giving further details of any error indicated by the + CallStateReason. This will not + normally be localized or suitable for display to users, and is only + applicable when the call state is + Call_State_Ended.
+
+ + + + + +

The current high-level state of this call. The + CallFlags provide additional + information, and the CallStateReason + and CallStateDetails explain the + reason for the current values for those properties.

+ +

Note that when in a conference call, this property is + purely to show your state in joining the call. The receiver + (or remote contact) in this context is the conference server + itself. The property does not change when other call members' + states change.

+ +

Clients MAY consider unknown values in this property to be an + error.

+ + + + + +

Flags representing the status of the call as a whole, + providing more specific information than the + CallState.

+ +

Clients are expected to ignore unknown flags in this property, + without error.

+ +

When an ongoing call is active and not on hold or has any + other problems, this property will be 0.

+ + + + + + A simple representation of the reason for a change in the call's + state, which may be used by simple clients, or used as a fallback + when the DBus_Reason member of a Call_State_Reason + struct is not understood. + + + + + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + + + + + +

The change was requested by the contact indicated by the Actor + member of a Call_State_Reason struct.

+ +

If the Actor is the local user, the DBus_Reason SHOULD be the + empty string.

+ +

If the Actor is a remote user, the DBus_Reason SHOULD be the empty + string if the call was terminated normally, but MAY be a non-empty + error name to indicate error-like call termination reasons (call + rejected as busy, kicked from a conference by a moderator, etc.).

+ + + + + +

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.

+ + + + + + +

The CallState changed from + Call_State_Pending_Receiver to + Call_State_Ended because the initiator + ended the call before the receiver accepted it. With an + incoming call this state change reason signifies a missed + call.

+ + + + + + +

A description of the reason for a change to the + CallState and/or + CallFlags.

+ + + + + The contact responsible for the change, or 0 if no contact was + responsible. + + + + + + The reason, chosen from a limited set of possibilities defined by + the Telepathy specification. If + Call_State_Change_Reason_User_Requested then + the Actor member will dictate whether it was the local user or + a remote contact responsible. + + + + + +

A specific reason for the change, which may be a D-Bus error in + the Telepathy namespace, a D-Bus error in any other namespace + (for implementation-specific errors), or the empty string to + indicate that the state change was not an error.

+ +

This SHOULD be an empty string for changes to any state other + than Ended.

+ +

The errors Cancelled and Terminated SHOULD NOT be used here; + an empty string SHOULD be used instead.

+ + +

Those error names are used to indicate normal call + termination by the local user or another user, respectively, + in contexts where a D-Bus error name must appear.

+ + + + + + + +

The reason for the last change to the + CallState and/or + CallFlags. The + CallStateDetails MAY provide additional + information.

+ + + + + +

Emitted when the state of the call as a whole changes.

+ +

This signal is emitted for any change in the properties + corresponding to its arguments, even if the other properties + referenced remain unchanged.

+ + + + + The new value of the CallState + property. + + + + + + The new value of the CallFlags + property. + + + + + + The new value of the CallStateReason + property. + + + + + + The new value of the CallStateDetails + property. + + + + + + +

If this property is True, all of the media streaming is done by some + mechanism outside the scope of Telepathy.

+ + +

A connection manager might be intended for a specialized hardware + device, which will take care of the audio streaming (e.g. + telepathy-yafono, which uses GSM hardware which does the actual + audio streaming for the call).

+ + +

If this is False, the handler is responsible for doing the actual + media streaming for at least some contents itself. Those contents + will have the Media.DRAFT interface, to communicate the necessary + information to a streaming implementation. Connection managers SHOULD + operate like this, if possible.

+ + +

Many connection managers (such as telepathy-gabble) only do the + call signalling, and expect the client to do the actual streaming + using something like + Farsight, to improve + latency and allow better UI integration.

+ + + + + + +

A set of flags representing the status of a remote contact in a + call.

+ +

It is protocol- and client-specific whether a particular contact + will ever have a particular flag set on them, and Telepathy clients + SHOULD NOT assume that a flag will ever be set.

+ + +

180 Ringing in SIP, and its equivalent in XMPP, are optional + informational messages, and implementations are not required + to send them. The same applies to the messages used to indicate + hold state.

+ + + + + +

The remote contact's client has told us that the contact has been + alerted about the call but has not responded.

+ + +

This is a flag per member, not a flag for the call as a whole, + because in Muji conference calls, you could invite someone and + have their state be "ringing" for a while.

+ + + + + + +

The call member has put this call on hold.

+ + +

This is a flag per member, not a flag for the call as a whole, + because in conference calls, any member could put the conference + on hold.

+ + + + + + + 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. + + + + + + A mapping from handles to their current state in the call. + + + + + + + + Emitted when the CallMembers property + changes in any way, either because contacts have been added to the + call, contacts have been removed from the call, or contacts' flags + have changed. + + + + + A map from members of the call to their new call member flags, + including at least the members who have been added to + CallMembers, and the members whose + flags have changed. + + + + + A list of members who have left the call, i.e. keys to be removed + from CallMembers. + + + + + + +

A mapping from the remote contacts that are part of this call to flags + describing their status. This mapping never has the local user's handle + as a key.

+ +

When the call ends, this property should be an empty list, + and notified with + CallMembersChanged

+ +

If the Call implements + Group and the Group members are + channel-specific handles, then this call SHOULD also use + channel-specific handles.

+ +

Anonymous members are exposed as channel-specific handles + with no owner.

+ + + + + +

If set on a requested channel, this indicates the transport that + should be used for this call. Where not applicable, this property + is defined to be Stream_Transport_Type_Unknown, + in particular, on CMs with hardware streaming.

+ + + When implementing a voip gateway one wants the outgoing leg of the + gatewayed to have the same transport as the incoming leg. This + property allows the gateway to request a Call with the right + transport from the CM. + + + + + + +

If set to True in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call AddContent.

+ +

If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.

+ +

If True on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.

+ +

If True on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + Contents).

+ +

The name of this new content can be decided by using the + InitialAudioName property.

+ +

Connection managers that support the ContactCapabilities + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = Call + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.

+ + +

Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.

+ + +

Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling UpdateCapabilities + (clients of a ChannelDispatcher + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their HandlerChannelFilter + properties):

+ +
    +
  • { ChannelType = Call }
    • +
  • { ChannelType = Call, InitialAudio = True } + if receiving calls with audio is supported
    • +
  • { ChannelType = Call, InitialVideo = True } + if receiving calls with video is supported
    • +
+ + +

Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.

+ + + + + + +

The same as InitialAudio, but for + a video stream. This property is immutable (cannot change).

+ +

In particular, note that if this property is False, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.

+ +

This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.

+ + + + + + +

If InitialAudio is set to + True, then this property will name the intial audio content + with the value of this property.

+ + +

Content names are meant to be significant, but if no name + can be given to initial audio content, then its name cannot + be meaningful or even localized.

+ + +

If this property is empty or missing from the channel + request and InitialAudio is True, then the CM must come up + with a sensible for the content, such as "audio".

+ +

If the protocol has no concept of stream names then this + property will not show up in the allowed properties list of + the Requestable Channel Classes for call channels.

+ + + + + + +

The same as + InitialAudioName, but for a + video stream created by setting + InitialVideo to True. This + property is immutable and so cannot change.

+ + + + + +

If True, a stream of a different content type can be added + after the Channel has been requested

+ +

If this property is missing, clients SHOULD assume that it is False, + and thus that the channel's streams cannot be changed once the call + has started.

+ +

If this property isn't present in the "allowed" set in any of the + Call entries contact capabilities, then user interfaces MAY choose to + show a separate "call" option for each class of call.

+ + +

For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + must be requested at the start of the call if video is desired. + User interfaces may use this pseudo-capability as a hint to + display separate "Audio call" and "Video call" buttons, rather + than a single "Call" button with the option to add and remove + video once the call has started for contacts without this flag. +

+ + + + + + +

This client supports audio calls.

+ + + + + +

This client supports video calls.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_GTalk_P2P.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_ICE.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_WLM_2009.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_SHM.

+ + + + + +

The client supports media streaming with H264 (etc.).

+ +

This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/subtype or video/subtype, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.

+ + +

For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + video/h264 on Call channels.

+ + +

For example, a client could advertise support for audio and video + calls using Speex, Theora and H264 by having five handler capability + tokens in its Capabilities + property:

+ +
    +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264
    • +
+ +

Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.

+ + +

This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.

+ + + + + + + diff --git a/spec/Channel_Type_Contact_List.xml b/spec/Channel_Type_Contact_List.xml new file mode 100644 index 0000000..5a0d333 --- /dev/null +++ b/spec/Channel_Type_Contact_List.xml @@ -0,0 +1,104 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + +

A channel type for representing a list of people on the server which is + not used for communication. This is intended for use with the interface + Channel.Interface.Group + for managing buddy lists and privacy lists + on the server. This channel type has no methods because all of the + functionality it represents is available via the group interface.

+ +

There are currently two types of contact list: + HANDLE_TYPE_LIST is a "magic" server-defined list, and + HANDLE_TYPE_GROUP is a user-defined contact group.

+ +

For server-defined lists like the subscribe list, singleton instances + of this channel type should be created by the connection manager at + connection time if the list exists on the server, or may be requested + by using the appropriate handle. These handles can be obtained using + RequestHandles + with a Handle_Type of HANDLE_TYPE_LIST and one of the + following identifiers:

+ +
    +
  • subscribe - the group of contacts for whom you receive presence
    • +
  • publish - the group of contacts who may receive your presence
    • +
  • hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence
    • +
  • allow - a group of contacts who may send you messages
    • +
  • deny - a group of contacts who may not send you messages
    • +
  • stored - on protocols where the user's contacts are stored, this + contact list contains all stored contacts regardless of subscription + status.
    • +
+ +

A contact can be in several server-defined lists. All lists are optional + to implement. If RequestHandles + or RequestChannel + for a particular contact list raises an error, this indicates that the + connection manager makes no particular statement about the list's contents; + clients MUST NOT consider this to be fatal.

+ +

If a client wants to list all of a user's contacts, it is appropriate to + use the union of the subscribe, publish and stored lists, including the + local and remote pending members.

+ +

For example in XMPP, contacts who have the subscription type "none", + "from", "to" and "both" can be respectively in the lists:

+ +
    +
  • "none": stored
    • +
  • "from": stored and publish
    • +
  • "to": stored and subscribe
    • +
  • "both": stored, publish and subscribe
    • +
+ +

These contact list channels may not be closed.

+ +

For user-defined contact groups, instances of this channel type should + be created by the connection manager at connection time for each group + that exists on the server. New, empty groups can be created by calling + RequestHandles + with a Handle_Type of HANDLE_TYPE_GROUP and with the + name set to the human-readable UTF-8 name of the group.

+ +

User-defined groups may be deleted by calling Close on the + channel, but only if + the group is already empty. Closing a channel to a non-empty group is + not allowed; its members must be set to the empty set first.

+ +

On some protocols (e.g. XMPP) empty groups are not represented on the + server, so disconnecting from the server and reconnecting might cause + empty groups to vanish.

+ + + + + diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml new file mode 100644 index 0000000..fefa77a --- /dev/null +++ b/spec/Channel_Type_Contact_Search.xml @@ -0,0 +1,462 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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 stable API. Changes from draft 2: + Contact_Search_Result_Map keys are now identifiers + rather than handles; consequently, the values need not include + x-telepathy-identifier. + + + +

A channel type for searching server-stored user directories. A new + channel should be requested by a client for each search attempt, and + closed when the search is completed or the required result has been + found. Channels of this type should have TargetHandleType + None (and hence TargetHandle 0 and + TargetID + ""). Requests for channels of this type need only + optionally specify the Server property + (if it is an allowed property in the connection's RequestableChannelClasses).

+ +

Before searching, the + AvailableSearchKeys property should be + inspected to determine the valid search keys which can be provided to + the Search method. A search request is + then started by providing some of these terms to the Search method, and + the SearchState will change from + Not_Started to In_Progress. As results are + returned by the server, the + SearchResultReceived signal is emitted + for each contact found; when the search is complete, the search state + will be set to Completed. If the search fails after Search + has been called, the state will change to Failed. A + running search can be cancelled by calling + Stop.

+ +

If the protocol supports limiting the number of results returned by a + search and subsequently requesting more results, after + Limit results have been received the + search state will be set to More_Available. Clients may + call More to request another + Limit results. If allowed by the + connection manager, clients may specify the "page size" by specifying + Limit when calling + CreateChannel. +

+ +

The client should call the channel's Close + method when it is finished with the channel.

+ +

Each channel can only be used for a single search; a new channel + should be requested for each subsequent search. Connection managers + MUST support multiple ContactSearch channels being open at once (even + to the same server, if applicable).

+ +

It does not make sense to request this channel type using EnsureChannel; + clients SHOULD request channels of this type using + CreateChannel + instead.

+ + +

A contact search channel that is already in use for a different + search isn't useful.

+ + + + + + The search has not started + + + The search is in progress + + + The search has paused, but more results can be retrieved + by calling More. + + + The search has been completed + + + The search has failed + + + + + + The current state of this search channel object. Change notification + is via SearchStateChanged. + + + + + + The new search state + + + + If the new state is Failed, the name of a D-Bus error + describing what went wrong. Otherwise, the empty string. + + + + +

Additional information about the state transition, which may + include the following well-known keys:

+ +
+
debug-message (s)
+
Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances
+
+ + +

This argument allows for future extensions. For instance, + if moving to state Failed because the server + rejected one of our search terms, we could define a key + that indicates which terms were invalid.

+ + + + +

Emitted when the SearchState property + changes. The implementation MUST NOT make transitions other than the + following:

+ +
    +
  • Not_Started → In_Progress
    • +
  • In_Progress → More_Available
    • +
  • More_Available → In_Progress
    • +
  • In_Progress → Completed
    • +
  • In_Progress → Failed
    • +
+ + + + + +

Any of the following search keys, with the indicated result for + the search:

+ +
+
The empty string
+
Search for the search term in some implementation-dependent + set of fields, using an implementation-dependent algorithm + (e.g. searching for each word mentioned) + + The "one big search box" approach to searching, as is familiar + from Google. The Sametime plugin to Pidgin appears to search in + this way. + +
+ +
A VCard_Field
+
Search for the search term in fields matching that name (for + instance, nickname would search nicknames, and + tel would search any available phone number, + regardless of its work/home/mobile/... status).
+ +
A VCard_Field followed by + ";" and a + VCard_Type_Parameter of the form + "type=..."
+
Search for the search term in fields of that name and type + only (for instance, tel;type=mobile).
+ +
x-telepathy-identifier
+
Search for contacts whose identifier in the IM protocol + matches the search term (e.g. contains it as a substring) + + Otherwise, starting a search by identifier would require the UI + to know the vCard field name corresponding to identifiers in + this protocol, which might be non-standard (like + x-jabber) or not exist at all. + +
+ +
x-gender
+
For the search term "male" or "female", search only for contacts + listed as male or female, respectively. The results for other + search terms are undefined; it is likely that contacts with + unspecified gender will only be matched if this search key + is omitted from the request. + + Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu + also supports limiting search results by gender. + +
+ +
x-n-family
+
Search for the search term in contacts' family names + (the first component of the vCard field n). + + Gadu-Gadu and TOC seem to support this mode of searching. + +
+ +
x-n-given
+
Search for the search term in contacts' given names + (the second component of the vCard field n). + + As for x-n-family. + +
+ +
x-online
+
For the search term "yes", search only for contacts who are + currently online. The results for other search terms are undefined. + Gadu-Gadu appears to support this. +
+ +
x-adr-locality
+
Search for the search term as a locality or city (the fourth + component of the vCard field adr). + + Gadu-Gadu and TOC appear to support this. + +
+
+ + + + + +

If supported by the protocol, the maximum number of results that + should be returned, where 0 represents no limit. If the + protocol does not support limiting results, this should be + 0.

+ +

For example, if the terms passed to + Search match Antonius, + Bridget and Charles and this property is + 2, the search service SHOULD only return Antonius + and Bridget.

+ +

This property SHOULD be requestable if and only if the protocol + supports specifying a limit; implementations SHOULD use + 0 as the default if possible, or a protocol-specific + sensible default otherwise.

+ + + + + + The set of search keys supported by this channel. Example values + include [""] (for protocols where several address fields are + implicitly searched) or ["x-n-given", "x-n-family", "nickname", + "email"] (for XMPP XEP-0055, without extensibility via Data Forms). + + + It can be in the NewChannels + signal for round-trip reduction. + + + + + + A map from search keys to search terms. + + + The search key to match against + + + + + + The term or terms to be searched for in the search key; depending on + the protocol and the server implementation, this may be matched by + exact or approximate equality, substring matching, word matching + or any other matching algorithm + + + + + + + + A dictionary mapping search key names to the desired values + + + + Send a request to start a search for contacts on this connection. This + may only be called while the SearchState + is Not_Started; a valid search request will cause the + SearchStateChanged signal to be emitted + with the state In_Progress. + + + + + The SearchState is no longer + Not_Started, so this method is no longer available. + + + + + The search terms included something this connection manager cannot + search for. + + + + + + + + + Request that a search in SearchState + More_Available move back to state In_Progress + and continue listing up to Limit more results. + + + + + The SearchState is not + More_Available. + + + + + + + +

Stop the current search. This may not be called while the + SearchState is Not_Started. If called + while the SearchState is In_Progress, + SearchStateChanged will be emitted, + with the state Failed and the error + org.freedesktop.Telepathy.Error.Cancelled.

+ +

Calling this method on a search in state Completed or Failed + succeeds, but has no effect.

+ + +

Specifying Stop to succeed when the search has finished means that + clients who call Stop just before receiving + SearchStateChanged don't have to + handle a useless error.

+ + +

Depending on the protocol, the connection manager may not be + able to prevent the server from sending further results after this + method returns; if this is the case, it MUST ignore any further + results.

+ + + + + The SearchState is Not_Started, so + this method is not yet available. + + + + + + + A map from contact identifier to search result, emitted in + the SearchResultReceived + signal. + + + + The identifier of a contact matching the search terms. + + + This is an identifier rather than a handle in case we make handles + immortal; see fd.o#23155 + and fd.o#13347 + comment 5. + + + + + + +

An array of fields representing information about this + contact, in the same format used in the ContactInfo + interface. It is possible that a separate call to RequestContactInfo + would return more information than this signal provides.

+ + + + + + + A mapping from contact identifier to an array of fields + representing information about this contact. + + + + Emitted when a some search results are received from the server. + This signal can be fired arbitrarily many times so clients MUST NOT + assume they'll get only one signal. + + + + + +

For protocols which support searching for contacts on multiple + servers with different DNS names (like XMPP), the DNS name of the + server being searched by this channel, e.g. + "characters.shakespeare.lit". Otherwise, the empty string.

+ + +

XEP 0055 defines a mechanism for XMPP clients to search services + of their choice for contacts, such as users.jabber.org (the "Jabber + User Directory").

+ + +

This property SHOULD be requestable if and only if the + protocol supports querying multiple different servers; + implementations SHOULD use a sensible default if possible if this + property is not specified in a channel request.

+ + +

This allows a client to perform searches on a protocol it knows + nothing about without requiring the user to guess a valid server's + hostname.

+ + + + + + + diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml new file mode 100644 index 0000000..9615763 --- /dev/null +++ b/spec/Channel_Type_DBus_Tube.xml @@ -0,0 +1,189 @@ + + + Copyright © 2008-2009 Collabora Limited + 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. + + + + + +

A D-Bus tube is an ordered reliable transport, for transporting D-Bus + traffic.

+ +

For each D-Bus tube, the connection manager listens on a D-Bus + server address, as detailed in the D-Bus specification. On this + address, it emulates a bus upon which each tube participant appears + as an endpoint.

+ +

The objects and interfaces which are expected to exist on the + emulated bus depend on the well-known name; typically, either the + participant who initiated the tube is expected to export the same + objects/interfaces that would be exported by a service of that name + on a bus, or all participants are expected to export those + objects/interfaces.

+ +

In a multi-user context (Handle_Type_Room) the tube behaves + like the D-Bus bus daemon, so participants can send each other + private messages, or can send broadcast messages which are + received by everyone in the tube (including themselves). + Each participant has a D-Bus unique name; connection managers + MUST prevent participants from sending messages with the wrong + sender unique name, and SHOULD attempt to avoid participants + receiving messages not intended for them.

+ +

In a 1-1 context (Handle_Type_Contact) the tube behaves like + a peer-to-peer D-Bus connection - arbitrary D-Bus messages with + any sender and/or destination can be sent by each participant, + and each participant receives all messages sent by the other + participant.

+ + + + + + Offers a D-Bus tube providing the service specified. + + + + The dictionary of arbitrary + Parameters + to send with the tube offer. + + + + + The access control the connection manager applies to the D-Bus socket. + + + + + The string describing the address of the private bus. The client + SHOULD NOT attempt to connect to the address until the tube is open. + + + + + + + The contact associated with this channel doesn't have tubes + capabilities. + + + + + + + + Accept a D-Bus tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeChannelStateChanged + signal is emitted. + + + + The access control the connection manager applies to the D-Bus socket. + + + + + The string describing the address of the private bus. The client + SHOULD NOT attempt to connect to the address until the tube is open. + + + + + + + Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a + participant opens or closes the tube. This provides change + notification for the DBusNames property. + + + + Array of handles and D-Bus names of new participants. + + + + + Array of handles of former participants. + + + + + + +

A string representing the service name that will be used over the + tube. It SHOULD be a well-known D-Bus service name, of the form + com.example.ServiceName.

+

When the tube is offered, the service name is transmitted to the + other end.

+

When requesting a channel with + CreateChannel, + this property MUST be included in the request.

+ + + + + + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping + between contact handles and their unique bus names on this tube. + For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty + dictionary. Change notification is via + DBusNamesChanged. + + + + + Represents the participants in a multi-user D-Bus tube, as + used by the DBusNames property and the + DBusNamesChanged signal. + + + The handle of a participant in this D-Bus tube. + + + + + That participant's unique name. + + + + + + +

A list of the access control types that are supported with this channel. + Note that only Socket_Access_Control_Localhost and + Socket_Access_Control_Credentials can be used with D-Bus tubes.

+ +

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST NOT be included in the request.

+ + + + + + + + diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml new file mode 100644 index 0000000..19dda06 --- /dev/null +++ b/spec/Channel_Type_File_Transfer.xml @@ -0,0 +1,531 @@ + + + + Copyright © 2008-2009 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.

+ + + + (as stable API) + +

A channel type for transferring files. The + transmission of data between contacts is achieved by reading from + or writing to a socket. The type of the socket (local Unix, IPv4, + etc.) is decided on when the file transfer is offered or accepted.

+ +

A socket approach is used to make the transfer less dependent on both + client and connection manager knowing the same protocols. As an example, + when browsing an SMB share in a file manager, one selects "Send file" + and chooses a contact. Instead of passing a URL which would then require + the connection manager to connect to the SMB share itself, the client + passes a stream from which the connection manager reads, requiring no + further connection to the share. It also allows connection managers to + be more restricted in their access to the system, allowing tighter + security policies with eg SELinux, or more flexible deployments which + cross user or system boundaries.

+ +

The Telepathy client should connect to the socket or address that + the connection manager has set up and provided back to the clients + through the two methods.

+ +
  • In order to send a file, one should request a FileTransfer + channel for a contact, including at least the mandatory properties + (Filename, + Size and ContentType). + Then, one should + call ProvideFile to configure the socket that + will be used to transfer the file.
    • + +
  • In order to receive an incoming file transfer, one should call + AcceptFile and then wait until the state + changes to Open. When the receiver wants to resume a transfer, the Offset + argument should be should be set to a non-zero value when calling + AcceptFile.
    • + +
  • Once the offset has been negotiated, the + InitialOffsetDefined signal + is emitted and the InitialOffset property + is defined. The InitialOffsetDefined + signal is emitted before channel becomes Open. + The receiver MUST check the value of + InitialOffset for a difference in offset + from the requested value in AcceptFile.
    • + +
  • When the state changes to Open, Clients can start the transfer of the + file using the offset previously announced. +
+ +

If something goes wrong with the transfer, + Channel.Close + should be called on the channel.

+ +

The File channel type may be requested for handles of type + HANDLE_TYPE_CONTACT. If the channel is requested for any other + handle type then the behaviour is undefined.

+ +

Connection managers SHOULD NOT advertise support for file transfer to + other contacts unless it has been indicated by a call to + UpdateCapabilities. +

+ +

People would send us files, and it would always fail. That would be silly.

+ + + + + +

The state of the file transfer as described by the + File_Transfer_State enum.

+ + + + + +

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

+ +

This property is mandatory when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. Protocols which do not have a content-type property with file + transfers should set this value to application/octet-stream.

+ + + + + +

The name of the file on the sender's side. This is therefore given + as a suggested filename for the receiver. This cannot change + once the channel has been created.

+ +

This property should be the basename of the file being sent. For example, + if the sender sends the file /home/user/monkey.pdf then this property should + be set to monkey.pdf.

+ +

This property is mandatory when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. This property cannot be empty and MUST be set to a sensible value.

+ + + + + +

The size of the file. If this property is set, then the file + transfer is guaranteed to be this size. This cannot change once + the channel has been created.

+ +

When you are creating a channel with this property, its value + MUST be accurate and in bytes. However, when receiving a file, this + property still MUST be in bytes but might not be entirely accurate + to the byte.

+ +

This property is mandatory when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. If this information isn't provided in the protocol, connection managers MUST set it + to UINT64_MAX.

+ + + + + +

The type of the ContentHash property.

+ +

This property is optional when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. However, if you wish to include the ContentHash + property you MUST also include this property. If you omit this property from a + Connection.Interface.Requests.CreateChannel + method call then its value will be assumed to be File_Hash_Type_None.

+ +

For each supported hash type, implementations SHOULD include an entry + in RequestableChannelClasses + with this property fixed to that hash type. If the protocol supports + offering a file without a content hash, implementations SHOULD list + this property in Allowed in a requestable channel class, mapping hash + types they don't understand to None. +

+ + + + + +

Hash of the contents of the file transfer, of type described + in the value of the ContentHashType + property.

+ +

This property is optional when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. Its value MUST correspond to the appropriate type of the + ContentHashType property. If the + ContentHashType property is not set, or set to File_Hash_Type_None, + then this property will not even be looked at.

+ + + + + +

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

+ +

This property is optional when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method. If this property was not provided by the remote party, connection managers MUST set it to + the empty string.

+ + + + + +

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

+ +

This property is optional when requesting the channel with the + Connection.Interface.Requests.CreateChannel + method.

+ + + + + +

A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for sockets with that + address type. For simplicity, if a CM supports offering a + particular type of file transfer, it is assumed to support accepting + it. Connection Managers MUST support at least Socket_Address_Type_IPv4.

+ +

A typical value for a host without IPv6 support:

+ + 
+          {
+            Socket_Address_Type_IPv4:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+               Socket_Access_Control_Netmask],
+            Socket_Address_Type_Unix:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+          }
+
+ + + + + +

The number of bytes that have been transferred at the time of + requesting the property. This will be updated as the file transfer + continues.

+ + + + + +

The offset in bytes from where the file should be sent. This MUST + be respected by both the receiver and the sender after the state + becomes Open, but before any data is sent or received. Until the + InitialOffsetDefined signal + is emitted, this property is undefined.

+ +

Before setting the State property to + Open, the connection manager MUST set the InitialOffset property, + possibly to 0.

+ +

This property MUST NOT change after the state of the transfer has + changed to Open.

+ + + + + + + An invalid state type used as a null value. This value MUST NOT + appear in the State property. + + + + + The file transfer is waiting to be accepted/closed by the receiver. + The receiver has to call AcceptFile, + then wait for the state to change to Open and check the offset value. + + + + + The receiver has accepted the transfer. The sender now has to + call ProvideFile to actually start the transfer. + The receiver should now wait for the state to change to Open + and check the offset value. + + + + + The file transfer is open for traffic. + + + + + The file transfer has been completed successfully. + + + + + The file transfer has been cancelled. + + + + + + + + No reason was specified. + + + + + The change in state was requested. + + + + + The file transfer was cancelled by the local user. + + + + + The file transfer was cancelled by the remote user. + + + + + The file transfer was cancelled because of a local error. + + + + + The file transfer was cancelled because of a remote error. + + + + + + + + No hash. + + + + + MD5 digest as a string of 32 ASCII hex digits. + + + + + SHA1 digest as a string of ASCII hex digits. + + + + + SHA256 digest as a string of ASCII hex digits. + + + + + + + Accept a file transfer that's in the Pending state. The file + transfer's state becomes Accepted after this method is called. + At this point the client can connect to the socket. CM MUST emit + InitialOffsetDefined and change + the state to Open before writing to the socket. + Then InitialOffset should be respected in case + its value differs from the offset that was specified as an argument + to AcceptFile. + + + + The type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The desired offset in bytes where the file transfer should start. + The offset is taken from the beginning of the file. Specifying an + offset of zero will start the transfer from the beginning of the + file. The offset that is actually given in the + InitialOffset property can differ + from this argument where the requested offset is not supported. + (For example, some protocols do not support offsets at all so + the InitialOffset property will always be 0.) + + + + + The address on which the connection manager will listen for + connections for this file transfer. + + + + + + + The given address type or access-control mechanism is not supported. + + + + + + Your address type, access control, access control parameter, + offset, or a combination of all four is invalid. + + + + The file transfer is not in the Pending state, there isn't + or there is a local error with acquiring a socket. + + + + + + + + Provide the file for an outgoing file transfer which has been offered. + Opens a socket that the client can use to provide a file to the connection manager. + The channel MUST have been requested, and will change state + to Open when this method is called if its state was Accepted. + + + + The type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The address on which the connection manager will listen for + connections for this file transfer. + + + + + + + The given address type or access-control mechanism is not supported. + + + + + Your address type, access control, access control parameter, or + a combination of all three is invalid. + + + + Channel is not an outgoing transfer, ProvideFile has already been called, + or there was a local error acquiring the socket. + + + + + + + + Emitted when the state of a file transfer changes. + + + + The new state of the file transfer; see the File_Transfer_State enumeration. + + + + + The reason for the state change; see the File_Transfer_State_Change_Reason + enumeration. + The value will always be File_Transfer_State_Change_Reason_None, except + when changing state to cancelled. + + + + + + + Emitted when the number of transferred bytes changes. This will not be + signalled with every single byte change. Instead, the most frequent + this signal will be emitted is once a second. This should be + sufficient, and the TransferredBytes + property SHOULD NOT be polled. + + + + The number of already transferred bytes. + + + + + + + Emitted when the value of the InitialOffset + property has been negotiated. This signal MUST be emitted before the channel + becomes Open and clients have to use this offset when transferring the + file. + + + + The value of the InitialOffset property. + + + + + + + + diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml new file mode 100644 index 0000000..98f7458 --- /dev/null +++ b/spec/Channel_Type_Room_List.xml @@ -0,0 +1,166 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

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

For protocols with a concept of chatrooms on multiple servers + with different DNS names (like XMPP), the DNS name of the server + whose rooms are listed by this channel, e.g. "conference.jabber.org". + Otherwise, the empty string.

+ +

This property cannot change during the lifetime of the channel.

+ + + + + + + A boolean indicating if room listing is in progress + + + + Check to see if there is already a room list request in progress + on this channel. + + + + + + + An array of structs containing: +
    +
  • an integer room handle
    • +
  • a string representing the D-Bus interface name of the channel type
    • +
  • a dictionary mapping string keys to variant boxed information
    • +
+ + + +

Emitted when information about rooms on the server becomes available. + The array contains the room handle (as can be passed to the + RequestChannel + method with HANDLE_TYPE_ROOM), the channel + type, and a dictionary containing further information about the + room as available. The following well-known keys and types are + recommended for use where appropriate:

+ +
+
handle-name (s)
+
The identifier of the room (as would be returned by + InspectHandles)
+ +
name (s)
+
The human-readable name of the room if different from the handle
+ +
description (s)
+
A description of the room's overall purpose
+ +
subject (s)
+
The current subject of conversation in the room (as would + be returned by getting the string part of the Subject property)
+ +
members (u)
+
The number of members in the room
+ +
password (b)
+
True if the room requires a password to enter
+ +
invite-only (b)
+
True if you cannot join the room, but must be invited
+ +
room-id (s)
+
The human-readable identifier of a chat room (as would be + returned by getting the RoomID property)
+ +
server (s)
+
The DNS name of the server hosting these channels (as would be + returned by getting the Server property)
+
+ + + + + Request the list of rooms from the server. The + ListingRooms (True) signal should be + emitted when this request is being processed, + GotRooms when any room information is + received, and ListingRooms (False) when + the request is complete. + + + + + + + + + + + Stop the room listing if it's in progress, but don't close the channel. + The ListingRooms (False) signal should + be emitted when the listing stops. + + + + + A boolean indicating if room listing is in progress + + + Emitted to indicate whether or not room listing request is currently + in progress. + + + +

A channel type for listing named channels available on the server. Once the + ListRooms method is called, it emits signals for rooms present on the + server, until you Close this + channel. In some cases, it may not be possible + to stop the deluge of information from the server. This channel should be + closed when the room information is no longer being displayed, so that the + room handles can be freed.

+ +

This channel type may be implemented as a singleton on some protocols, so + clients should be prepared for the eventuality that they are given a + channel that is already in the middle of listing channels. The + ListingRooms signal, or + GetListingRooms method, can be used to check + this.

+ + + + diff --git a/spec/Channel_Type_Server_Authentication.xml b/spec/Channel_Type_Server_Authentication.xml new file mode 100644 index 0000000..76599aa --- /dev/null +++ b/spec/Channel_Type_Server_Authentication.xml @@ -0,0 +1,121 @@ + + + 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 stable API) + + + +

The type for a channel representing an authentication step with the + server. The actual authentication functionality is implemented by + the additional interface named in + AuthenticationMethod, + such as Channel.Interface.SASLAuthentication.

+ +

Future authentication steps also supported by this channel type might + include solving a captcha and/or agreeing to an EULA or terms-of-use + document; each of these would be represented by a channel with this + type, but a different + AuthenticationMethod.

+ +

Channels of this type will normally be be signalled and dispatched + while the Connection + owning them is in the CONNECTING state. They MAY also appear on a + Connection in the CONNECTED state, for instance if periodic + re-authentication is required.

+ +

Normally, only one channel of this type will + exist on a given Connection; if there is more than one, the handler + must complete authentication with each of them in turn.

+ +

Channels of this type cannot be requested with methods such as + CreateChannel. + They always have Requested = False, + TargetHandleType = None + and TargetHandle + = 0.

+ +

While it is CONNECTING, the Connection MUST NOT proceed with + connection, or signal + StatusChanged + to the CONNECTED state, until each channel of this type has either + been accepted as having a positive result (for instance, on SASL + channels this is done with the AcceptSASL method), or closed with the Close method.

+ + +

ServerAuthentication channels normally represent the client + authenticating itself to the server, but can also be used for the + server to authenticate itself to the client (i.e. prove that it is + in fact the desired server and not an imposter). Until the + authentication handler has confirmed this, connection should not + continue.

+ + +

If a channel of this type is closed with the Close method before + authentication has succeeded, this indicates that the Handler has + given up its attempts to authenticate or that no Handler is + available.

+ +

If this occurs, the connection manager MAY attempt to continue + connection (for instance, performing SASL authentication by using any + credentials passed to RequestConnection, + for instance from the Account.Parameters). If this fails + or has already been tried, the Connection will + disconnect.

+ + +

In particular, the ChannelDispatcher will close the + channel if it cannot find a handler.

+ + +

When the connection is done with the channel and it is no + longer needed, it is left open until either the connection state + turns to DISCONNECTED or the handler closes the channel. The + channel SHOULD NOT close itself once finished with.

+ + + + +

This property defines the method used for the authentication step + represented by this channel, which MUST be one of this channel's + Interfaces.

+ +

The initially-defined interface that can be used here is + Channel.Interface.SASLAuthentication.

+ + + + + + diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml new file mode 100644 index 0000000..1f3348e --- /dev/null +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -0,0 +1,69 @@ + + + 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 stable API) + + + + +

A channel type that carries a TLS certificate between a server + and a client connecting to it.

+

Channels of this kind always have Requested = False, + TargetHandleType + = None and TargetHandle + = 0, and cannot be requested with methods such as CreateChannel. + Also, they SHOULD be dispatched while the + Connection + owning them is in the CONNECTING state.

+

In this case, handlers SHOULD accept or reject the certificate, using + the relevant methods on the provided object, or MAY just Close the channel before doing so, to fall + back to a non-interactive verification process done inside the CM.

+

For example, channels of this kind can pop up while a client is + connecting to an XMPP server.

+ + + + +

A TLSCertificate + containing the certificate chain as sent by the server, + and other relevant information.

+

This property is immutable.

+ + + + + + + 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_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml new file mode 100644 index 0000000..63e7b2f --- /dev/null +++ b/spec/Channel_Type_Stream_Tube.xml @@ -0,0 +1,292 @@ + + + Copyright © 2008-2009 Collabora Limited + 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. + + + + + +

A stream tube is a transport for ordered, reliable data transfer, + similar to SOCK_STREAM sockets.

+ +

When offering a stream tube, the initiating client creates a local + listening socket and offers it to the recipient client using the + Offer method. When a + recipient accepts a stream tube using the + Accept method, the + recipient's connection manager creates a new local listening socket. + Each time the recipient's client connects to this socket, the + initiator's connection manager proxies this connection to the + originally offered socket.

+ + + + + + Offer a stream tube exporting the local socket specified. + + + + The type of the listening address of the local service, as a member of + Socket_Address_Type. + + + + + The listening address of the local service, as indicated by the + address_type. + + + + + The access control the local service applies to the local socket, + specified so the connection manager can behave appropriately + when it connects. + + + + + The dictionary of arbitrary + Parameters + to send with the tube offer. + + + + + + + The contact associated with this channel doesn't have tube + capabilities. + + + + + The connection manager doesn't support the given address type + or access-control type. + + + + + + + + Accept a stream tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeChannelStateChanged + signal is emitted. + + + + The type of address the connection manager should listen on. + + + + +

The type of access control the connection manager should apply to + the socket.

+ +

Note that if you plan to establish more than one connection + through the tube, the Socket_Access_Control_Port access control + can't be used as you can't connect more than once from the same + port.

+ + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The address on which the connection manager will listen for + connections to this tube. The client should not attempt to connect + to the address until the tube is open. + + + + + + + The access_control_param is invalid with the given access_control. + + + + + The given address type or access-control mechanism is not supported. + + + + + + + +

Emitted each time a participant opens a new connection to its + socket.

+ +

This signal is only fired on the offering side.

+ + + + The handle of the participant who opened the new connection + + + + +

A parameter which can be used by the listening process to identify + the connection. Note that this parameter has a meaningful value + only in the Socket_Access_Control_Port and + Socket_Access_Control_Credentials cases. If a different + Socket_Access_Control has been chosen when offering the tube, this + parameter should be ignored.

+ +

In the Socket_Access_Control_Port case, the variant + contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the address from which the CM is connected to the client + application.

+ +

In the Socket_Access_Control_Credentials case, the variant + contains the byte (D-Bus signature 'y') that has been sent with + the credentials.

+ + + + + The unique ID associated with this connection. This ID will be used + to identifiy the connection when reporting errors with + ConnectionClosed. + + + + + + +

Emitted when the tube application connects to the CM's socket.

+ +

This signal is only fired on the accepting side.

+ + + + The unique ID associated with this connection. This ID will be used + to identifiy the connection when reporting errors with + ConnectionClosed. + + + + + + +

Emitted when a connection has been closed.

+ + + + The ID of the connection. + + + + +

The name of a D-Bus error describing the error that occurred.

+ +

The following errors can be used:

+
    +
  • org.freedesktop.Telepathy.Error.Cancelled: + user closed the socket or the tube.
    • +
  • org.freedesktop.Telepathy.Error.ConnectionLost: + the bytestream relaying connection's data has been broken.
    • +
  • org.freedesktop.Telepathy.Error.ConnectionRefused: + the tube offer refused the connection.
    • +
+ + + + + A debug message. + + + + + + +

A string representing the service name that will be used over the + tube. It should be a well-known TCP service name as defined by + + http://www.iana.org/assignments/port-numbers or + + http://www.dns-sd.org/ServiceTypes.html, for instance + "rsync" or "daap".

+

When the tube is offered, the service name is transmitted to the + other end.

+

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST be included in the request.

+ + + + + +

A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for stream tubes with that + address type. For simplicity, if a CM supports offering a + particular type of tube, it is assumed to support accepting it.

+ +

A typical value for a host without IPv6 support:

+ + 
+          {
+            Socket_Address_Type_IPv4:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+               Socket_Access_Control_Netmask],
+            Socket_Address_Type_Unix:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+          }
+
+ +

Connection Managers MUST support at least IPv4 with the localhost + access control.

+ +

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST NOT be included in the request.

+ + + + + + An identifier for a stream tube connection. + These are defined with the + NewLocalConnection or + NewRemoteConnection signals + and are used by ConnectionClosed + to identify the closed connection. + + + + + + + diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml new file mode 100644 index 0000000..aa2b903 --- /dev/null +++ b/spec/Channel_Type_Streamed_Media.xml @@ -0,0 +1,853 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

+ + + + + + + + An audio stream + + + A video stream + + + + + + The stream is disconnected. + + + The stream is trying to connect. + + + The stream is connected. + + + + + + Media are not being sent or received + + + Media are being sent, but not received + + + Media are being received, but not sent + + + Media are being sent and received + + + + + + + The local user has been asked to send media by the remote user. + Call RequestStreamDirection to + indicate whether or not this is acceptable. + + + + + The remote user has been asked to send media by the local user. + The StreamDirectionChanged signal + will be emitted when the remote user accepts or rejects this + change. + + + + + + + + + + + + + + + +

An unsigned integer identifying a stream within a channel.

+ + + + + + + An array of structs containing: +
    +
  • the stream identifier
    • +
  • the contact handle who the stream is with (or 0 if the stream + represents more than a single member)
    • +
  • the type of the stream
    • +
  • the current stream state
    • +
  • the current direction of the stream
    • +
  • the current pending send flags
    • +
+ + + + Returns an array of structs representing the streams currently active + within this channel. Each stream is identified by an unsigned integer + which is unique for each stream within the channel. + + + + + + + An array of stream identifiers (as defined in + ListStreams) + + + + +

Request that the given streams are removed. If all streams are + removed, the channel MAY close.

+ +

Clients SHOULD NOT attempt to terminate calls by removing all the + streams; instead, clients SHOULD terminate calls by removing the + Group.SelfHandle + from the channel, using either + RemoveMembers + or + RemoveMembersWithReason. +

+ + + + + + A stream identifier is unknown + + + + + + + + + The stream identifier (as defined in + ListStreams) + + + + + The desired stream direction (a value of MediaStreamDirection) + + + +

Request a change in the direction of an existing stream. In particular, + this might be useful to stop sending media of a particular type, + or inform the peer that you are no longer using media that is being + sent to you.

+ +

Depending on the protocol, streams which are no longer sending in + either direction should be removed and a + StreamRemoved signal emitted. + Some direction changes can be enforced locally (for example, + BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending), + others may not be possible on some protocols, and some need agreement + from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND + flag will be set in the + StreamDirectionChanged signal, and the + signal + emitted again without the flag to indicate the resulting direction when + the remote end has accepted or rejected the change.

+ + + + + A stream identifier is unknown + + + + + The requested direction is not available on this stream + + + + + + + + + A contact handle with whom to establish the streams + + + + + An array of stream types (values of MediaStreamType) + + + + + An array of structs (in the same order as the given stream types) + containing: +
    +
  • the stream identifier
    • +
  • the contact handle who the stream is with (or 0 if the stream + represents more than a single member)
    • +
  • the type of the stream
    • +
  • the current stream state
    • +
  • the current direction of the stream
    • +
  • the current pending send flags
    • +
+ + + +

Request that streams be established to exchange the given types of + media with the given member. In general this will try and establish a + bidirectional stream, but on some protocols it may not be possible to + indicate to the peer that you would like to receive media, so a + send-only stream will be created initially. In the cases where the + stream requires remote agreement (eg you wish to receive media from + them), the StreamDirectionChanged signal + will be emitted with the + MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again + with the flag cleared when the remote end has replied.

+ +

If streams of the requested types already exist, calling this + method results in the creation of additional streams. Accordingly, + clients wishing to have exactly one audio stream or exactly one + video stream SHOULD check for the current streams using + ListStreams before calling this + method.

+ + +

It is valid to use a handle which is neither + a current nor pending member in this channel's Group + interface. If + so, that handle will be added to the remote-pending set only when + an attempt has actually been made to contact them. For further + call-state notification, use the CallState + interface, if + supported. This usage was not allowed in spec versions below + 0.17.2.

+ + + + + + A stream type given is invalid. + + + + + A stream type given is not implemented by the connection manager. + Since 0.17.23, connection managers SHOULD raise this error + in preference to InvalidArgument. + + Connection managers can't know whether an unknown number + is a valid stream type that was introduced in a later spec + version. + + + + + + That contact's client does not implement one of the given stream + types. For this method, clients SHOULD consider this error and + NotCapable to be equivalent. + + + + + That contact's client does not implement one of the given stream + types. Since 0.17.23, connection managers SHOULD raise + this in preference to NotAvailable. + + + + + + + + + The stream identifier (as defined in + ListStreams) + + + + + The contact handle who the stream is with (or 0 if it + represents more than a single member) + + + + + The stream type (a value from MediaStreamType) + + + +

Emitted when a new stream has been added to this channel. + Clients SHOULD assume that the stream's + Media_Stream_State is initially Disconnected.

+ +

If a connection manager needs to represent the addition of a stream + whose state is already Connecting or Connected, it MUST do this + by emitting StreamAdded, closely followed by + StreamStateChanged indicating a + change to the appropriate state.

+ + +

Historically, it was not clear from the StreamAdded signal what + the state of the stream was. telepathy-spec 0.17.22 + clarified this.

+ + +

Similarly, clients SHOULD assume that the initial + Media_Stream_Direction of a newly added stream + is Receive, and that the initial + Media_Stream_Pending_Send is + Pending_Local_Send.

+ +

If a connection manager needs to represent the addition of a stream + whose direction or pending-send differs from those initial values, + it MUST do so by emitting StreamAdded, closely followed by + StreamDirectionChanged indicating a + change to the appropriate direction and pending-send state.

+ + +

StreamAdded doesn't itself indicate the stream's direction; this + is unfortunate, but is preserved for compatibility.

+ +

This is the appropriate direction for streams added by a remote + contact on existing connection managers, and does not violate + user privacy by automatically sending audio or video (audio streams + start off muted, video streams start off not sending). For + streams added by the local user using the client receiving the + signal, the true direction can also be determined from the return + value of the RequestStreams + method.

+ +

Existing clients typically operate by maintaining a separate + idea of the directions that they would like the streams to have, + and enforcing these intended directions by calling + RequestStreamDirection whenever + needed.

+ + + + + + + + The stream identifier (as defined in ListStreams) + + + + + The new stream direction (as defined in ListStreams) + + + + + The new pending send flags (as defined in ListStreams) + + + +

Emitted when the direction or pending flags of a stream are + changed.

+ +

If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user + has requested that we begin sending on this stream. + RequestStreamDirection + should be called to indicate whether or not this change is + acceptable.

+ + +

This allows for a MSN-style user interface, "Fred has asked you + to enable your webcam. (Accept | Reject)", if desired.

+ + + + + + + + The stream identifier (as defined in + ListStreams) + + + + + A stream error number, one of the values of MediaStreamError + + + + + A string describing the error (for debugging purposes only) + + + + Emitted when a stream encounters an error. + + + + + + + stream_id - the stream identifier (as defined in + ListStreams) + + + + Emitted when a stream has been removed from this channel. + + + + + + + The stream identifier (as defined in + ListStreams) + + + + + The new stream state (as defined in ListStreams) + + + + Emitted when a member's stream's state changes. + + + + + +

If set to true in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call RequestStreams.

+ +

If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.

+ +

If true on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.

+ +

If true on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + ListStreams).

+ +

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

+ +

This reduces D-Bus round trips.

 + +

Connection managers capable of signalling audio calls to contacts + SHOULD include a channel class in RequestableChannelClasses + with ChannelType + = StreamedMedia + and TargetHandleType + = Contact in the fixed properties dictionary, and InitialAudio + (and also InitialVideo, if applicable) in the allowed properties + list. Clients wishing to discover whether a connection manager + can signal audio and/or video calls SHOULD use this information.

+ + +

Not all protocols support signalling video calls, and it would be + possible (although unlikely) to have a protocol where only video, + and not audio, could be signalled.

+ + +

Connection managers that support the ContactCapabilities + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = StreamedMedia + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.

+ + +

Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.

+ + +

Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling UpdateCapabilities + (clients of a ChannelDispatcher + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their HandlerChannelFilter + properties):

+ +
    +
  • { ChannelType = StreamedMedia }
    • +
  • { ChannelType = StreamedMedia, InitialAudio = true } + if receiving calls with audio is supported
    • +
  • { ChannelType = StreamedMedia, InitialVideo = true } + if receiving calls with video is supported
    • +
+ + +

Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.

+ + + + + + +

The same as InitialAudio, but for + a video stream. This property is immutable (cannot change).

+ +

In particular, note that if this property is false, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.

+ +

This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.

+ + + + + +

If True, once streams have been requested for this channel + (either by setting InitialAudio or + InitialVideo when the channel is + requested, or by calling + RequestStreams on a channel with no + streams), a stream of a different content type cannot be added; + subsequent calls to RequestStreams + that attempt to do so will fail.

+ +

If this property is missing, clients SHOULD assume that it is false, + and thus that the channel's streams can be changed once the call has + started.

+ +

If this property is present in the "allowed" set in all of the + StreamedMedia entries in a contact's capabilities, then user + interfaces MAY choose to show a separate "call" option for each + class of call.

+ + +

For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + must be requested at the start of the call if video is desired. + User interfaces may use this pseudo-capability as a hint to + display separate "Audio call" and "Video call" buttons, rather + than a single "Call" button with the option to add and remove + video once the call has started for contacts without this flag. +

+ + +

This property is immutable, and therefore SHOULD be announced + in NewChannels, + etc.

+ + + + +

A channel that can send and receive streamed media such as audio or + video. Provides a number of methods for listing and requesting new + streams, and signals to indicate when streams have been added, removed + and changed status. The state of the call (ringing remotely, ringing + locally, answered, missed, etc.) are represented using the properties + and signals of the Group interface.

+ +

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

+ +

Outgoing calls

+ +

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

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

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

+ +

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

+ +

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

+ +

Incoming calls

+ +

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

+ +

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

+ +

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

+ + +

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

+ + +

When the local user accepts an incoming call, the connection manager + SHOULD change the direction of any streams with pending local send + to be sending, without altering whether those streams are + receiving.

+ + +

This matches existing practice, and means that a client + can answer incoming calls and get an unmuted microphone/activated + webcam without having to take additional action to accept the + stream directions.

+ +

It does, however, introduce a race condition: a client believing + that it is accepting an audio-only call by calling AddMembers + can inadvertantly accept an audio + video call (and hence activate + sending from a webcam without the user's permission) if a video + stream is added just before AddMembers is processed. This race + should be removed when this specification is revised.

+ + +

During a call

+ +

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

+ +

Handler filters

+ +

For historical reasons, handlers must specify more than one filter if + they want to correctly advertise support for audio and/or video calls. If + they can handle channels using the MediaSignalling + interface, they should also advertise various + Handler_Capability_Tokens to indicate which codecs and + transports they support. See InitialAudio + and MediaSignalling/video/h264 + for the gory details. In summary:

+ +
+
To advertise support for streamed media in general, include the + following filter in HandlerChannelFilter:
+ 
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+}
+ +
To advertise support for audio calls, also include the following + filter:
+ 
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+  '...Channel.Type.StreamedMedia.InitialAudio': True,
+}
+ +
To advertise support for video calls, also include the following + filter:
+ 
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+  '...Channel.Type.StreamedMedia.InitialVideo': True,
+}
+ +
If you use telepathy-farsight, and have H.264 support, you probably + want these Capabilities:
+ 
+[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp",
+  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p",
+  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264",
+]
+
+ + + + + The channel-type-specific capability flags used for + Channel.Type.StreamedMedia in the Connection.Interface.Capabilities + interface. See the InitialAudio + property for details of the mechanisms that will replace this. + + + + The handle is capable of using audio streams within a media channel. + + + + + The handle is capable of using video streams within a media channel. + + + + + The handle is capable of performing STUN to traverse NATs. + + + + + The handle is capable of establishing Google Talk peer-to-peer + connections (as implemented in libjingle 0.3) to traverse NATs. + + + + + The handle is capable of establishing ICE UDP peer-to-peer + connections (as defined by the IETF MMUSIC working group) to traverse + NATs. + + + + + + Channels whose target handle is this contact will have + ImmutableStreams = True. + + + + + + + + diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml new file mode 100644 index 0000000..0cd4d5b --- /dev/null +++ b/spec/Channel_Type_Text.xml @@ -0,0 +1,669 @@ + + + Copyright © 2005-2009 Collabora Limited + Copyright © 2005-2009 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 +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.

+ + + + + The Messages interface is now + mandatory + + + + A unique-per-channel identifier for an incoming message. These + SHOULD be allocated in a way that minimizes collisions (in particular, + message IDs SHOULD NOT be re-used until all of the 32-bit integer + space has already been used). + + + + + New APIs should use + an array of Message_Part instead. + A struct (message ID, timestamp in seconds since + 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) + representing a pending text message, as returned by + ListPendingMessages. The arguments of + the Received signal also match this + struct's signature. + + + + + + + + + + + + The IDs of the messages to acknowledge + + + + Inform the channel that you have handled messages by displaying them to + the user (or equivalent), so they can be removed from the pending queue. + + + + + A given message ID was not found, so no action was taken + + + + + + + Consulting + MessageTypes is preferred. + + + + An array of integer message types (ChannelTextMessageType) + + + + Return an array indicating which types of message may be sent on this + channel. + + + + + Consulting + PendingMessages is preferred. + + + + If true, behave as if + AcknowledgePendingMessages had also + been called. + + + Setting this to true is NOT RECOMMENDED for clients that + have some sort of persistent message storage - clients SHOULD only + acknowledge messages after they have actually stored them, which is + impossible if this flag is true. + + + + An array of structs representing the pending queue. Each contains: +
    +
  • a numeric identifier
    • +
  • a Unix timestamp indicating when the message was received
    • +
  • the contact handle for the contact who sent the message
    • +
  • the message type, taken from ChannelTextMessageType
    • +
  • the bitwise-OR of the message flags from ChannelTextMessageFlags
    • +
  • the text of the message
    • +
+ + + + List the messages currently in the pending queue, and optionally + remove then all. + + + + + In practice, this signal + was not emitted, and does not have useful semantics. + + This signal is emitted to indicate that an incoming message was + not able to be stored and forwarded by the connection manager + due to lack of memory. + + + + + The + MessageReceived signal is more informative. + + + + A numeric identifier for acknowledging the message + + + + + A Unix timestamp indicating when the message was received + + + + + The handle of the contact who sent the message + + + + + The type of the message (normal, action, notice, etc.) + + + + + A bitwise OR of the message flags + + + + + The text of the message + + + + Signals that a message with the given id, timestamp, sender, type + and text has been received on this channel. Applications that catch + this signal and reliably inform the user of the message should + acknowledge that they have dealt with the message with the + AcknowledgePendingMessages method. + + + + + The + SendMessage method is more flexible. + + + + An integer indicating the type of the message + + + + + The message to send + + + +

Request that a message be sent on this channel. When the message has + been submitted for delivery, this method will return and the + Sent signal will be emitted. If the + message cannot be submitted for delivery, the method returns an error + and no signal is emitted.

+ +

This method SHOULD return before the Sent signal is + emitted.

+ + +

When a Text channel implements the Messages + interface, that "SHOULD" becomes a "MUST".

+ + + + + + + + + + + + + + An unknown error occurred + + + + + The requested contact was offline + + + + + The requested contact is not valid + + + + + The user does not have permission to speak on this channel + + + + + The outgoing message was too long and was rejected by the server + + + + + The channel doesn't support sending text messages to the requested + contact + + + + + + Delivery reporting is now + provided by the Messages interface. + + + + The error that occurred + + + + + The Unix timestamp indicating when the message was sent + + + + + The message type + + + + + The text of the message + + + +

Signals that an outgoing message has failed to send. The error + will be one of the values from ChannelTextSendError.

+ +

This signal should only be emitted for messages for which + Sent has already been emitted and + Send has already returned success.

+ + older spec versions claimed that SendError + was emitted instead of Sent, rather than in addition + to Sent. However, the 0.17.3+ semantics were what we'd always + actually implemented. + + + + The + MessageSent signal is more informative. + + + + Unix timestamp indicating when the message was sent + + + + + The message type (normal, action, notice, etc) from + ChannelTextMessageType + + + + + The text of the message. If the message was, or will be, altered + during transmission, this argument SHOULD reflect what other + contacts will receive rather than being a copy of the argument + to Send. + + + +

Signals that a message has been submitted for sending.

+ + + + + + The type of message. + + + + + An ordinary chat message. Unknown types SHOULD be treated like this. + + + + + + An action which might be presented to the user as + "* <sender> <action>", such as an IRC CTCP + ACTION (typically selected by the "/me" command). For example, the + text of the message might be "drinks more coffee". + + + + + + A one-off or automated message not necessarily expecting a reply + + + + + + An automatically-generated reply message. + + + + + + A delivery report. This message type MUST NOT appear unless the + channel supports the Messages + interface; see Message_Part for the format that + delivery reports must take. + + + + + + The + Messages interface has an extensible data structure + including separate booleans for most of these flags. + + + + The incoming message was truncated to a shorter length by the + server or the connection manager. + + + + + +

The incoming message contained non-text content which cannot be + represented by this interface, but has been signalled + in the Messages + interface.

+ +

Connection managers SHOULD only set this flag if the non-text + content appears to be relatively significant (exactly how + significant is up to the implementor). The intention is that + if this flag is set, clients using this interface SHOULD inform + the user that part of the message was not understood.

+ + + + + +

The incoming message was part of a replay of message history.

+ + +

In XMPP multi-user chat, a few past messages are replayed + when you join a chatroom. A sufficiently capable IRC connection + manager could also set this flag on historical messages when + connected to a proxy like bip or irssi-proxy. The existence + of this flag allows loggers and UIs to use better heuristics + when eliminating duplicates (a simple implementation made + possible by this flag would be to avoid logging scrollback + at all).

+ + + + + + +

The incoming message has been seen in a previous channel during + the lifetime of the Connection, but + had not been acknowledged + when that channel closed, causing an identical channel (the + channel in which the message now appears) to open.

+ + +

This means that a logger (which should already have seen the + message in the previous channel) is able to recognise and ignore + these replayed messages.

+ + + + + + + + True if people may join the channel without other members being made + aware of their identity. + + + + + True if people may not join the channel until they have been invited. + + + + + The limit to the number of members, if limited is true. + + + + + True if there is a limit to the number of channel members. + + + + + True if channel membership is not sufficient to allow participation. + + + + + A human-visible name for the channel, if it differs from the channel's + TargetID. + + + + + A human-readable description of the channel's overall purpose. + + + + + The password required to enter the channel if password-required is true. + + + + + True if a password must be provided to enter the channel. + + + + + True if the channel will remain in existence on the server after all + members have left it. + + + + + True if the channel is not visible to non-members. + + + + + A human-readable description of the current subject of conversation in + the channel, similar to /topic in IRC. This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. + + + + + A contact handle representing who last modified the subject, or 0 + if it isn't known. This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. + + + + + A unix timestamp indicating when the subject was last modified. + This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. + + + + +

A channel type for sending and receiving messages. This channel type + is primarily used for textual messages, but can also be used for + formatted text, text with "attachments", or binary messages on some + protocols.

+ +

Most of the methods and signals on this interface are deprecated, + since they only support plain-text messages with limited metadata. + See the mandatory Messages + interface for the modern equivalents.

+ +

When a message is received, an identifier is assigned and a + MessageReceived signal emitted, and the message + is placed in a pending queue represented by the + PendingMessages property. + When the Handler + for a channel has handled the message by showing it to the user + (or equivalent), it should acknowledge the receipt of that message + using the AcknowledgePendingMessages + method, and the message will then be removed from the pending queue. + Numeric identifiers for received messages may be reused over the + lifetime of the channel.

+ +

Sending messages can be requested using the + SendMessage method, which will return + successfully when the message has been submitted for sending, or + return an error with no signal emission if there is an immediate + failure. If a message is submitted for sending but delivery of the + message later fails, this is indicated by a delivery report, which + is received in the same way as an incoming message.

+ +

Simple one-to-one chats (such as streams of private messages in + XMPP or IRC) should be represented by a Text channel whose + TargetHandleType + is Handle_Type_Contact. The expected way to + request such a channel is to set the ChannelType, TargetHandleType, + and either TargetHandle or TargetID in a call to EnsureChannel.

+ +

Named chat rooms whose identity can be saved and used again later + (IRC channels, Jabber MUCs) are expected to be represented by Text + channels with Handle_Type_Room and the Group + interface. In protocols where a chatroom can be used as a continuation + of one or more one-to-one chats, these channels should also have the + Conference + interface.

+ +

Unnamed, transient chat rooms which cannot be rejoined by their + unique identifier (e.g. a conversation on MSN which has, or once had, + three or more participants) are expected to be represented by Text + channels with Handle_Type_None (and hence TargetHandle 0), the + Group + interface, and optionally the + Conference + interface.

+ +

On protocols like MSN where a conversation with a user is actually + just a nameless chat room starting with exactly two members, to which + more members can be invited, the initial one-to-one conversation + SHOULD be represented with Handle_Type_Contact. If a third participant + joins or is invited, this SHOULD be represented by signalling + a new Conference channel + with the one-to-one channel in its InitialChannels, migrating the underlying protocol + object from the one-to-one channel to the Conference channel, + and creating a new protocol-level conversation if the one-to-one + channel is re-used. See the Conference interface for more details.

+ + +

This keeps the presentation of all one-to-one conversations + uniform, and makes it easier to hand over a conversation from a + 1-1-specific UI to a more elaborate multi-user UI; while it does + require UIs to understand Conference to follow the + upgrade, UIs that will deal with XMPP need to understand Conference + anyway.

+ + +

If a channel of type Text is closed while it has pending messages, + the connection manager MUST allow this, but SHOULD open a new channel + to deliver those messages, signalling it as a new channel with the + NewChannels + signal. The new channel should resemble the old channel, but have + Requested = FALSE regardless of its previous value; the InitiatorHandle + and InitiatorID should correspond to the sender of one of the pending + messages.

+ + +

In effect, this turns this situation, in which a client + is likely to lose messages:

+ +
    +
  • UI window is closed
    • +
  • message arrives
    • +
  • text channel emits Received
    • +
  • UI calls Close on text channel before it has seen the + Received signal
    • +
  • text channel emits Closed and closes
    • +
+ +

into something nearly equivalent to this situation, which is + fine:

+ +
    +
  • UI window is closed
    • +
  • UI calls Close on text channel
    • +
  • text channel emits Closed and closes
    • +
  • message arrives
    • +
  • new text channel is created, connection emits NewChannels
    • +
  • (the same or a different) UI handles it
    • +
+ +

Requested must be set to FALSE so the replacement channel + will be handled by something.

+ +

In practice, connection managers usually implement this by keeping + the same internal object that represented the old channel, adjusting + its properties, signalling that it was closed, then immediately + re-signalling it as a new channel.

+ + +

As a result, Text channels SHOULD implement Channel.Interface.Destroyable.

+ + +

This "respawning" behaviour becomes problematic if there is no + suitable handler for Text channels, or if a particular message + repeatedly crashes the Text channel handler; a channel dispatcher + can't just Close() the channel in these situations, because + it will come back.

+ +

In these situations, the channel dispatcher needs a last-resort + way to destroy the channel and stop it respawning. It could either + acknowledge the messages itself, or use the Destroyable interface; + the Destroyable interface has the advantage that it's not + channel-type-dependent, so the channel dispatcher only has to + understand one extra interface, however many channel types + eventually need a distinction between Close and Destroy.

+ + + + + + diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml new file mode 100644 index 0000000..c0a973f --- /dev/null +++ b/spec/Channel_Type_Tubes.xml @@ -0,0 +1,615 @@ + + + + Copyright © 2007-2009 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. + + + + Client implementations + SHOULD use StreamTube and + DBusTube + instead. + + + +

A "tube" is a mechanism for arbitrary data transfer. Two types of + data transfer are currently specified: D-Bus messages, and streams of + bytes. Each tube has a service name, which is a string specifying the + kind of communication that takes place over it, and a dictionary of + arbitrary parameters. Tube parameters are commonly used for bootstrap + information such as usernames and passwords. Each tube is identified + by a locally unique identifier.

+ +

The Tubes channel type may be requested for handles of type + HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.

+ +

Stream tubes specify listening addresses using pairs of parameters + with signature 'u', 'v', where the integer 'u' is a member of + Socket_Address_Type and the v is dependent on the type of address.

+ + + + An identifier for a tube. These are local to a Tubes + channel, and may not be assumed to be the same as the other + participants' idea of the tube identifier. + + + + A struct (tube ID, initiator handle, tube type, + service name, parameters, state) representing a tube, as returned + by ListTubes on the Tubes channel type. + + + + + + + + + + Represents a participant in a multi-user D-Bus tube, as + returned by GetDBusNames and seen in the + DBusNamesChanged signal. + + + The handle of a participant in this D-Bus tube. + + + + + That participant's unique name. + + + + + + + +

The tube is D-Bus tube as described by the + org.freedesktop.Telepathy.Channel.Type.DBusTube interface.

+ + + + + +

The tube is stream tube as described by the + org.freedesktop.Telepathy.Channel.Type.StreamTube interface.

+ + + + + + + + The tube is waiting to be accepted/closed locally. + + + + + The tube is waiting to be accepted/closed remotely. + + + + + The tube is open for traffic. + + + + + + The supported socket address and access-control types + for tubes. See GetAvailableStreamTubeTypes. + + + + + + List the available address types and access-control types + for stream tubes. + + +

A mapping from address types (members of Socket_Address_Type) to + arrays of access-control type (members of Socket_Access_Control) + that the connection manager supports for stream tubes with that + address type. For simplicity, if a CM supports offering a + particular type of tube, it is assumed to support accepting it.

+ +

A typical value for a host without IPv6 support:

+ + 
+            {
+              Socket_Address_Type_IPv4:
+                [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+                 Socket_Access_Control_Netmask],
+              Socket_Address_Type_Unix:
+                [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+            }
+
+ +

If stream tubes are not supported, this will be an empty + dictionary.

+ + + + + + + + An array of the available tube types, as defined by the Tube_Type + enum. + + + + + + + + Return an array of tuples, each representing a tube, with the + following members: + +
    +
  • the tube's ID
    • +
  • the tube's initiator
    • +
  • the tube's type
    • +
  • the tube's service
    • +
  • the tube's parameters
    • +
  • the tube's state
    • +
+ + + + + + + + Offers a D-Bus tube providing the service specified. + + + + A string representing the service name that will be used over the + tube. + It should be a well-known D-Bus service name, of the form + com.example.ServiceName. + + + + + A dictionary of properties for the new tube; the allowable keys, + types and values are defined by the service. Connection managers + must support the value being any primitive (non-container) + D-Bus type, or a byte array 'ay'. + + + + + The ID of the new tube. + + + + + + + The contact associated with this channel doesn't have tubes + capabilities. + + + + + The connection manager doesn't support D-Bus tubes. + + + + + + + + Offer a stream tube exporting the local socket specified. + + + + A string representing the service name that will be used over the + tube. + It should be a well-known TCP service name as defined by + + http://www.iana.org/assignments/port-numbers or + + http://www.dns-sd.org/ServiceTypes.html, for instance + "rsync" or "daap". + + + + +

A dictionary of properties for the new tube; the allowable keys, + types and values are defined by the service. Connection managers + must support the value being any primitive (non-container) + D-Bus type, or a byte array 'ay'.

+

These should usually be the same key-value pairs specified for + use in the DNS-SD TXT record for that service.

+ + + + + The type of the listening address of the local service, as a member of + Socket_Address_Type. + + + + + The listening address of the local service, as indicated by the + address_type. + + + + + The access control the local service applies to the local socket, + specified so the connection manager can behave appropriately + when it connects. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The ID of the new tube. + + + + + + + The contact associated with this channel doesn't have tube + capabilities. + + + + + The connection manager doesn't support stream tubes, or + does not support the given address type or access-control type. + + + + + + + + Emitted when a tube is created. + + + + The ID of the new tube. + + + + + The handle of the contact who initiated the tube. + + + + + The tube type, as defined by the Tube_Type enum. + + + + + A string representing the service that will be used over the tube. + + + + + The new tube's properties. + + + + + The new tube's state. + + + + + + + + Accept a D-Bus tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeStateChanged signal is + emitted. + + + + The ID of the tube to accept. + + + + + The string describing the address of the private bus. The client + should not attempt to connect to the address until the tube is open. + + + + + + The given tube ID is invalid or does not refer to a D-Bus + tube. + + + + + + + + Accept a stream tube that's in the "local pending" state. The + connection manager will attempt to open the tube. The tube remains in + the "local pending" state until the TubeStateChanged signal is + emitted. + + + + The ID of the tube to accept. + + + + + The type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The address on which the connection manager will listen for + connections to this tube. The client should not attempt to connect + to the address until the tube is open. + + + + + + + The given tube ID is invalid or does not refer to a stream + tube. + + + + + The given address type or access-control mechanism is not supported. + + + + + + + + Emitted when the state of a tube changes. + + + + The ID of the tube that changed state. + + + + + The new state of the tube; see the Tube_State enumeration. + + + + + + + Close a tube. + + + + The ID of the tube to close. + + + + + + + + + + Emitted when a tube has been closed. The ID of a closed tube is no + longer valid. The ID may later be reused for a new tube. + + + + The ID of the tube that was closed. + + + + + + + + For a D-Bus tube, return a string describing the address of the + private bus. + + + + The ID of the tube to get an address for. + + + + + The bus address. + + + + + + The tube is not a D-Bus tube. + + + + + This tube is not in the "open" state. + + + + + + + + + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping + between contact handles and their unique bus names on this tube. + + + + The ID of the tube to get names for. + + + + + An array of structures, each containing a contact handle and a D-Bus + bus name. + + + + + + The tube is not a multi-user D-Bus tube. + + + + + This tube is not in the "open" state. + + + + + + + + + Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a + participant opens or closes the tube. + + + + The ID of the tube whose names have changed. + + + + + Array of handles and D-Bus names of new participants. + + + + + Array of handles of former participants. + + + + + + + For a stream tube, obtain the address of the socket used to + communicate over this tube. + + + + The ID of the stream tube to get the socket for. + + + + + The type of the listening address of the socket, as a member of + Socket_Address_Type. + + + + + The listening address of the socket, as indicated by the + address_type. + + + + + + The tube is not a stream tube. + + + + + This tube is not in the "open" state. + + + + + + + + Emitted on a stream tube when a participant opens a new connection + to its socket. + + + + The ID of the tube + + + + + The handle of the participant who opened the new connection + + + + + + + + diff --git a/spec/Client.xml b/spec/Client.xml new file mode 100644 index 0000000..19f6914 --- /dev/null +++ b/spec/Client.xml @@ -0,0 +1,122 @@ + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + +

Telepathy clients use connection managers, the channel dispatcher + and optionally the account manager to provide useful + functionality.

+ +

User interface processes are the obvious example of Telepathy + clients, but they can provide other functionality, such as + address-book synchronization.

+ +

Every running or activatable process with a well-known + name of the form org.freedesktop.Telepathy.Client.clientname + should be probed by the channel dispatcher to discover its + capabilities. Each client is either an observer, an + approver, a channel handler, or some combination + of these.

+ + +

Activatable services (those with a D-Bus .service + file) must be supported so that we can run clients + in response to channel creation.

+ +

Non-activatable services (those that do not register a D-Bus + .service file for their well-known name, but do + request it at runtime) must be supported so that we can have + programs that process channels, but only if they are already + running - for instance, a full-screen media centre + application might do this.

+ + +

The client name, clientname, MUST be a non-empty string of + ASCII digits, letters, dots and/or underscores, starting with a + letter, and without sets of two consecutive dots or a dot + followed by a digit. For non-activatable services, it MAY contain a + part that is generated per instance at runtime.

+ + +

If each of a client Foo's instances should be able to manipulate + channels separately, the instance with unique name + :1.25 might request a well-known name like + org.freedesktop.Telepathy.Client.Foo._1._25.

+ +

(Note that well-known bus-name components may not start with a + digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)

+ + +

Each Client MUST export an object whose object path may be + determined by replacing '.' with '/' in the well-known name and + prepending '/'. This object represents its API as a Telepathy + client; the channel dispatcher will call its methods and read + its properties when appropriate.

+ +

As an optimization, activatable clients SHOULD install a file + $XDG_DATA_DIRS/telepathy/clients/clientname.client + containing a cached version of its immutable properties, + so that for most clients, the channel dispatcher can + just read a file to discover capabilities, instead of + having to service-activate the client immediately in order to fetch + its read-only properties. However, the D-Bus API is canonical, and + the channel dispatcher MUST support clients without such a file.

+ +

Non-activatable clients MAY install a .client file, + but there's not much point in them doing so.

+ +

The .client files MUST contain UTF-8 text with the same syntax + as + Desktop + Entry files (although the allowed groups, keys and values differ). + Every .client file MUST contain a group whose name is + the name of this interface.

+ +

The groups, keys and values in the .client file are + defined by individual interfaces. Each interface that can usefully + cache information in the .client file SHOULD correspond + to a group with the same name.

+ + + + +

A list of the extra interfaces provided by this client. + This SHOULD include at least one of + Client.Observer, + Client.Approver or + Client.Handler.

+ +

In the .client file, this is represented by key + "Interfaces" in the group named after this interface. + The value of the key is a list of interface names each followed by + a semicolon (so it always ends with a semicolon unless it is empty), + i.e. a key of type "strings" as described in the Desktop Entry + specification.

+ + + + + + diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml new file mode 100644 index 0000000..dd26303 --- /dev/null +++ b/spec/Client_Approver.xml @@ -0,0 +1,197 @@ + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + + + +

Approvers are clients that notify the user that new channels have + been created by a contact, and allow the user to accept or reject + those channels. The new channels are represented by a ChannelDispatchOperation + object, which is passed to the + AddDispatchOperation method.

+ + +

For instance, Empathy's tray icon, or the answer/reject window + seen when a Maemo device receives a VoIP call, should be + Approvers.

+ + +

Approvers can also select which channel handler will be used for the + channel, for instance by offering the user a list of possible + handlers rather than just an accept/reject choice. + However, the Channel Dispatcher must be able to prioritize + possible handlers on its own using some reasonable heuristic, + probably based on user configuration.

+ +

It is possible (and useful) to have an approver and + a channel handler in the same process; this is particularly useful + if a channel handler wants to claim responsibility for particular + channels itself.

+ +

All approvers are notified simultaneously. For instance, in a + desktop system, there might be one approver that displays a + notification-area icon, one that is part of a contact list + window and highlights contacts there, and one that is part + of a full-screen media player.

+ +

Any approver can approve the handling of a channel dispatch operation + with a particular channel handler by calling the HandleWith + method. Approvers can also attempt to Claim + channels; if this succeeds, the approver may handle the channels + itself (if it is also a Handler), or close the channels in order to + reject them.

+ +

At the D-Bus level, there is no "reject" operation: approvers wishing + to reject channels SHOULD call the Claim method, then (if it succeeds) + close the channels in any way they see fit.

+ +

The first approver to reply gets its decision acted on; any other + approvers that reply at approximately the same time will get a D-Bus + error, indicating that the channel has already been dealt with.

+ +

Approvers should usually prompt the user and ask for + confirmation, rather than dispatching the channel to a handler + straight away.

+ + + + +

A specification of the channels in which this approver is + interested. The AddDispatchOperation + method should be called by the channel dispatcher whenever at least + one of the channels in a channel dispatch operation matches this + description.

+ +

This property works in exactly the same way as the + Client.Observer.ObserverChannelFilter + property. In particular, it cannot change while the approver process + continues to own the corresponding Client bus name.

+ +

In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + ApproverChannelFilter instead of ObserverChannelFilter.

+ + + + + +

Called by the channel dispatcher when a ChannelDispatchOperation + in which the approver has registered an interest is created, + or when the approver starts up while such channel dispatch + operations already exist.

+ +

The channel dispatcher SHOULD call this method on all approvers + at the same time. If an approver returns an error from this method, + the approver is assumed to be faulty.

+ +

If no approvers return from this method + successfully (including situations where there are no matching + approvers at all), the channel dispatcher SHOULD consider this + to be an error, and recover by dispatching the channel to the + most preferred handler.

+ + + Processes that aren't approvers (or don't at least ensure that there + is some approver) probably shouldn't be making connections + anyway, so there should always be at least one approver running. + + + + + +

The initial value of the ChannelDispatchOperation.Channels + property, containing the Channels + to be dispatched and their properties.

+ + +

This can't be signalled to the approver through the Properties + parameter of this method, because Channels is not an immutable + property.

+ + +

This argument always contains all of the channels in the channel + dispatch operation, even if not all of them actually match + the ApproverChannelFilter.

+ + +

This seems the least bad way to handle such a situation; + see the discussion on + bug + #21090.

+ + +

The actual channels to be dispatched may reduce as channels are + closed: this is signalled by ChannelDispatchOperation.ChannelLost. +

+ +

Approvers SHOULD connect to ChannelLost and ChannelDispatchOperation.Finished. + (if desired) before returning from AddDispatchOperation, since + those signals are guaranteed not to be emitted until after all + AddDispatchOperation calls have returned (with success or failure) + or timed out.

+ + + + + +

The + ChannelDispatchOperation + to be processed.

+ + + + + +

Properties of the channel dispatch operation. The keys MUST be + fully qualified D-Bus property names. This MUST NOT include + properties that could change, SHOULD include as many properties as + possible given that constraint, and MUST include at least the + Account, + Connection + and PossibleHandlers + properties.

+ + + + + + + diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml new file mode 100644 index 0000000..3a922e8 --- /dev/null +++ b/spec/Client_Handler.xml @@ -0,0 +1,337 @@ + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + + + +

Handlers are the user interface for a channel. They turn an abstract + Telepathy channel into something the user wants to see, like a text + message stream or an audio and/or video call.

+ +

For its entire lifetime, each channel on a connection known to the + channel dispatcher is either being processed by the channel dispatcher, + or being handled by precisely one Handler.

+ +

Because each channel is only handled by one Handler, handlers may + perform actions that only make sense to do once, such as acknowledging + Text + messages, doing the actual streaming for StreamedMedia + channels with the MediaSignalling + interface, or transferring the file in FileTransfer + channels.

+ +

When a new incoming channel (one with + Requested + = FALSE) is offered to + Approvers + by the channel dispatcher, it also offers the Approvers a list of all + the running or activatable handlers whose + HandlerChannelFilter property + (possibly as cached in the .client file) indicates that they + are able to handle the channel. The Approvers can choose one of + those channel handlers to handle the channel.

+ +

When a new outgoing channel (one with + Requested + = TRUE) appears, the channel dispatcher passes it to an appropriate + channel handler automatically. +

+ + + + + +

A specification of the channels that this channel handler can + deal with. It will be offered to approvers as a potential + channel handler for bundles that contain only suitable channels, + or for suitable channels that must be handled separately.

+ +

This property works in exactly the same way as the + Client.Observer.ObserverChannelFilter + property. In particular, it cannot change while the handler process + continues to own the corresponding Client bus name.

+ +

In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + HandlerChannelFilter instead of ObserverChannelFilter.

+ + + + + +

If true, channels destined for this handler are automatically + handled, without invoking approvers.

+ + +

The intended usage is to allow a client handling one channel to + pick up closely related channels. Suppose a client capable of + handling both Text and StreamedMedia, + org.freedesktop.Telepathy.Client.Empathy, is + handling a StreamedMedia channel. That client can take a second + well-known bus name, say + org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1, + and configure an object at + /org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1 + with BypassApproval = TRUE, + whose HandlerChannelFilter + matches closely related Text channels by their Bundle property.

+ + +

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

+ +
+[org.freedesktop.Telepathy.Client.Handler]
+BypassApproval=true
+
+ + + + + + A DBus_Interface, followed by a slash '/' character + and an identifier for a capability defined by that interface. The + capability identifier SHOULD be in lower case. If an interface + references an external specification which is case-insensitive (such + as MIME), then names from that specification MUST be normalized to + lower-case before providing them to this Telepathy API, so that + implementations can safely rely on simple byte-by-byte comparison. + + + These aren't D-Bus core Properties, and we want them to look visibly + different. + + +

So far, all client capabilities are defined by the MediaSignalling + interface.

+ + + + + +

The set of additional capabilities supported by this handler. + This describes things like support for streamed media codecs and + NAT traversal mechanisms: see the Contact Capabilities + interface for more details.

+ +

For handlers that have a .client file, the + channel dispatcher may discover this property from the + org.freedesktop.Telepathy.Client.Handler.Capabilities + group; for each capability, that group contains a key + whose name is the capability, with value true. + Keys with other values SHOULD NOT appear in this group.

+ +

For instance, the .client file for a streamed media + handler that supports ICE-UDP NAT traversal, Speex audio, + and Theora and H264 video might contain this group:

+ +
+[org.freedesktop.Telepathy.Client.Handler.Capabilities]
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
+
+ +

Like the HandlerChannelFilter + property, this property cannot change while the Handler owns its + Client bus name. However, the .client file, if any, + can change (due to upgrades or installation of pluggable codecs), + and the capabilities really supported by the handler might not + exactly match what is cached in the .client file.

+ + +

The client file is installed statically and is intended to list + codecs etc. that the handler guarantees it can support (e.g. by + having a hard dependency on them), whereas the running handler + process might be able to find additional codecs.

+ + + + + + +

Called by the channel dispatcher when this client should handle these + channels, or when this client should present channels that it is already + handling to the user (e.g. bring them into the foreground).

+ + +

Clients are expected to know what channels they're already handling, + and which channel object path corresponds to which window or tab. + This can easily be done using a hash table keyed by channels' object + paths.

+ + +

This method can raise any D-Bus error. If it does, the + handler is assumed to have failed or crashed, and the channel + dispatcher MUST recover in an implementation-specific way; it MAY + attempt to dispatch the channels to another handler, or close the + channels.

+ +

If closing the channels, it is RECOMMENDED that the channel + dispatcher attempts to close the channels using + Channel.Close, + but resorts to calling + Channel.Interface.Destroyable.Destroy + (if available) or ignoring the channel (if not) if the same handler + repeatedly fails to handle channels.

+ +

After HandleChannels returns successfully, the client process is + considered to be responsible for the channel until it its unique + name disappears from the bus.

+ + +

If a process has multiple Client bus names - some temporary and + some long-lived - and drops one of the temporary bus names in order + to reduce the set of channels that it will handle, any channels + that it is already handling should remain unaffected.

+ + + + + + The + Account + with which the channels are associated. The + well-known bus name to use is that of the + AccountManager. + + + + + + The Connection with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + + + + + + The channels and their immutable properties. Their well-known + bus name is the same as that of the Connection. + + + + + +

The requests satisfied by these channels.

+ + +

If the handler implements Requests, this tells it + that these channels match previous AddRequest + calls that it may have received.

+ +

There can be more than one, if they were EnsureChannel + requests.

+ + + + + + + The time at which user action occurred, or 0 if this channel + 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. + + + + + +

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.

+ + + + + + + + +

A list of the channels that this process is currently handling.

+ +

There is no change notification.

+ + +

This property exists for state recovery - it makes it possible + for channel handling to survive a ChannelDispatcher crash.

+ +

If the channel dispatcher is automatically replaced, the + replacement can discover all Handlers by looking for the Client + well-known bus names, and discover which channels they are + currently handling. Once this has been done, all unhandled + channels can be re-dispatched, and the only issue visible to + the user is that unhandled channels that they have already + approved might be sent back to Approvers.

+ + +

The value of this property SHOULD be the same for all Client + instances that share a unique bus name, and SHOULD include all + channels that are being handled, even if they were conceptually + handled by a different Client instance.

+ + +

Otherwise, when a process released a temporary Client name, + channels that it handled because of that Client name would no + longer be state-recoverable.

+ + + + + + + diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml new file mode 100644 index 0000000..4c1a8b7 --- /dev/null +++ b/spec/Client_Handler_Future.xml @@ -0,0 +1,88 @@ + + + Copyright © 2009 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.

+ + + + + + +

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

+ + + + + +

If true, channels destined for this handler are not passed to + observers for observing.

+ + +

This is useful in use-cases where the handler doesn't want anyone + observing the channel - for example, because channels it handles + shouldn't be logged.

+ + +

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

+ +
+[org.freedesktop.Telepathy.Client.Handler]
+BypassObservers=true
+
+ + + + + +

If true, channels destined for this handler that have the + Conference interface, with a channel that + was previously handled by the same client process in their + InitialChannels property, should bypass the + approval stage. In effect, this is a weaker form of + BypassApproval.

+ + +

It would be reasonable for a user interface to accept + invitations to continuations of an existing channel automatically, + or not; this is a matter of UI policy.

+ +

It's somewhat complex for an Approver to keep track of which + channels are being handled by a particular Handler, but + the Channel Dispatcher already has to track this, so it's + useful for the channel dispatcher to assist here.

+ + + + + + + diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml new file mode 100644 index 0000000..3cecfce --- /dev/null +++ b/spec/Client_Interface_Requests.xml @@ -0,0 +1,175 @@ + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + + + + +

This interface can be implemented by a Handler to be notified about + requests for channels that it is likely to be asked to handle.

+ + + + +

Called by the ChannelDispatcher to indicate that channels have been + requested, and that if the request is successful, they will probably + be handled by this Handler. The ChannelDispatcher SHOULD only + call this method on one handler per request.

+ + +

This allows the UI to start preparing to handle the channels + in advance (e.g. render a window with an "in progress" message), + improving perceived responsiveness.

+ +

The use of "probably" is because you can't necessarily tell from + a channel request which handler will handle particular channels. + A reasonable heuristic would be to match the request against the + HandlerChannelFilter, + and respect the preferred handler (if any).

+ + +

If the request succeeds and is given to the expected Handler, + the Requests_Satisfied parameter to + HandleChannels + can be used to match the channel to a previous AddRequest call.

+ + +

This lets the UI direct the channels to the window that it + already opened.

+ + +

If the request fails, the expected handler is notified by the + channel dispatcher calling its + RemoveRequest method.

+ + +

This lets the UI close the window or display the error.

+ + +

The channel dispatcher SHOULD remember which handler was notified, + and if the channel request succeeds, it SHOULD dispatch the channels + to the expected handler, unless the channels do not match that + handler's HandlerChannelFilter. + If the channels are not dispatched to the expected handler, the + handler that was expected is notified by the channel dispatcher + calling its RemoveRequest method + with the NotYours error.

+ + +

Expected handling is for the UI to close the window it + previously opened.

+ + +

Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.

+ + +

Calls to this method are merely a notification.

+ + + + + + The ChannelRequest + object, which MUST have been returned by CreateChannel + or EnsureChannel + before this method is called. + + + See those methods for the rationale of this ordering. + + + + + + +

Some of the properties of the ChannelRequest. To avoid race + conditions, this dictionary MUST NOT include properties whose + values could subsequently change. It SHOULD include as many + properties as possible, given that constraint.

+ +

In particular, the properties Requests, + UserActionTime + and Account + MUST be included, and Hints + MUST be included if implemented.

+ + + + + + +

Called by the ChannelDispatcher to indicate that a request + previously passed to AddRequest + has failed and should be disregarded.

+ +

Handlers SHOULD NOT return an error from this method; errors + returned from this method SHOULD NOT alter the channel dispatcher's + behaviour.

+ + +

Calls to this method are merely a notification.

+ + + + + + The request that failed. + + + + + +

The name of the D-Bus error with which the request failed.

+ +

If this is org.freedesktop.Telepathy.Error.NotYours, + this indicates that the request succeeded, but all the resulting + channels were given to some other handler.

+ + + + + + Any message supplied with the D-Bus error. + + + + + + + diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml new file mode 100644 index 0000000..01fee8b --- /dev/null +++ b/spec/Client_Observer.xml @@ -0,0 +1,379 @@ + + + Copyright © 2008-2009 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.

+ + + + (as a stable interface) + + + + +

Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.

+ +

Observers SHOULD NOT modify the state of a channel except + via user interaction.

+ + +

We want Observer UIs for file transfer channels (a progress + bar for the transfer) to be able to have a Cancel button.

+ + +

Observers MUST NOT carry out actions that exactly one process + must take responsibility for (e.g. acknowledging Text + messages, or carrying out the actual transfer in a file transfer + channel).

+ + +

Since arbitrarily many observers can be activated for + each channel, it would not make sense for observers to do things + that can only be done by one process (acknowledging + Text + messages, carrying out streaming for + StreamedMedia + channels, doing the actual data transfer for file transfers, + setting up the out-of-band connection for Tubes). The + Handler + is responsible for such tasks.

+ +

Handlers MAY, of course, delegate responsibility for these + tasks to other processes (including those run as observers), + but this MUST be done explicitly via a request from the Handler + to the Observer.

+ + +

Whenever a collection of new channels is signalled, the channel + dispatcher will notify all running or activatable observers whose + ObserverChannelFilter property + (possibly as cached in the .client file) indicates that they are + interested in some of the channels.

+ +

Observers are activated for all channels in which they have + registered an interest - incoming, outgoing or automatically created - + although of course the ObserverChannelFilter property can be set + to filter on the + Requested + property.

+ +

Because it might take time for an observer to become ready (for + instance, a Text logger needs to wait until pending messages have been + downloaded), the channel dispatcher must wait (up to some timeout) for + all observers to return from + ObserveChannels before letting anything + destructive happen. Destructive things (e.g. acknowledging messages) + are defined to be done by handlers, therefore HandleWith and Claim + aren't allowed to succeed until all observers are ready.

+ + + + +

A specification of the channels in which this observer is + interested. The ObserveChannels method + should be called by the channel dispatcher whenever any of the new + channels in a NewChannels + signal match this description.

+ +

Only certain D-Bus types have useful semantics for matching like this, + so only certain types are allowed:

+ +
+
Integers of all sizes, including byte (y, n, q, i, u, x, t)
+
Matched by numeric value, regardless of type (e.g. 42 as a + 16-bit signed integer 'n' is considered equal to 42 as a 32-bit + unsigned integer 'u')
+ +
Booleans (b)
+
Matched by equality in the obvious way; not considered equal to any + other type
+ +
Strings (s)
+
Matched by equality in the obvious way; not considered equal to any + other type
+ +
Object paths (o)
+
Matched by equality in the obvious way; not considered equal to any + other type
+ +
+ +

This property never changes while the observer process owns its + Client bus name. For activatable processes, the filter can change + due to an upgrade - the channel dispatcher SHOULD observe changes to + .client files using a mechanism like inotify.

+ + +

Not allowing this property to change is a simplification, + particularly for activatable processes (we reject the possibility + that a process with a .client file, when activated, has a filter + that differs from what its .client file said).

+ +

If an Observer wants to add extra channels to its list of + interests at runtime, it can register an additional Client bus name + (for instance, the org.freedesktop.Telepathy.Client.Empathy process + with unique name :1.42 could additionally register + org.freedesktop.Telepathy.Client.Empathy._1_42) with additional + filters. To remove those filters, it can release the bus name; + it could even re-claim the bus name immediately, with different + filters.

+ +

The same principle is applied to Approvers and Handlers.

+ + +

For observers that have a .client file, the channel dispatcher + may discover this property from keys of the form + "propertyname type", + in groups in the .client file whose name is the name of this + interface followed by .ObserverChannelFilter, + a space and an ASCII decimal number starting from 0.

+ +

Values in the .client file are encoded in exactly the same way as + the default-p keys in .manager files, as + described in the ConnectionManager interface (but note that not all + types supported in .manager files can appear in .client files).

+ +

For instance, a .client file for an observer that is only interested + in Text channels, with CONTACT or ROOM handles, that were requested by + a local client:

+ +
+[org.freedesktop.Telepathy.Client]
+Interfaces=org.freedesktop.Telepathy.Client.Observer;
+
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+org.freedesktop.Telepathy.Channel.Requested b=true
+
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=2
+org.freedesktop.Telepathy.Channel.Requested b=true
+
+ + + + + + + When using telepathy-mission-control, version 5.4.0 or later is + needed for this property to be useful. + + + +

If true, upon the startup of this observer, ObserveChannels + will be called for every already existing channel matching + its ObserverChannelFilter

+ +

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 + possibility that it will miss some events during this process + (particularly Text + messages), this window of event loss is kept to a minimum.

+ +

Non-activatable observers can't take advantage of this + mechanism, but setting this property on a non-activatable + observer does allow it to "catch up" on channels that are + currently active at the time that it starts up.

+ + +

When the ObserveChannels method is called due to observer recovery, + the Observer_Info dictionary will contain one extra item + mapping the key "recovering" to True.

+ + + + + +

Called by the channel dispatcher when channels in which the + observer has registered an interest are announced in a NewChannels + signal.

+ +

If the same NewChannels signal announces some channels that match + the filter, and some that do not, then only a subset of the channels + (those that do match the filter) are passed to this method.

+ +

If the channel dispatcher will split up the channels from a single + NewChannels signal and dispatch them separately (for instance + because no installed Handler can handle all of them), it will call + ObserveChannels several times.

+ +

The observer MUST NOT return from this method call until it is ready + for a handler for the channel to run (which may change the channel's + state).

+ + +

The channel dispatcher must wait for observers to start up, + to avoid the following race: text channel logger (observer) gets + ObserveChannels, text channel handler gets + HandleChannels + channel handler starts up faster and acknowledges messages, + logger never sees those messages.

+ + +

The channel dispatcher SHOULD NOT change its behaviour based on + whether this method succeeds or fails: there are no defined D-Bus + errors for this method, and if it fails, this only indicates that + an Observer is somehow broken.

+ + +

The expected error response in the channel dispatcher is to + log a warning, and otherwise continue as though this method + had succeeded.

+ + + + + + The + Account + with which the channels are associated. The + well-known bus name to use is that of the + AccountManager. + + + + + + The + Connection + with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + + + + + + The Channels + and their properties. Their well-known bus names are all the same as + that of the Connection. + + + + + +

The path to the ChannelDispatchOperation + for these channels, or the special value '/' if there is no + ChannelDispatchOperation (because the channels were requested, not + incoming).

+ +

If the Observer calls Claim + or HandleWith + on the dispatch operation, it MUST be careful to avoid deadlock, + since these methods cannot return until the Observer has returned + from ObserveChannels.

+ + +

This allows an Observer to Claim + a set of channels without having to match up calls to this method + with calls to AddDispatchOperation.

+ + + + + + + The ChannelRequests + satisfied by these channels. + + + If the same process is an Observer and a Handler, it can be useful + to be given this information as soon as possible (it will also + be passed to Handler.HandleChannels). + + + + + + +

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

+ +
+
recovering - b
+
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 + to catch up on previous events (perhaps after a previous instance of + 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; + observers MAY safely ignore any entry in this dictionary.

+ + + + + + + + diff --git a/spec/Connection.xml b/spec/Connection.xml new file mode 100644 index 0000000..51ec1ab --- /dev/null +++ b/spec/Connection.xml @@ -0,0 +1,1293 @@ + + + Copyright (C) 2005-2009 Collabora Limited + Copyright (C) 2005-2009 Nokia Corporation + Copyright (C) 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.

+ + + + + + + + A struct representing a channel, as returned by + ListChannels on the Connection interface. + + The object path of the channel, which is on the + same bus name as the connection + + + The channel's type + + + The type of the handle that the channel communicates + with, or Handle_Type_None if there is no associated + handle + + + The handle that the channel communicates with, + or 0 if there is no associated handle + + + + + +

Request that the connection be established. This will be done + asynchronously and errors will be returned by emitting + StatusChanged signals.

+ +

Calling this method on a Connection that is already connecting + or connected is allowed, and has no effect.

+ + + + + + Request that the connection be closed. This closes the connection if + it's not already in DISCONNECTED state, and destroys the connection + object. + + + + + +

The set of optional interfaces supported by this connection. + Before the connection status changes to CONNECTED, + this property may change at any time, but it is guaranteed that + interfaces will only be added, not removed. After the connection + status changes to CONNECTED, this property cannot + change further.

+ +

There is no explicit change notification; reasonable behaviour + for a client would be to retrieve the interfaces list once + initially, and once more when it becomes CONNECTED.

+ + +

In some connection managers, certain capabilities of a connection + are known to be implemented for all connections (e.g. support + for SimplePresence), and some interfaces (like SimplePresence) can + even be used before connecting. Other capabilities may + or may not exist, depending on server functionality; by the time + the connection goes CONNECTED, the connection manager is expected + to have evaluated the server's functionality and enabled any extra + interfaces for the remainder of the Connection's lifetime.

+ + + Clients SHOULD fall back + to calling GetInterfaces if this + property is not supported. + + + + + + The value of the Interfaces property + + + + +

Returns the set of optional interfaces supported by this + connection. See Interfaces for more + details.

+ + + + + + Before version 0.17.8 calling GetInterfaces while + on a connection that is not yet CONNECTED wasn't allowed. If a + CM returns this error, its list of interfaces should be regarded + as empty until it becomes CONNECTED. + + + + + + + + + A string identifier for the protocol + + + + + Get the protocol this connection is using. + + + + + + Emitted whenever the SelfHandle property + changes. If the connection + is not yet in the CONNECTED state, this signal is not guaranteed + to be emitted. + + Clients MAY assume that if the + SelfHandle property exists, this signal will be emitted when + necessary. + + + + The new value of the SelfHandle property. + + + + + + + The handle which represents the user on this connection, which will + remain valid for the lifetime of this connection, or until a change + in the user's identifier is signalled by the + SelfHandleChanged signal. + If the connection is not yet in the CONNECTED state, the value of + this property MAY be zero. + + For compatibility with older + versions, clients should fall back to calling the + GetSelfHandle + method. + + + + + + The value of the SelfHandle property + + + + + Returns the value of the SelfHandle property. Change notification + is via the SelfHandleChanged signal. + + Use GetAll to get the + SelfHandle property (and all other Connection properties) + instead. + + + + + + + + +

The current status of the connection. Change notification is via + the StatusChanged signal.

+ +

If retrieval of property succeeds and yields the value Disconnected, + this indicates that the connection has not yet been established. + If connection has been attempted and failed, the Connection object + SHOULD be removed from the bus entirely, meaning that retrieval of + this property SHOULD fail.

+ + Clients SHOULD fall back + to calling GetStatus if this + property is not supported. + + + + + + The value of the Status property + + + + + Get the current status as defined in the + StatusChanged signal. + + + + + If + HasImmortalHandles is true, + this method no longer does anything. + + + The type of handle to be held + + + + + + A array of integer handles to hold + + + + +

If HasImmortalHandles is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.

+ +

In older connection managers, this method + notifies the connection manger that your client is holding a copy + of handles which may not be in use in any existing channel or + list, and were not obtained by using the + RequestHandles method. For + example, a handle observed in an emitted signal, or displayed + somewhere in the UI that is not associated with a channel. The + connection manager must not deallocate a handle where any clients + have used this method to indicate it is in use until the + ReleaseHandles + method is called, or the clients disappear from the bus.

+ +

Note that HoldHandles is idempotent - calling it multiple times + is equivalent to calling it once. If a handle is "referenced" by + several components which share a D-Bus unique name, the client + should perform reference counting internally, and only call + ReleaseHandles when none of the cooperating components need the + handle any longer.

+ + + + + + + The handle type is invalid + + + + + One of the given handles is not valid + + + + + + + + + The type of handle to be inspected + + + + + + An array of integer handles of this type + + + + + + An array of identifiers corresponding to the given handles, in the same order. + + + + + Return a string representation for a number of handles of a given + type. + + + + + + + The handle type is invalid + + + + + One of the given handles is not valid + + + + + + + Use the + Requests.Channels + property instead. + + + + + An array of structs representing channels. + + + + + List all the channels which currently exist on this connection. + + + + + + + + + Connection managers MUST still + emit this signal, but clients SHOULD listen for the Requests.NewChannels + signal instead. + + + + + A D-Bus object path for the channel object on this service + + + + + + A D-Bus interface name representing the channel type + + + + + + An integer representing the type of handle this channel + communicates with, or Handle_Type_None if no handle is specified + + + + + + A handle indicating the specific contact, room or list this + channel communicates with, or zero if no handle is specified + + + + + +

If true, the channel was requested by a client that intends to + present it to the user itself (i.e. it passed suppress_handler=TRUE + to the RequestChannel method), so no + other handler should be + launched. Clients MAY assume that channels where this is true + were created by a user request.

+ +

If false, either the channel was created due to incoming + information from the service, or the channel was requested by + a local client that does not intend to handle the channel itself + (this usage is deprecated).

+ +

Clients MUST NOT assume that only incoming channels will have + this flag set to false.

+ + + + + Emitted when a new Channel object is created, either through user + request or incoming information from the service. + + + + + If + HasImmortalHandles is true, + this method no longer does anything. + + + An integer handle type (as defined in RequestHandle) + + + + + + An array of integer handles being held by the client + + + + +

If HasImmortalHandles is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.

+ +

In older connection managers, this method + explicitly notifies the connection manager that your client is no + longer holding any references to the given handles, and that they + may be deallocated if they are not held by any other clients or + referenced by any existing channels. See + HoldHandles for notes.

+ + + + + + + The handle type is invalid + + + + + One of the given handles is not valid + + + + + + + Use + Requests.CreateChannel + or Requests.EnsureChannel + instead. Connection managers MAY implement RequestChannel by + raising NotImplemented, or implement fewer types of channel via + this API. + + + + A D-Bus interface name representing base channel type + + + + + + An integer representing the handle type, or Handle_Type_None if + no handle is specified + + + + + + A nonzero integer handle representing a contact, room, list etc. + according to handle_type, or zero if the handle_type is + Handle_Type_None + + + + + +

Clients SHOULD always set this to true.

+ + +

The historical meaning was that clients that did not + intend to take responsibility for displaying the channel to + the user could set this to FALSE, in which case the channel + dispatcher would launch an appropriate channel handler.

+ +

However, clients whose functionality relies on having a + working channel dispatcher should obtain that functionality by + calling methods on the channel dispatcher, so that they will + get an appropriate error if the channel dispatcher is missing + or not working.

+ +

The channel dispatcher itself should set this to true too, + so that it will ignore the + NewChannel signal that results + from the creation of the channel. It can then dispatch the + channel returned from this method to an + appropriate handler.

+ +

So, there is no sensible use-case for setting this to false, + and setting it to false can result in unhandled channels (in + the case where clients assume that a channel dispatcher is + present, but it isn't).

+ + + + + + + The D-Bus object path for the channel created or retrieved + + + + +

Request a channel satisfying the specified type and communicating + with the contact, room, list etc. indicated by the given + handle_type and handle. The handle_type and handle may both be + zero to request the creation of a new, empty channel, which may + or may not be possible, depending on the protocol and channel + type.

+ +

On success, the returned channel will always be of the requested + type (i.e. implement the requested channel-type interface).

+ +

If a new, empty channel is requested, on success the returned + channel will always be an "anonymous" channel for which the type + and handle are both zero.

+ +

If a channel to a contact, room etc. is requested, on success, the + returned channel may either be a new or existing channel to + the requested entity (i.e. its + TargetHandleType + and TargetHandle + properties are the + requested handle type and handle), or a newly created "anonymous" + channel associated with the requested handle in some + implementation-specific way.

+ +

For example, for a contact handle, the returned channel + might be "anonymous", but implement the groups interface and have + the requested contact already present among the members.

+ +

If the request cannot be satisfied, an error is raised and no + channel is created.

+ + + + + + + + Unknown channel type + + + + + The given handle does not exist or cannot be created + + + + + The requested channel type cannot be created with the given handle + + + + + The requested channel cannot be created because contact doesn't + have the required capabilities. + + + + + + + + + + + + A "null" handle type used to indicate the absence of a handle. + When a handle type and a handle appear as a pair, if the handle + type is zero, the handle must also be zero. + + + + + A contact + + + + + A chat room + + + + + A server-generated contact list (see Channel.Interface.Group) + + + + + A user-defined contact list (see Channel.Interface.Group) + + + + + + An unsigned 32-bit integer representing a + handle + + + + An unsigned 32-bit integer representing a handle of type + Handle_Type_Contact + + + + An unsigned 32-bit integer representing a handle of type + Handle_Type_Room + + + + An unsigned 32-bit integer representing a handle of type + Handle_Type_List + + + + An unsigned 32-bit integer representing a handle of type + Handle_Type_Group + + + + If + HasImmortalHandles is true, + this method no longer has its reference-counting effect. + + + The type of handle required + + + + + + An array of identifiers of entities to request handles for + + + + + + An array of integer handle numbers in the same order as the given identifiers. + + + + +

Request several handles from the connection manager which represent a + number of contacts, rooms or server-stored lists on the service.

+ +

If HasImmortalHandles is true, + which SHOULD always be the case in this version of telepathy-spec, + the handles remain valid until the connection disconnects.

+ +

The implementation of this method in older connection managers + must 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 + ReleaseHandles + method. Where the identifier refers to an entity that already has a + handle in this connection manager, this handle should be returned + instead. The handle number 0 must not be returned by the connection + manager.

+ + + + + + + The given identifier does not identify a valid entity of the given + type. + + + For instance, an XMPP connection would raise this error for + identifiers with type Handle_Type_Room that do not contain + exactly one '@' character, that contain spaces, and so on. + + + + + + The given handle type is not valid, or is not implemented on this + connection. + + + For instance, a connection to a protocol that doesn't have + chat rooms would raise this error for room handles, and all CMs + would raise this error for Handle_Type_None. + + + + + + + + + + The connection is fully connected and all methods are available. + + + + + Connect has been called but the + connection has not yet been established. Some methods may fail + until the connection has been established. + + + + + If this is retrieved from GetStatus or + Status, it indicates that connection + has not yet been attempted. If seen in a + StatusChanged signal, it indicates + that the connection has failed; the Connection object SHOULD be + removed from D-Bus immediately, and all subsequent method calls + SHOULD fail. + + + + + + +

A reason why the status of the connection changed. Apart from + Requested, the values of this enumeration only make sense as + reasons why the status changed to Disconnected.

+ + + + +

There is no reason set for this state change. Unknown status + reasons SHOULD be treated like this reason.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Disconnected.

+ + + + + +

The change is in response to a user request. Changes to the + Connecting or Connected status SHOULD always indicate this reason; + changes to the Disconnected status SHOULD indicate this reason + if and only if the disconnection was requested by the user.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cancelled.

+ + + + + +

There was an error sending or receiving on the network socket.

+ +

When the status changes from Connecting to Disconnected for this + reason, the equivalent D-Bus error is either + org.freedesktop.Telepathy.Error.NetworkError, + org.freedesktop.Telepathy.Error.ConnectionRefused, + org.freedesktop.Telepathy.Error.ConnectionFailed + or some more specific error.

+ +

When the status changes from Connected to Disconnected for this + reason, the equivalent D-Bus error is either + org.freedesktop.Telepathy.Error.NetworkError, + org.freedesktop.Telepathy.Error.ConnectionLost + or some more specific error.

+ + + + + +

The username or password was invalid.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.AuthenticationFailed. +

+ + + + + +

There was an error negotiating SSL on this connection, or + encryption was unavailable and require-encryption was set when the + connection was created.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.EncryptionNotAvailable + if encryption was not available at all, or + org.freedesktop.Telepathy.Error.EncryptionError + if encryption failed.

+ + + + + +

In general, this reason indicates that the requested account + name or other identification could not be used due to conflict + with another connection. It can be divided into three cases:

+ +
    +
  • If the status change is from Connecting to Disconnected + and the 'register' parameter to RequestConnection was present + and true, the requested account could not be created on the + server because it already exists. + The equivalent D-Bus error is + org.freedesktop.Telepathy.Error.RegistrationExists. +
    • + +
  • If the status change is from Connecting to Disconnected + but the 'register' parameter is absent or false, the connection + manager could not connect to the specified account because + a connection to that account already exists. + The equivalent D-Bus error is + org.freedesktop.Telepathy.Error.AlreadyConnected. + + + In some protocols, like XMPP (when connecting with the same + JID and resource as an existing connection), the existing + connection "wins" and the new one fails to connect. + +
    • + +
  • If the status change is from Connected to Disconnected, + the existing connection was automatically disconnected because + a new connection to the same account (perhaps from a different + client or location) was established. + The equivalent D-Bus error is + org.freedesktop.Telepathy.Error.ConnectionReplaced. + + + In some protocols, like MSNP (when connecting twice with the + same Passport), the new connection "wins" and the + existing one is automatically disconnected. + +
    • +
+ + + + + +

The server did not provide a SSL certificate.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.NotProvided. +

+ + + + + +

The server's SSL certificate is signed by an untrusted certifying + authority. This error SHOULD NOT be used to represent a self-signed + certificate: use the more specific Cert_Self_Signed reason for + that.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Untrusted. +

+ + + + + +

The server's SSL certificate has expired.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Expired. +

+ + + + + +

The server's SSL certificate is not yet valid.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.NotActivated. +

+ + + + + +

The server's SSL certificate did not match its hostname.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.HostnameMismatch. +

+ + + + + +

The server's SSL certificate does not have the expected + fingerprint.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch. +

+ + + + + +

The server's SSL certificate is self-signed.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.SelfSigned. +

+ + + + + +

There was some other error validating the server's SSL + certificate.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Invalid. +

+ + + + + +

The server's SSL certificate has been revoked.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Revoked. +

+ + + + + +

The server's SSL certificate uses an insecure algorithm, + or is cryptographically weak.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Insecure. +

+ + + + + +

The length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.LimitExceeded +

+ + + + + + +

Emitted when an error occurs that renders this connection unusable. +

+ +

Whenever this signal is emitted, it MUST immediately be followed by + a StatusChanged signal with status + Connection_Status_Disconnected and an appropriate reason + code.

+ +

Connection managers SHOULD emit this signal on disconnection, but + need not do so. Clients MUST support connection managers that emit + StatusChanged(Disconnected, ...) without first emitting + ConnectionError.

+ + +

This signal provides additional information about the reason + for disconnection. The reason for connection is always + straightforward - it was requested - so it does not need further + explanation. However, on errors, it can be useful to provide + additional information.

+ +

The Connection_Status_Reason is not given + here, since it will be signalled in + StatusChanged. A reasonable client + implementation would be to store the information given by this + signal until StatusChanged is received, at which point the + information given by this signal can be used to supplement the + StatusChanged signal.

+ + + + + + The name of a D-Bus error describing the error that occurred, + which may correspond to a + Connection_Status_Reason, or may be a more + specific Telepathy error + (such as + org.freedesktop.Telepathy.Error.ConnectionRefused + for Connection_Status_Reason_Network_Error) + or a protocol-specific or connection-manager-specific error in a + suitable namespace. + + + For instance, a SIP connection manager could signal + "402 Payment Required" as an error in a + connection-manager-specific namespace, or a link-local + XMPP implementation that used Avahi could provide the error + given to it by the avahi-daemon. + + + + + + +

Additional information about the error, which may include + the following well-known keys:

+ +
+
debug-message (s)
+
Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances
+
user-requested (b), expected-hostname (s), certificate-hostname (s)
+
The same details defined in TLS_Certificate_Rejection.
+
+ + + + + + + + + + An integer indicating the new status, as defined by ConnectionStatus + + + + + + An integer indicating the reason for the status change, as defined + by ConnectionStatusReason + + + + + Emitted when the status of the connection changes. All states and + reasons have numerical values, as defined in ConnectionStatus + and ConnectionStatusReason. + + + + + +

The same string that would be returned by + InspectHandles. As a special case, + this is always present in the result of GetContactAttributes, + whether it was explicitly requested or not.

+ + + + + + +

Register a client's interest in notifications related to one or + more interfaces.

+ +

Groups of notifications are identified by a token which is either + a D-Bus interface name, or a string that starts with a D-Bus + interface name. The meaning of each token is given by that D-Bus + interface, which MUST define it in its documentation.

+ + +

Initially, all interests are in entire interface, but allowing + other strings allows subscription to part of an interface; for + instance, an interest in ...MailNotification/count could track + the number of messages without caring about their detailed + content.

+ + +

For each token with which this method interacts, the + Connection tracks an "interest count" (like a reference count) for + each unique bus name that has called this method. When a client + calls this method, for each token, the interest count for its + unique bus name is incremented; when + RemoveClientInterest is called, + all interest counts for that unique bus name are decremented. + If the unique bus name leaves the bus (for instance, if the + client crashes or exits), all interest counts for that unique bus + name are set to zero.

+ +

The Connection can then use these reference counts to + avoid subscribing to protocol-level notifications unless at least + one client has a non-zero interest count for the relevant + token.

+ + +

This method exists to reduce memory and network overhead when + there is no active subscription.

+ +

One situation where this is useful is Location: on XMPP, location updates are received + over PEP. If the Connection advertises the + geoloc+notify capability, it will be sent location + updates for all contacts. To avoid consuming resources for this, + the connection should avoid advertising that capability until + a client has expressed an interest in contacts' locations.

+ +

Another example of a protocol that benefits from this method is + the Google XMPP Mail Notification extension, which can be used + to implement MailNotification. In this protocol, the CM + receives a notification that something has changed, but to get + more information, the CM must request this information. Knowing + that nobody is currently interested in this information, the CM + can avoid generating useless network traffic. Similarly, the CM + may free the list of unread messages to reduce memory overhead.

+ + +

If this method is called for an interface that might require + protocol-level subscription, but the connection cannot set up + that subscription yet (for instance because the + Status is not Connected yet), the + Connection MUST remember the client's interest, and attempt to + subscribe to the appropriate protocol feature when this becomes + possible.

+ +

Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.

+ + +

The only reason it could fail is if it's unimplemented, in which + case the only thing the client can usefully do is to proceed as if + it had succeeded.

+ + + + + +

Interfaces or parts of interfaces in which to register an + interest, represented by either a + DBus_Interface, or a string prefixed with a + DBus_Interface.

+ +

If the Connection does not support one of these tokens, this + is not considered to be an error; the unsupported token is + simply ignored.

+ + + + + + + +

Release an interest registered using + AddClientInterest. See that + method's documentation for details.

+ +

Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.

+ + +

The only reasons it could fail are if it's unimplemented, or if + the client's reference-counting is wrong and it has tried to + remove a client interest that it did not add. In both cases, + there's nothing the client could do about it.

+ + + + + +

Interfaces or parts of interfaces that were previously passed to + AddClientInterest.

+ + + + + + + +

True if handles last for the whole lifetime of the Connection. + This SHOULD be the case in all connection managers, but clients + MUST interoperate with older connection managers + (which reference-count handles).

+ + + + +

This models a connection to a single user account on a communication + service. Its basic capability is to provide the facility to request and + receive channels of differing types (such as text channels or streaming + media channels) which are used to carry out further communication.

+ +

In order to allow Connection objects to be discovered by new clients, + the object path and well-known bus name MUST be of the form + /org/freedesktop/Telepathy/Connection/cmname/proto/account + and + org.freedesktop.Telepathy.Connection.cmname.proto.account + where:

+ +
    +
  • cmname is the same + Connection_Manager_Name that appears + in the connection manager's object path and well-known bus name
    • +
  • proto is the Protocol name as seen in + ListProtocols, + but with "-" replaced with "_" to get a valid + object path/bus name
    • +
  • account is some non-empty sequence of ASCII letters, + digits and underscores not starting with a digit
    • +
+ +

account SHOULD be formed such that any valid distinct + connection instance on this protocol has a distinct name. This + might be formed by including the server name followed by the user + name (escaped via some suitable mechanism like telepathy-glib's + tp_escape_as_identifier() function to preserve uniqueness); on + protocols where connecting multiple times is permissable, a + per-connection identifier might be necessary to ensure + uniqueness.

+ +

Clients MAY parse the object path to determine the connection + manager name and the protocol, but MUST NOT attempt to parse the + account part. Connection managers MAY use any unique string + for this part.

+ +

As well as the methods and signatures below, arbitrary interfaces may be + provided by the Connection object to represent extra connection-wide + functionality, such as the Connection.Interface.SimplePresence for + receiving and + reporting presence information, and Connection.Interface.Aliasing for + connections where contacts may set and change an alias for themselves. + These interfaces can be discovered using the + GetInterfaces method.

+ +

Contacts, rooms, and server-stored lists (such as subscribed contacts, + block lists, or allow lists) on a service are all represented by + immutable handles, which are unsigned non-zero integers which are + valid only for the lifetime of the connection object, and are used + throughout the protocol where these entities are represented, allowing + simple testing of equality within clients.

+ +

Zero as a handle value is sometimes used as a "null" value to mean + the absence of a contact, room, etc.

+ +

Handles have per-type uniqueness, meaning that + every (handle type, handle number) tuple is guaranteed to be unique within + a connection and that a handle alone (without its type) is meaningless or + ambiguous. Connection manager implementations should reference count these + handles to determine if they are in use either by any active clients or any + open channels, and may deallocate them when this ceases to be true. Clients + may request handles of a given type and identifier with the + RequestHandles method, inspect the entity + identifier with the InspectHandles + method, keep handles from being released with + HoldHandles, and notify that they are no + longer storing handles with + ReleaseHandles.

+ + + Previously, the account part of + Connection bus names/object paths was allowed to have more than one + component (i.e. contain dots or slashes), resulting in Connection + bus names and object paths with more than 7 components. We now restrict + Connection bus names/object paths to have exactly 7 + components. + + The Requests and Contacts interfaces + are now mandatory. Their functionality will be merged into the main + Connection interface at some point in future. + + + + diff --git a/spec/Connection_Future.xml b/spec/Connection_Future.xml new file mode 100644 index 0000000..6b5291e --- /dev/null +++ b/spec/Connection_Future.xml @@ -0,0 +1,110 @@ + + + Copyright © 2009 Collabora Limited + 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.

+ + + + + + (as a draft) + + + + The "primary" interface implemented by an object attached + to a connection. For example, a Gabble plugin implementing + fine-grained control of XEP-0016 privacy lists might expose an object + implementing com.example.PrivacyLists. + + + + + The object path of the sidecar, exported by the same bus + name as the Connection to which it is attached. + + + Immutable properties of the sidecar. + + + +

Request an object with a particular interface providing additional + connection-specific functionality, together with its immutable + properties. These will often be implemented by plug-ins to the + connection managers; for example, support for an XMPP XEP for which + no generic Telepathy interface exists might be implemented by a + Gabble plugin exposing a sidecar with a particular interface.

+ +

This method may be called at any point during the lifetime of a + connection, even before its Connection_Status + changes to Connected. It MAY take a long time to + return—perhaps it needs to wait for a connection to be established + and for all the services supported by the server to be discovered + before determining whether necessary server-side support is + available—so callers SHOULD override the default method timeout (25 + seconds) with a much higher value (perhaps even MAX_INT32, meaning + “no timeout” in recent versions of libdbus).

+ + +

There is an implicit assumption that any connection + manager plugin will only want to export one “primary” object per + feature it implements, since there is a one-to-one mapping between + interface and object. This is reasonable since Sidecars are + (intended to be) analogous to extra interfaces on the connection, + providing once-per-connection shared functionality; it also makes + client code straightforward (look up the interface you care about + in a dictionary, build a proxy object from the value). More + “plural” plugins are likely to want to implement new types of + Channel + instead.

+ + + + + + The requested sidecar is not implemented by this connection manager, + or a necessary server-side component does not exist. (FIXME: split + these two errors out? Then again, once we list the guaranteed and + possible sidecars on a Protocol object, clients can tell the + difference themselves, because they shouldn't be calling this in the + first case.) + + + + + + A server-side component needed by the requested sidecar reported it + is currently too busy, or did not respond for some + implementation-defined time. The caller may wish to try again later. + + + + + + The connection was disconnected while the sidecar was being set up. + + + + + + diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml new file mode 100644 index 0000000..497c6d0 --- /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_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml new file mode 100644 index 0000000..9675771 --- /dev/null +++ b/spec/Connection_Interface_Aliasing.xml @@ -0,0 +1,185 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + A dictionary whose keys are contact handles and whose + values are aliases. + + + + + + + A pair (contact handle, alias) as seen in the + AliasesChanged signal. + + + + + + + + + + An array containing structs of: +
    +
  • the handle representing the contact
    • +
  • the new alias
    • +
+ + + + Signal emitted when a contact's alias (or that of the user) is changed. + + + + + +

The aliases of contacts on this connection may be changed by the + user of the service, not just by the contacts themselves. This is + the case on Jabber, for instance.

+

It is possible that aliases can be changed by the contacts too - + which alias takes precedence is not defined by this + specification, and depends on the server and/or connection manager + implementation.

+

This flag only applies to the aliases of "globally valid" contact + handles. At this time, clients should not expect to be able to + change the aliases corresponding to any channel-specific + handles. If this becomes possible in future, a new flag will + be defined.

+ + + + + + + An integer with a bitwise OR of flags from ConnectionAliasFlags + + + + Return a bitwise OR of flags detailing the behaviour of aliases on this + connection. + + + + + + + + + An array of handles representing contacts + + + + + A list of aliases in the same order as the contact handles + + + + Request the value of several contacts' aliases at once. + + + + + + + + + + + + An array of handles representing contacts + + + + + A dictionary mapping contact handles to aliases + + + + Request the value of several contacts' aliases at once. This SHOULD + only return cached aliases, falling back on the contact identifier + (i.e. the string corresponding to the handle) if none is present. Also + if there was no cached alias, a request SHOULD be started of which the + result is later signalled by + AliasesChanged. + + + + + + + + + + A dictionary mapping integer handles of contacts + to strings of the new alias to set. + + + + Request that the alias of the given contact be changed. Success will be + indicated by emitting an AliasesChanged + signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is + not set, this method will only ever succeed if the contact is the + user's own handle (as returned by Connection.GetSelfHandle). + + + + + + + + + + + + +

The same string that would be returned by + GetAliases + (always present with some value, possibly the + same as Connection/contact-id, if information from the + Aliasing interface was requested) +

+ + + + +

An interface on connections to support protocols where contacts have an + alias which they can change at will. Provides a method for the user to set + their own alias, and a signal which should be emitted when a contact's + alias is changed or first discovered.

+ +

On connections where the user is allowed to set aliases for contacts and + store them on the server, the GetAliasFlags + method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the + SetAliases method may be called on contact + handles other than the user themselves.

+ +

Aliases are intended to be used as the main displayed name for the + contact, where available.

+ + + + diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml new file mode 100644 index 0000000..704263c --- /dev/null +++ b/spec/Connection_Interface_Anonymity.xml @@ -0,0 +1,165 @@ + + + + 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.

+ + + + (as stable API) + + +

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 Show_Client_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 + Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info + in SupportedAnonymityModes to indicate + its support for explicitly hiding and publicising client information. +

+ + + + + +

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.Error.WouldBreakAnonymity + error. + Any client that sets AnonymityModes + SHOULD also set this property first (rather than accepting the CM's + default value).

+ + + + + +

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

+ + + + + 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_Avatars.xml b/spec/Connection_Interface_Avatars.xml new file mode 100644 index 0000000..3b9290e --- /dev/null +++ b/spec/Connection_Interface_Avatars.xml @@ -0,0 +1,516 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005-2008 Nokia Corporation + Copyright (C) 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.

+ + + + + + strengthened uniqueness requirements + so (CM name, protocol, token) is unique; previously only + (our Account, remote contact identifier, token) was required to be + unique + +

An opaque token chosen by the connection manager, representing + a particular avatar.

+ + +

Because avatars can be relatively large images, most protocols + provide a way to detect whether an old avatar is still valid, + or whether an avatar has changed, without pushing the actual + avatar data to all clients.

+ + +

The connection manager MUST choose these tokens in a way that + makes it highly unlikely that two different avatars with the same + connection manager and protocol will have the same token.

+ + +

This means that clients MAY use the triple + (Connection_Manager_Name, + Protocol, avatar token) as a key for + their avatar cache. For instance, an avatar for a + telepathy-gabble Jabber contact might be stored in a file + .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.

+ + +

For instance, some protocols (like XMPP) identify avatars by a + hash of the avatar data; in this case, the hash can be used as the + avatar token.

+ +

Some protocols identify avatars by the timestamp of the last + change to the avatar; in these protocols it would be necessary for + the connection manager to encode both the timestamp and the + contact's identifier into the avatar token in order to ensure + uniqueness.

+ +

This token SHOULD be kept short and reasonably suitable for use + in a filename, but MAY contain any UTF-8 character (so clients using + avatar tokens in filenames MUST be prepared to escape characters + that are not valid in filenames). Connection managers for protocols + where tokens would otherwise become inconveniently large or contain + many unsuitable characters SHOULD hash the identifying data to + generate the token.

+ + + + + A dictionary whose keys are contact handles and whose + values are avatar tokens. + + + + + + + + An integer handle for the contact whose avatar has changed + + + + + Unique token for their new avatar + + + + Emitted when the avatar for a contact has been updated, or first + discovered on this connection. If the token differs from the token + associated with the client's cached avatar for this contact, the new + avatar should be requested with + RequestAvatars. + + + + + + + The contact whose avatar has been retrieved + + + + + The token corresponding to the avatar + + + + + An array of bytes containing the image data + + + + + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + + + + Emitted when the avatar for a contact has been retrieved. + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + An array of supported MIME types (e.g. "image/jpeg"). + Clients MAY assume that the first type in this array is preferred. + This property cannot change after the Connection goes to the Connected + state. + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + The minimum height in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + The minimum width in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + + + + + + + The recommended height in pixels of an avatar on this protocol, or 0 if + there is no preferred height. + This property cannot change after the Connection goes to the Connected + state. + + + In XMPP a recommended width is given by the protocol specification; + in proprietary protocols, using the same avatar size as the + proprietary client is likely to lead to the best display to other + users. + + + + + + + + The recommended width in pixels of an avatar on this protocol, or 0 if + there is no preferred width. + This property cannot change after the Connection goes to the Connected + state. + + + The rationale is the same as for + RecommendedAvatarHeight. + + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + The maximum height in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + The maximum width in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + + + + + Fall back to calling + GetAvatarRequirements if getting this + property fails. + + The maximum size in bytes of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + + + + + Use GetAll to retrieve the + D-Bus properties on this interface, falling back to this method + on failure. + + + An array of supported MIME types (eg image/jpeg) + + + + + The minimum image width in pixels + + + + + The minimum image height in pixels + + + + + The maximum image width in pixels, or 0 if there is no limit + + + + + The maximum image height in pixels, or 0 if there is no limit + + + + + The maximum image size in bytes, or 0 if there is no limit + + + + Get the required format of avatars on this connection. + + + + + + + + + + + + + An array of handles representing contacts + + + + + An array of avatar tokens or empty strings (if no avatar is set) in the + same order as the given array of contact handles + + + Use GetKnownAvatarTokens + instead. + + Get the unique tokens for all of the given contacts' avatars. + + Using this method in new Telepathy clients is deprecated; use + GetKnownAvatarTokens instead. + + + + + + + + + + + + + + An array of handles representing contacts + + + + + A dictionary of handles mapped to avatar tokens, containing only + the known avatar tokens. + + + + Get the unique tokens for the given contacts' avatars. These tokens + can be persisted across connections, and should be used by the client + to check whether the avatars have been updated. For handles other than + the self handle, only tokens that are already known are returned; an + empty token means the given contact has no avatar. However, a CM must + always have the tokens for the self handle if one is set (even if it is + set to no avatar). On protocols where the avatar does not persist + between connections, a CM should omit the self handle from the returned + map until an avatar is explicitly set or cleared. + + + + + + + + + + + + + + An integer handle for the contact to request the avatar for + + + + + An array of bytes containing the image data + + + + + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + + + Use RequestAvatars + instead. + + Request the avatar for a given contact. Using this method in new + Telepathy clients is deprecated; use RequestAvatars instead. + + + + + + + + + The contact does not currently have an avatar. + + + + + + + + + The contacts to retrieve avatars for + + + + Request avatars for a number of contacts. The + AvatarRetrieved signal is emitted for + each avatar retrieved. If the handles are valid but retrieving an + avatar fails (for any reason, including the contact not having an + avatar) the AvatarRetrieved signal is not emitted for that contact. + + + + + + + + + + + An array of bytes representing the avatar image data + + + + + A string representing the image MIME type + + + + + The string token of the new avatar + + + + Set a new avatar image for this connection. The avatar image must + respect the requirements obtained by + GetAvatarRequirements. + + + + + + + + + + + + + + Remove the avatar image for this connection. + + + + + + + + + +

The same string that would be returned by + GetKnownAvatarTokens + (omitted from the result if the contact's avatar token is not known, + present as an empty string if the contact is known not to have + an avatar). Unlike in the + GetKnownAvatarTokens + method, the avatar tokens for the self handle aren't required to be + present. This attribute should not be used to determine whether or + not the Avatar needs to be set. +

+ + + + +

An interface for requesting avatars for contacts on a given connection, + receiving notification when avatars are changed, and publishing your own + avatar.

+ +

Avatars are identified by a string, the Avatar_Token, + which represents a particular avatar. Tokens MUST be chosen by the + connection manager in such a way that the triple + (Connection_Manager_Name, Protocol, + Avatar_Token) uniquely identifies an avatar. + An empty token means that an avatar has not been set for this contact, and + a changed token implies the contact's avatar has changed, but the strings + should otherwise be considered opaque by clients.

+ +

A client should use GetKnownAvatarTokens + to request the tokens for the + avatars of all the contacts it is interested in when it connects. The + avatars can then be requested using + RequestAvatars for the contacts. Clients + should bind to the AvatarUpdated signal and + request a new copy of + the avatar when a contacts' avatar token changes. Clients should cache the + token and data of each contact's avatar between connections, to avoid + repeatedly retrieving the same avatar.

+ +

To publish an avatar, a client should use + SetAvatar to provide an image which meets + the requirements returned by the + GetAvatarRequirements + function. On some protocols the avatar is stored on the server, so setting + the avatar is persistent, but on others it is transferred via a peer to + peer mechanism, so needs to be set every connection. Hence, on every + connection, clients should inspect the avatar token of the connection's + self handle using GetKnownAvatarTokens; if + the self handle is not in the + returned map, the client should re-set the avatar. If the self handle's + avatar token is known, but the avatar has been changed locally since the + last connection, the client should upload the new avatar; if the avatar has + not changed locally, then the client should download the avatar from the + server if its token differs from the that of the local avatar.

+ +

To remove the published avatar on protocols which have persistent avatars, + a client should use the ClearAvatar method. + This method can safely be used even if there is no avatar for this + connection.

+ + + + diff --git a/spec/Connection_Interface_Balance.xml b/spec/Connection_Interface_Balance.xml new file mode 100644 index 0000000..76f9040 --- /dev/null +++ b/spec/Connection_Interface_Balance.xml @@ -0,0 +1,111 @@ + + + Copyright © 2009 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.

+ + + + (as stable API) + + +

In many real-time communication services the user can pay for certain + services, typically calls to the + PSTN, + in advance. In (at least) Skype, it's possible to query the current + balance in a machine-readable way.

+ + + + +

An amount of money in a specified currency. For example, + 3.21 British pounds would conventionally be represented by + (Amount = 321, Scale = 2, + Currency = "GBP"), but could be represented by + (Amount = 3210, Scale = 3, + Currency = "GBP") in a service that records + balance in units of 0.001 pounds.

+ +

As a special case, if Amount = 0, + Scale = 2**32 - 1 (i.e. the largest possible + 32-bit unsigned integer) and Currency = "", this + indicates an unknown amount.

+ + + + +

The amount, expressed as a fixed-point number with decimal scale + defined by the Scale field; for instance, an + Amount value of 1234 with Scale of + 2 represents 12.34 in the currency unit given by the + Currency field.

+ + + + +

The decimal scale for the fixed point value of the + Amount field, defining the number of rightmost decimal + digits from the integer value which form the fractional part of the + resulting currency value.

+ +

As well as defining the interpretation of Amount, user + interfaces may use this value to determine the precision with which + to display the amount.

+ + + + + The currency code represented by this amount, which SHOULD be an + international currency code such as "EUR", "USD", + or "JPY" if possible. An empty string can be used to + indicate that the currency is not known. + + + + + + +

The user's balance on the account corresponding to this Connection. + A negative amount may be possible on some services, and indicates + that the user owes money to the service provider.

+ +

On initial connection, this property may have an unknown + value, represented by Amount = 0, + Scale = 2**32 - 1 (the largest possible 32-bit + unsigned integer) and Currency = "".

+ + + + + +

Emitted when the user's balance has changed.

+ + + + +

The new value of the AccountBalance + property.

+ + + + + + + diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml new file mode 100644 index 0000000..8e5eb33 --- /dev/null +++ b/spec/Connection_Interface_Capabilities.xml @@ -0,0 +1,254 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + +

An interface for connections where it is possible to know what channel + types may be requested before the request is made to the connection + object. Each capability represents a commitment by the connection + manager that it will ordinarily be able to create a channel when given + a request with the given type and handle.

+ +

Capabilities pertain to particular contact handles, and represent + activities such as having a text chat or a voice call with the user. + The activities are represented by the D-Bus interface name of the + channel type for that activity.

+ +

The generic capability flags are defined by + Connection_Capability_Flags.

+ +

In addition, channel types may have type specific capability flags of + their own, which are described in the documentation for each channel + type.

+ +

This interface also provides for user interfaces notifying the + connection manager of what capabilities to advertise for the user. This + is done by using the + AdvertiseCapabilities method, and deals + with the + interface names of channel types and the type specific flags pertaining + to them which are implemented by available client processes.

+ + + Previously, this interface + also expressed capabilities of the connection itself, indicating what + sorts of channels could be requested (for instance, the ability to + open chatroom lists or chatrooms). However, this was never very + well-defined or consistent, and as far as we know it was never + implemented correctly. This usage is now deprecated. + + Client implementations SHOULD use ContactCapabilities + instead. + Connection managers implementing + Capabilities MUST implement ContactCapabilities too. + + + + + The given channel type and handle can be given to RequestChannel + to create a new channel of this type. + + + + + The given contact can be invited to an existing channel of this type. + + + + + + A pair (channel type, type-specific flags) as passed to + AdvertiseCapabilities on the + Capabilities interface. + + + + + + A struct (contact handle, channel type, generic flags, + type-specific flags) representing a capability posessed by a contact, + as returned by GetCapabilities on the + Capabilities interface. + + + + + + + + A struct (contact handle, channel type, old generic flags, + new generic flags, old type-specific flags, new type-specific flags) + representing a change to one of a contact's capabilities, as seen in the + CapabilitiesChanged signal on the + Capabilities interface. + + + + + + + + + + + + An array of structures containing: +
    +
  • a string channel type
    • +
  • a bitwise OR of type specific capability flags
    • +
+ + + + + An array of D-Bus interface names of channel types to remove + + + + + An array of structures describing the current capabilities containing: +
    +
  • a string channel type
    • +
  • a bitwise OR of type specific capability flags
    • +
+ + + +

Used by user interfaces to indicate which channel types they are able + to handle on this connection. Because these may be provided by + different client processes, this method accepts channel types to add + and remove from the set already advertised on this connection. The type + of advertised capabilities (create versus invite) is protocol-dependent + and hence cannot be set by the this method. In the case of a client + adding an already advertised channel type but with new channel type + specific flags, the connection manager should simply add the new flags + to the set of advertised capabilities.

+ +

Upon a successful invocation of this method, the + CapabilitiesChanged + signal will be emitted for the user's own handle ( Connection.GetSelfHandle) + by the connection manager to indicate the changes + that have been made. This signal should also be monitored to ensure + that the set is kept accurate - for example, a client may remove + capabilities or type specific capability flags when it exits + which are still provided by another client.

+ +

On connections managed by the ChannelDispatcher, + this method SHOULD NOT be used by clients other than the + ChannelDispatcher itself.

+ + + + + + + + + + + An array of structures containing: +
    +
  • an integer handle representing the contact
    • +
  • a string channel type
    • +
  • a bitwise OR of the contact's old generic capability flags
    • +
  • a bitwise OR of the contact's new generic capability flags
    • +
  • a bitwise OR of the contact's old type specific capability flags
    • +
  • a bitwise OR of the contact's new type specific capability flags
    • +
+ + + +

Announce that there has been a change of capabilities on the + given handle.

+ +

If the handle is zero, the capabilities refer to the connection + itself, in some poorly defined way. This usage is deprecated and + clients should ignore it.

+ + + + + + +

An array of contact handles for this connection.

+ +

This may include zero, which originally meant a query for + capabilities available on the connection itself. This usage + is deprecated; clients SHOULD NOT do this, and connection managers + SHOULD proceed as though zero had not been present in this + list.

+ + + + + An array of structures containing: +
    +
  • an integer handle representing the contact
    • +
  • a string channel type
    • +
  • a bitwise OR of generic capability flags for the type
    • +
  • a bitwise OR of type specific capability flags for the type
    • +
+ + + + Returns an array of capabilities for the given contact handles. + + + + + + + The handle does not represent a contact and is not zero + + + + + + + + +

The same structs that would be returned by + GetCapabilities + (all of them will redundantly have the contact's handle as the + first member). Omitted from the result if the contact's capabilities + are not known; present in the result as an empty array if the + contact is known to have no capabilities at all.

+ + + + + + diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml new file mode 100644 index 0000000..99a3602 --- /dev/null +++ b/spec/Connection_Interface_Cellular.xml @@ -0,0 +1,131 @@ + + + + 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.

+ + + + (as stable API) + + +

This interface is for various cellular things (GSM and/or CDMA) 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.

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

+ + + + + + 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). If + OverrideMessageServiceCentre is + False, this property's value should be ignored by the CM + in favour of the SIM's default SMSC.

+ + + + + +

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

Determines whether SMSes containing characters that do not fit into + a 7‐bit GSM character set should be sent as UCS‐2, or lossily + recoded. If False (which SHOULD be the default), + messages will be sent with no loss of fidelity (at the potential + financial cost of using twice as many SMSes); if True, + the message will be recoded in an implementation‐specific way to fit + into a country‐specific GSM reduced character set.

+ + + + + diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 0000000..9790856 --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,218 @@ + + + Copyright (C) 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 stable API) + + + +

An interface on connections to support protocols which allows users to + subscribe to the client types of their contacts.

+ +

One can connect to instant messaging networks on a huge variety of + devices, from PCs, to phones to consoles. It can be useful for users + to know what kind of device a contact is using so that he or she + can decide not to send that big file or start a video chat. This + interface exposes exactly this information for clients to display.

+ +

The client types are represented in strings, using the values + + documented by the XMPP registrar with some additional types + added for other protocols. A contact can set one or more client types + so this interface returns a list of strings to denote client types + for a contact. The well-known client types to be used are:

+ +
    +
  • bot
    • +
  • console (minimal non-GUI client used on dumb terminals or + text-only screens, not a games console)
    • +
  • handheld
    • +
  • pc
    • +
  • phone
    • +
  • web
    • + +
+ +

If the empty list is given as the client types, this means that + details about the contact's client types are unknown. If there are + multiple resources of a contact online at one point in time, the + client types of the most available resource will be returned. In + other words, the returned client types are those for the resource whose + presence will be retreived using the + SimplePresence + interface.

+ +

For example, if a contact has two resources:

+ +
    +
  • their phone, with presence "available"; and
    • +
  • their pc, with presence "busy";
    • +
+ +

then the methods in this interface will return an array (with + one element: "phone") as the client types because that is the more + available resource. If at some later time the contact's phone's presence + changes to "away", the + ClientTypesUpdated signal will + notify that the contact's client types attribute has changed from + ["phone"] to ["pc"], + because "busy" is a more available presence than "away".

+ + + + + + A mapping from contact handle to client types. + + + + A contact. + + + + + The contact's client types as documented earlier in this interface. + + + + + + + Return the client types of the given contacts, if they are + already known. If any of the given contacts' client types are + not known, request their current client types, but return + immediately without waiting for a reply; if a reply with a + non-empty client type array is later received for those + contacts, the + ClientTypesUpdated signal will + be emitted for them. + + + This method is appropriate for "lazy" client type finding, for instance + displaying the client types (if available) of everyone in your contact + list. + + + + + + The contacts whose client types should be returned or signalled. + + + + + + The contacts' client types, if already known. Contacts whose client + types are not already known are omitted from the mapping; contacts known + to have no client type information appear in the mapping with an empty + list. + + + + + + + + + + + + Return the current client types of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + + + + + + The contact whose client types should be returned. + + + + + + The contact's client types. It MAY be empty, indicating that no client + type information was found. + + + + + + + + + + The requested contact does not allow the local user to see their + client type information. + + + + + + + + Emitted when a contact's client types change or become known. + + + + + The contact. + + + + + The contact's client types, or an empty list to indicate that nothing + is known about the contact's client types. + + + + + + +

The same mapping that would be returned by + GetClientTypes for this contact. + Omitted from the result if the contact's client types are not + known.

+ + + + + A string representing a single client type of a + contact. + + + + + diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml new file mode 100644 index 0000000..31343de --- /dev/null +++ b/spec/Connection_Interface_Communication_Policy.xml @@ -0,0 +1,163 @@ + + + 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 +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. + + + + (draft 1) + + + +

+ This interface supports controlling which contacts are allowed + to initiate text chats, incoming calls, and other forms of + communication as supported by the underlying protocol. The + policies supported for different communication methods on this + connection are listed in the + SupportedPolicies property. The + current configuration is held in + ActivePolicies; it can be modified + using SetPolicy, and changes + are signalled by PolicyChanged. +

+ + + + + A mapping of communication methods (channel types), and their + associated policy. + + + + + The channel interface with the policy. + + + + + + The active policy for this channel type. + + + + + + + The communication policies supported by this connection. + + + + + +

The active communication policies on this + connection. Communication methods that are not in this + mapping are considered open.

+ +

For example, to allow incoming calls only from contacts + buddy list, and to allow text messages from anyone, + the policy would look like this:

+ + 
+{
+    'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open,
+    'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List
+}
+
+ +

Changes to this property are signalled by + PolicyChanged.

+ + + + + + Set a policy for a communication method (channel + type). Depending on the server or protocol, more than one + communication method could be bound to the same policy, if + calling this method on one channel type changes the policy on + another channel type, the PolicyChanged + signal that would follow would include all the channel types + that have an altered policy. + + + + The channel type to set the policy for. + + + + + The policy to set for this channel. + + + + + + + ActivePolicies has + changed. This occurs when the server unilaterally changed the + policy or SetPolicy has been + called. + + + + A subset of the active policies that have changed. + + + + + + +

The communication methods (channel types), and the policies + that can be applied to them. This is server and protocol + dependant.

+ +

Grouped channel types will always have the same policy applied + to them.

+ + + Different protocols have different limitations to the + granularity of communication policies. One protocol might be + able to set a different policy for VoIP calls and text chat, + while another protocol might only be able to set one policy + to both VoIP and text chat. + + + + + A list of channel interfaces that support these policies. + + + + + A list of supported policies. + + + + + + diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml new file mode 100644 index 0000000..fb13c37 --- /dev/null +++ b/spec/Connection_Interface_Contact_Capabilities.xml @@ -0,0 +1,306 @@ + + + Copyright (C) 2005, 2006, 2008 Collabora Limited + Copyright (C) 2005, 2006, 2008 Nokia Corporation + Copyright (C) 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.

+ + + + (as stable API) + + +

Contact capabilities describe the channel classes which may be + created with a given contact in advance of attempting to create a + channel. Each capability represents a commitment by the + connection manager that it will ordinarily be able to create a channel + with a contact when given a request with the properties defined by the + channel class.

+ +

Capabilities pertain to particular contact handles, and represent + activities such as having a text chat, a voice call with the user or a + stream tube of a defined type.

+ +

This interface also enables user interfaces to notify the connection + manager what capabilities to advertise for the user to other contacts. + This is done by using the + UpdateCapabilities method.

+ + +

XMPP is a major user of this interface: XMPP contacts will not, + in general, be callable using VoIP unless they advertise suitable + Jingle capabilities.

+ +

Many other protocols also have some concept of capability flags, + which this interface exposes in a protocol-independent way.

+ + + + + + A structure representing the capabilities of a single client. + + + + + For implementations of the Client + interface, the well-known bus name name of the client; for any other + process, any other reversed domain name that uniquely identifies it. + + + + + + An array of channel classes that can be handled by this client. + This will usually be a copy of the client's HandlerChannelFilter + property. + + + + + + An array of client capabilities supported by this client, to be + used by the connection manager to determine what capabilities to + advertise. This will usually be a copy of the client's Capabilities + property. + + + + + + +

Alter the connection's advertised capabilities to include + the intersection of the given clients' capabilities with what the + connection manager is able to implement.

+ +

On connections managed by the ChannelDispatcher, processes other + than the ChannelDispatcher SHOULD NOT call this method, and the + ChannelDispatcher SHOULD use this method to advertise the + capabilities of all the registered Client.Handler + implementations.On connections not managed by the ChannelDispatcher, + clients MAY use this method directly, to indicate the channels they + will handle and the extra capabilities they have.

+ +

Upon a successful invocation of this method, the connection manager + will only emit the + ContactCapabilitiesChanged signal + for the user's SelfHandle + if, in the underlying protocol, the new capabilities are distinct + from the previous state.

+ + +

The connection manager will essentially intersect the provided + capabilities and the channel classes it implements. Therefore, + certain properties which are never fixed for a channel class + (such as the target handle, or the Parameters property of a tube + channel) will almost certainly not be advertised.

+ + +

This method MAY be called on a newly-created connection while it + is still in the DISCONNECTED state, to request that when the + connection connects, it will do so with the appropriate + capabilities. Doing so MUST NOT fail.

+ + + + +

The capabilities of one or more clients.

+ +

For each client in the given list, any capabilities previously + advertised for the same client name are discarded, then replaced by + the capabilities indicated.

+ +

As a result, if a client becomes unavailable, this method SHOULD + be called with a Handler_Capabilities structure + containing its name, an empty list of channel classes, and an + empty list of capabilities. When this is done, the connection + manager SHOULD free all memory associated with that client name.

+ + +

This method takes a list of clients so that + when the channel dispatcher first calls it (with a list of all + the Handlers that are initially available), the changes can be + made atomically, with only one transmission of updated + capabilities to the network. Afterwards, the channel dispatcher + will call this method with a single-element list every time + a Handler becomes available or unavailable.

+ + +

The connection manager MUST ignore any channel classes and client + capabilities for which there is no representation in the protocol + or no support in the connection manager.

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

An array of contact handles for this connection.

+ +

The handle zero MUST NOT be included in the request.

+ + + + +

A map from contact handles to lists of requestable channel + classes, representing the channel requests that are expected + to succeed for that contact.

+ +

Contacts listed among Handles whose capabilities are unknown + SHOULD be omitted from this map; contacts known to have an empty + set of capabilities SHOULD be included in the keys of this map, + with an empty array as the corresponding value.

+ + + +

Returns an array of requestable channel classes for the given + contact handles, representing the channel requests that are + expected to succeed.

+ + + + + + The handle does not represent a contact. Zero is always invalid. + + + + + + + + + All the capabilities of the contacts + + + +

Announce that there has been a change of capabilities on the + given handles. A single signal can be emitted for several + contacts.

+ + +

The underlying protocol can get several contacts' capabilities at + the same time.

+ + + + + + + A mapping from contact handle to their capabilities. + + + + A contact handle. + + + + +

The contact's capabilities. These should be represented + in the same way as in RequestableChannelClasses, + except that they may have more fixed properties or fewer allowed + properties, to represent contacts who do not have all the + capabilities of the connection.

+ +

In particular, requestable channel classes for channels with + target handle type Contact MUST list TargetHandleType among their fixed properties when + they appear here, and clients MAY assume that this will be the + case.

+ + +

This matches the initial implementations - service-side in + telepathy-gabble, and client-side in telepathy-qt4 - and means + that clients can use exactly the same code to interpret + RequestableChannelClasses and contact capabilities.

+ + +

Channel classes with target handle type Handle_Type_Contact + indicate that a request that matches the channel class, and also + either has the contact's handle as TargetHandle or the contact's identifier as + TargetID, can be expected to succeed. Connection + managers SHOULD NOT include the TargetHandle or TargetID as a + fixed property in contact capabilities.

+ + +

This makes one channel class sufficient to describe requests via + TargetHandle or TargetID, and is necessary in order to allow + clients to interpret RequestableChannelClasses and contact + capabilities with the same code.

+ + +

Channel classes with target handle type Handle_Type_Room or + Handle_Type_None indicate that if a channel matching the channel + class is created, then inviting the contact to that channel + can be expected to succeed.

+ + +

To support room-based XMPP protocols like + Muji + and MUC Tubes, it's necessary to be able to discover who can be + invited to a given room channel; most XMPP contacts won't + support being invited into a Muji conference call, at least + in the short to medium term.

+ + +

No interpretation is defined for channel classes with any other + target handle type, or for channel classes that do not fix a + target handle type, in this version of the Telepathy + specification.

+ + + + + + +

The same structs that would be returned by + GetContactCapabilities. + Omitted from the result if the contact's capabilities + are not known; present in the result as an empty array if the + contact is known to have no capabilities at all.

+ + + + + + diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml new file mode 100644 index 0000000..5282a82 --- /dev/null +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -0,0 +1,549 @@ + + + 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.

+ + + + + (as stable API) + + +

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

+ +

The most basic functionality of this interface is to list and monitor + a contact's set of groups. To do this, use the + GroupsChanged signal, and the + groups contact attribute (this should + usually be done by connecting to the GroupsChanged signal, then + calling GetContactListAttributes with this interface + included in the Interfaces argument). Simple user interfaces can + limit themselves to displaying that information, and ignore the rest + of this interface: to ensure that this works, + GroupsChanged is emitted for every + change, even if that change could be inferred from another signal + such as GroupsRemoved.

+ +

Looking at contacts' lists of groups is sufficient to present a + user interface resembling XMPP's data model, in which groups behave + like tags applied to contacts, and so an empty group cannot exist + or is not interesting. However, some protocols model groups as + objects in their own right. User interfaces may either track + the set of groups via the Groups + property and the GroupsCreated and + GroupsRemoved signals, or ignore + this extra information.

+ +

Similarly, in some protocols it is possible to rename a group as + a single atomic operation. Simpler user interfaces will + see the new name being created, the old name being removed, and the + members moving to the new name, via the signals described above. + More advanced user interfaces can optionally distinguish between an + atomic rename and a create/remove pair, and display renamed groups + differently, by monitoring the + GroupRenamed signal.

+ +

This interface also provides various methods to manipulate + user-defined groups, which can be expected to work if + GroupStorage is not None.

+ +

Depending on the protocol, some methods might be implemented by + more than one protocol operation; for instance, in a + "contact-centric" protocol like XMPP, + SetContactGroups is a single + protocol operation and SetGroupMembers + requires a protocol operation per contact, whereas in a more + "group-centric" protocol it might be the other way around. User + interfaces SHOULD call whichever method most closely resembles the + way in which the user's action was represented in the UI, and + let the connection manager deal with the details.

+ + + + +

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; clients can also + get extra context for group membership changes by receiving + GroupRenamed and + GroupsRemoved.

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

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 and + GroupsRemoved; clients can also + distinguish between a create/remove pair and a renamed group by + receiving GroupRenamed.

+ +

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

+ + + + + + 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, in protocols where this can + be distinguished from group creation, removal and membership + changes.

+ +

Immediately after this signal is emitted, + GroupsCreated MUST signal the + creation of a group with the new name, and + GroupsRemoved MUST signal the + removal of a group with the old name.

+ + +

Emitting these extra signals, in this order, means that clients + that are interested in the set of groups that exist (but treat a + rename and a create/remove pair identically) can ignore the + GroupRenamed signal entirely.

+ + +

If the group was not empty, immediately after those signals are + 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, renaming a + group MAY be signalled as a set of + GroupsCreated, + GroupsRemoved and + GroupsChanged signals, instead of + emitting this signal.

+ + +

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.

+ + +

Emitting the signals in this order allows for two modes of + operation. A client interested only in a contact's set of groups + can ignore GroupsRemoved and rely + on the GroupsChanged signal that + will follow; a more elaborate client wishing to distinguish between + all of a group's members being removed, and the group itself + being removed, can additionally watch for + GroupsRemoved and use it to + disambiguate.

+ + + + + The names of the groups. + + + + + +

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.

+ +

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.

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

+ +

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.

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

+ +

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.

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

+ +

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.

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

+ +

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.

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

+ +

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.

+ + + + 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 new file mode 100644 index 0000000..527d325 --- /dev/null +++ b/spec/Connection_Interface_Contact_Info.xml @@ -0,0 +1,550 @@ + + + Copyright (C) 2008 Collabora Limited + Copyright (C) 2008 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.

+ + + (as stable API) + + + + + + The name of the field; this is the lowercased name of a vCard field. + For example, a field representing a contact's address would be named + "adr". + + + + +

A list of vCard type parameters applicable to this field, with their + values. The type parameter names, and any values that are + case-insensitive in vCard, MUST be in lower case. For example, a + contact's preferred home address would have parameters + 'type=home' and 'type=pref'.

+ + + The type parameter 'type' is likely to be the most common, but + there can be others, such as 'language=en'. + + +

Characters which are required to be escaped in vCard type + parameters should not be escaped in this list. For instance, + a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become + ('x-foo', ['semicolon=;'], ['bar']) in this interface.

+ + + This avoids Telepathy UIs having to understand the escaping and + unescaping rules for vCards. The type parameter name is not + allowed (by RFC 2425) to contain an '=' character, so no ambiguity + is introduced. + + + + + +

For unstructured vCard fields (such as 'fn', a formatted name + field), a single-element array containing the field's value.

+ +

For structured fields (such as 'adr', an address field), an array + corresponding to the semicolon-separated elements of the field (with + empty strings for empty elements).

+ +

A vCard field with multiple comma-separated values, such as + 'nickname', should be represented by several + Contact_Info_Fields.

+ +

Characters which are required to be escaped in vCard values, such as + semi-colons and newlines, should not be escaped in this list (e.g. if + a value contains a newline, the data passed over D-Bus should + contain a literal newline character).

+ + + An earlier draft of this interface split structured vCard fields + into multiple Telepathy-level fields; for example, 'n' became + 'family-name', 'given-name', etc. But under this representation, + omitting empty components leads to difficulty identifying where one + name ends and another begins. Consider the fields ['given-name', + 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does + this represent two 'n' fields, or one with incorrect component + ordering? + + + + +

Represents one piece of information about a contact, as modelled by + a single vCard field. Of the fields defined in RFC 2426, common + examples include:

+ +
+
fn
+
The contact's full name, formatted to their liking
+ +
n
+
The contact's full name, divided into five parts: family name, + given name, additional names, honorific prefixes, and honorific + suffixes
+ +
org
+
The contact's organisation, divided into the organization's name + possibly followed by one or more organizational unit names.
+ +
adr
+
A street address for the contact, divided into seven components: + post office box, extended address, street address, locality (e.g., + city), region (e.g., state or province), the postal code, and the + country name.
+ +
label
+
A free-form street address for the contact, formatted as a + single value (with embedded newlines where necessary) suitable for + printing on an address label
+ +
tel
+
A telephone number for the contact.
+ +
email
+
An email address for the contact.
+
+ +

For example, the following vCard:

+ + 
+   BEGIN:vCard
+   VERSION:3.0
+   FN:Wee Ninja
+   N;LANGUAGE=ja:Ninja;Wee;;;-san
+   ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement
+   ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
+    ;CB2 1SJ;UK
+   LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ
+   TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753
+   EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
+   EMAIL;TYPE=INTERNET:wee.ninja@example.com
+   URL:http://www.thinkgeek.com/geektoys/plush/8823/
+   NICKNAME:HR Ninja,Enforcement Ninja
+   END:vCard
+ +

would be represented by (in Python-like syntax):

+ + 
+[
+  ('fn', [], ['Wee Ninja']),
+  ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
+  ('org', [], ['Collabora, Ltd.', 'Management Division',
+    'Human Resources; Company Policy Enforcement']),
+  ('adr', ['type=work','type=postal','type=parcel'],
+   ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+  ('label', ['type=work','type=postal','type=parcel'],
+   ['''11 Kings Parade
+  Cambridge
+  Cambridgeshire
+  UK
+  CB2 1SJ''']),
+  ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+  ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+  ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
+  ('email', ['type=internet'], ['wee.ninja@example.com']),
+  ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+  ('nickname', [], ['HR Ninja']),
+  ('nickname', [], ['Enforcement Ninja'])
+]
+ + + + + A dictionary whose keys are contact handles and whose + values are contact information.. + + + + + + + + An integer handle for the contact whose info has changed. + + + + + An array of fields representing information about this contact. + + + + Emitted when a contact's information has changed or been received for + the first time on this connection. + + + + + + + An array of handles representing contacts. + + + + + A dictionary mapping contact handles to information, whose keys are + the subset of the requested list of handles for which information was + cached. + + + + Request information on several contacts at once. This SHOULD only + return cached information, omitting handles for which no information is + cached from the returned map. + + + + + + + Integer handles for contacts. + + + + Retrieve information for the given contact, requesting it from the + network if an up-to-date version is not cached locally. This method + SHOULD return immediately, emitting + ContactInfoChanged when the contacts' + updated contact information is returned. + + + This method allows a client with cached contact information to + update its cache after a number of days. + + + + + + + + + + + + An integer handle for a contact. + + + + + Information about that contact. + + + + Retrieve information for a contact, requesting it from the network if + it is not cached locally. + + + This method is appropriate for an explicit user request to show + a contact's information; it allows a UI to wait for the contact + info to be returned. + + + + + + + + + The contact's information could not be retrieved. + + + + + + + + Set new contact information for this connection, replacing existing + information. This method is only suppported if + ContactInfoFlags contains + Can_Set, and may only be passed fields conforming to + SupportedFields. + + + + The new information to be set. + + + + + + + + + + Setting your own information is not supported on this protocol. + + + + + The supplied fields do not match the restrictions specified by + SupportedFields. + + + + + + + + Flags defining the behaviour of contact information on this protocol. + Some protocols provide no information on contacts without an explicit + request; others always push information to the connection manager as + and when it changes. + + + + + Indicates that SetContactInfo is + supported on this connection. + + + + + + Indicates that the protocol pushes all contacts' information to the + connection manager without prompting. If set, + ContactInfoChanged will be emitted + whenever contacts' information changes. + + + + + + + A string naming a field in a vCard, such as "fn" or "adr". Although + these are case-insensitive in RFC 2425, in Telepathy they MUST be + normalized to lower case. In the terminology of RFC 2425 this is + called a "type name", and corresponds to the "name" production given + in the ABNF. + + + + + + A type parameter as defined by RFC 2426, such as "type=cell" or + "language=en". + + + + + +

An integer representing the bitwise-OR of flags on this + connection.

+ +

This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.

+ + +

Some XMPP servers, like Facebook Chat, do not allow the vCard to + be changed (and so would not have the Can_Set flag). Whether the + user's server is one of these cannot necessarily be detected until + quite late in the connection process.

+ + + + + + + A struct describing a vCard field, with parameters, that + may be passed to SetContactInfo on this + Connection. + + + A vCard field name, such as 'tel'. + + + + The set of vCard type parameters which may be set on this + field. If this list is empty and the + Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type + parameters may be used. + + + + Flags describing the behaviour of this + field. + + + + Maximum number of instances of this field which may be + set. MAXUINT32 is used to indicate that there is no + limit. + + + + + +

A list of field specifications describing the kinds of fields which may + be passed to SetContactInfo. The empty + list indicates that arbitrary vCard fields are permitted. This + property SHOULD be the empty list, and be ignored by clients, if + ContactInfoFlags does not contain the + Can_Set flag.

+ +

For example, a protocol in which arbitrary vCards were stored + as-is would set this property to the + empty list. A protocol whose notion of contact information is one + each of personal phone number, mobile phone number, location, email + address and date of birth, with no attributes allowed on each piece + of information, would set this property to (in Python-like + syntax):

+ + 
+[
+  ('tel', ['type=home'], Parameters_Exact, 1),
+  ('tel', ['type=cell'], Parameters_Exact, 1),
+  ('adr', [], Parameters_Exact, 1),
+  ('bday', [], Parameters_Exact, 1),
+  ('email', ['type=internet'], Parameters_Exact, 1),
+]
+ +

A protocol which allows users to specify up to four phone numbers, + which may be labelled as personal and/or mobile, would set this + property to + [ ('tel', ['type=home', 'type=cell'], 0, 4), ].

+ + +

Studying existing IM protocols shows that in practice protocols + allow either a very restricted set of fields (such as MSN, which + seems to correspond roughly to the largest example above), or + something mapping 1:1 to a large subset of vCard (such as XMPP's + XEP-0054).

+ + +

This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.

+ + +

Some XMPP servers, like Google Talk, only allow a small subset of + the "vcard-temp" protocol. Whether the user's server is one of + these cannot be detected until quite late in the connection + process.

+ + + + + + + Flags describing the behaviour of a vCard field. + + + +

If present, exactly the parameters indicated must be set on this + field; in the case of an empty list of parameters, this implies that + parameters may not be used.

+ +

If absent, and the list of allowed parameters is non-empty, + any (possibly empty) subset of that list may be + used.

+ +

If absent, and the list of allowed parameters is empty, + any parameters may be used.

+ + + + + +

Indicates that this field will be overwritten when the user's alias + is changed with SetAliases + or when the Account's Nickname + is updated. Clients that allow the editing of the Alias and the + ContactInfo in the same location should hide fields with this flag.

+ +

If a client allowed the user to edit both the nickname and the + ContactInfo field at the same time, the user could set them to two + different values even though they map to the same property. This + would result in surprising behavior where the second value would + win over the first.

+ +

In addition to hiding this field when editing ContactInfo together + with the user's nickname, it is recommended that clients call + SetContactInfo before setting the + user's nickname.

+ +

This ensures that if the user changes the nickname, the correct + value will get set even if the stale nickname is mistakenly sent + along with SetContactInfo.

+ +

If used, this flag typically appears on either the 'nickname' or + 'fn' field.

+ + + + + +

An interface for requesting information about a contact on a given + connection. Information is represented as a list of + Contact_Info_Fields forming a + structured representation of a vCard (as defined by RFC 2426), using + field names and semantics defined therein.

+ +

On some protocols, information about your contacts is pushed to you, + with change notification; on others, like XMPP, the client must + explicitly request the avatar, and has no way to tell whether it has + changed without retrieving it in its entirety. This distinction is + exposed by ContactInfoFlags containing + the Push flag.

+ +

On protocols with the Push flag set, UIs can connect to + ContactInfoChanged, call + GetContactInfo once at login for the set + of contacts they are interested in, and then be sure they will receive + the latest contact info. On protocols like XMPP, clients can do the + same, but will receive (at most) opportunistic updates if the info is + retrieved for other reasons. Clients may call + RequestContactInfo or + RefreshContactInfo to force a contact's + info to be updated, but MUST NOT do so unless this is either in + response to direct user action, or to refresh their own cache after a + number of days.

+ + +

We don't want clients to accidentally cause a ridiculous amount of + network traffic.

+ + + + + +

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 0000000..033c64d --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,1085 @@ + + + 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.

+ + + + (as stable API) + + +

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.20 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 fail until the contact list is available. + Using a method also allows extra attributes to be retrieved at + the same time.

+ + + + + + 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. + + + + + + The progress made in retrieving the contact list. + Change notification is via + ContactListStateChanged. + + + + + + Emitted when ContactListState + changes. + + + + + The new value of ContactListState. + + + + + + +

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 not No
    • +
  • all contacts whose publish + attribute is not No
    • +
+ +

but MAY contain other contacts.

+ + +

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

+ + +

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.

+ + + + + +

A list of strings indicating which D-Bus interfaces the calling + process is interested in. Equivalent to the corresponding argument + to GetContactAttributes, + except that if this list does not contain the ContactList + interface itself, it is treated as though that interface was also + requested.

+ + + + + +

If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + Connection.HoldHandles. + (If HasImmortalHandles is true, which SHOULD be the + case in all new connection managers, this has no effect.)

+ + + + + +

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

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

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

+ + + + + + + +

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: see the + subscribe and + publish contact attributes for + details.

+ + + + The presence subscription state is + unknown. + + + + 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. + + + + + +

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 not Yes, 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 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.

+ + + + + +

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

+ +

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

+ + + + + +

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

+ +

On some protocols, certain metadata (for instance, contact aliases) + can only be stored for contacts on the contact list, or contacts + with a particular contact list state.

+ +

To make it easier to deal with such protocols, if clients set + metadata on a contact who is not in the required state, the + Connection MUST cache the metadata for the duration of the session. + If clients request the attributes of that contact after the + appropriate "set" method has returned successfully, the Connection + MUST return the new (cached) value.

+ +

If the contact is later placed in the required state to store + metadata (for instance, if subscription to the contact's presence + is requested, on a protocol like MSN where the alias has storage type + Subscribed_Or_Pending), the connection MUST store the cached + metadata at that time.

+ + +

If the Connection didn't cache changes in this way, a client + intending to change the alias on MSN would have to wait until + the server acknowledged the subscription request; in the meantime, + other clients would still display the old alias.

+ + +

The only exception to that general rule is that if the Connection + cannot store particular metadata at all (i.e. the + storage type is None), it MUST reject attempts to set it.

+ + +

If the implementation knows that metadata can't be stored at + all, it's useful to report that, which can be done + synchronously. In general, user interfaces should detect + storage type None and not display editing controls at all.

+ + + + + +

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.

+ + + + + + +

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.

+ + + + + + +

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 contacts are removed from that list.

+ + +

This provides change notification for that list, and for + 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 + contacts that have been added, and all the contacts for which those + attributes have changed. + + + + + + The identifiers of the contacts in the Changes map. + + + + + + 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. + + + + + + Connection managers MUST still + emit this signal, but clients SHOULD listen for the + ContactsChangedWithID signal in + addition, and ignore this signal after ContactsChangedWithID has been + emitted at least once. + + +

Emitted immediately after + ContactsChangedWithID, under the same + circumstances.

+ +

If clients receive this signal without first receiving a + corresponding ContactsChangedWithID, + they MUST assume that only this signal will be emitted.

+ + + + + The same as the corresponding argument to + ContactsChangedWithID. + + + + + + The same as the corresponding argument to + ContactsChangedWithID, except that it + only includes handles and not identifiers. + + + + + + +

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.

+ +

Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically allow the contacts to see the local user's + presence). User interfaces that require mutual subscription + MAY call AuthorizePublication + at the same time as this method.

+ + +

Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.

+ + +

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

+ + + + +

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.

+ + + + + + + + + + The ContactListState is None + or Waiting. + + + + + It was not possible to perform the requested action, because + CanChangeContactList 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.

+ +

Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically request that the contacts allow the user to + subscribe to their presence). User interfaces that require mutual + subscription MAY call + RequestSubscription at the same time + as this method.

+ + +

Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.

+ + +

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.

+ + +

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.

+ + + + +

One or more contacts to authorize.

+ + + + + + + + + + It was not possible to perform the requested action, because + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. + + + + + + + +

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.

+ + +

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.

+ + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. + + + + + + + +

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.

+ +

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.

+ + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeContactList 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.

+ +

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.

+ + + + +

One or more contacts to remove.

+ + + + + + + + + + It was not possible to perform the requested action because + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. + + + + + + + + diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml new file mode 100644 index 0000000..1020190 --- /dev/null +++ b/spec/Connection_Interface_Contacts.xml @@ -0,0 +1,191 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + +

This interface allows many attributes of many contacts to be + obtained in a single D-Bus round trip.

+ +

Each contact attribute has an string identifier + (Contact_Attribute), which is namespaced + by the D-Bus interface which defines it.

+ + + + + A DBus_Interface, followed by a slash '/' character + and an identifier for an attribute defined by that interface. The + attribute identifier SHOULD be in lower case. + + + These aren't D-Bus core Properties, and we want them to look visibly + different. + + + + + + + Some of the attributes of a single contact. + + + + + The name of the attribute + + + + + + The value of the attribute + + + + + + Mapping returned by + GetContactAttributes, representing a + collection of Contacts and their requested attributes. + + + + A contact + + + + + + Attributes of that contact + + + + + + + A list of D-Bus interfaces for which + GetContactAttributes is expected to work. + This cannot change during the lifetime of the Connection. + + + + + + Return any number of contact attributes for the given handles. + + + + + An array of handles representing contacts. + + + + + +

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.

+ +

Connection managers SHOULD ignore interfaces requested which they + do not support (i.e. those not mentioned in the + ContactAttributeInterfaces + property.)

+ + +

This simplifies client-side code. Clients which care may + distinguish between unsupported interfaces (e.g. this Connection + does not support Avatars), and interfaces on which no information + is known for these contacts (e.g. we don't know the avatar tokens + of any of the contacts, so we omitted them all) by inspecting + ContactAttributeInterfaces.

+ + +

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

+ +

As well as returning cached information immediately, the + connection MAY start asynchronous requests to obtain better + values for the contact attributes. If better values are later + obtained by this process, they will be indicated with the usual + signals (such as AliasesChanged).

+ + + For instance, an XMPP connection manager could download vCards + in response to a request for Aliasing + attributes. + + + + requesting information for interfaces not mentioned in + ContactAttributeInterfaces is no + longer an error. Be aware that older connection managers may still + consider this an error. + + + + + +

If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + Connection.HoldHandles. + (If HasImmortalHandles is true, which SHOULD be the + case in all new connection managers, this has no effect.)

+ + +

For further round-trip avoidance.

+ + + + + + +

A dictionary mapping the contact handles to contact attributes. + If any of the requested handles 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.

+ +

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

+ + + + + + + + + + diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml new file mode 100644 index 0000000..e5457b1 --- /dev/null +++ b/spec/Connection_Interface_Forwarding.xml @@ -0,0 +1,346 @@ + + + + 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.

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

+ +

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

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

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.

+ + + + +

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. + + + + + + + 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. + + + + + + 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. + + + + + + + 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. + + + + + + + + diff --git a/spec/Connection_Interface_Keepalive.xml b/spec/Connection_Interface_Keepalive.xml new file mode 100644 index 0000000..9f4ac68 --- /dev/null +++ b/spec/Connection_Interface_Keepalive.xml @@ -0,0 +1,73 @@ + + + + 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 1) + + +

Most messaging protocols allow the client to send periodic + content-less pings to the server when the connection is otherwise idle, + to reassure both itself and the server that its connection is still + alive. Depending on the nature of the network connection, and the + device running the client, the desired interval between such pings may + vary.

+ + +

For instance, on a mobile handset connected via 3G, + overly-frequent keepalives can drain the battery through needlessly + waking up the radio, and a relatively high interval is appropiate. By + contrast, a desktop computer is less likely to be asleep in the first + place, and users expect dropped connections to be noticed as soon as + possible.

+ + +

This interface provides a + KeepaliveInterval property which + controls the frequency of keepalive pings, if any. Connection managers + implementing this property should also include it in Protocol.Parameters + with the DBus_Property flag, allowing the desired value to + be stored in Account.Parameters + and passed onto the connection by the account manager.

+ + + + +

The time in seconds between pings sent to the server to ensure that + the connection is still alive, or 0 to disable such + pings.

+ +

This property (and parameter) supersedes the older + keepalive-interval + Connection_Parameter_Name.

+ + + + + + diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml new file mode 100644 index 0000000..fe54923 --- /dev/null +++ b/spec/Connection_Interface_Location.xml @@ -0,0 +1,464 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 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.

+ + + (as stable API) + + + +

An interface on connections to support protocols which allow users to + publish their current geographical location, and subscribe to the + current location of their contacts.

+ +

This interface is geared strongly towards automatic propagation and + use of this information, so focuses on latitude, longitude and + altitude which can be determined by GPS, although provision is also + included for an optional human-readable description of locations. All + co-ordinate information is required to be relative to the WGS84 + datum.

+ +

The information published through this interface is intended to have + the same scope as presence information, so will normally be made + available to those individuals on the user's "publish" contact list. + Even so, user interfaces should not automatically publish location + information without the consent of the user, and it is recommended + that an option is made available to reduce the accuracy of the + reported information to allow the user to maintain their privacy.

+ +

Location information is represented using the terminology of XMPP's + XEP-0080 + or the XEP-0080-derived + Geoclue API where + possible.

+ +

Clients of this interface SHOULD register an interest in it by calling + Connection.AddClientInterest with an argument + containing the name of this interface, + before calling any Location method. If they do so, they SHOULD also call + Connection.RemoveClientInterest after use to allow + the CM to release resources associated with this interface.

+ + + + + + + A user's location, represented as an extensible mapping. + + + + + +

Civic addresses are represented by the following well-known + keys (all of which have string values), which should be kept in + sync with those used in XEP-0080 and in the Geoclue project:

+ +
    +
  • countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country + code, e.g. "us", "gb", "fr"
    • +
  • country - s: a country name in unspecified locale, e.g. + "USA"
    • +
  • region - s: an administrative region of the nation, such as a + state or province
    • +
  • locality - s: a locality within the administrative region, such + as a town or city
    • +
  • area - s: a named area such as a campus or neighborhood
    • +
  • postalcode - s: a code used for postal delivery
    • +
  • street - s: a thoroughfare within the locality, or a crossing of + two thoroughfares
    • +
+ +

The following address keys are defined in XEP-0080 but not by + Geoclue, and are also allowed:

+ +
    +
  • building - s: a specific building on a street or in an area
    • +
  • floor - s: a particular floor in a building
    • +
  • room - s: a particular room in a building
    • +
  • text - s: any more specific information, e.g. + "Northwest corner of the lobby"
    • +
  • description - s: A natural-language name for or description of + the location, e.g. "Bill's house"
    • +
  • uri - s: a URI representing the location or pointing to more + information about it
    • +
+ +

Since the previous strings have data intended to be read by users, + the language used should be stated using:

+ +
    +
  • language - s: a specific language or locale of location + information in a format compatible to RFC 4646. Note that UTF-8 + is the only allowed encoding, e.g. "en" or "fr-CA".
    • +
+ +

Positions are represented by the following well-known keys:

+ +
    +
  • lat - d: latitude in decimal degrees north, -90 to +90, + relative to the WGS-84 datum + + This is from XEP-0080; the XEP allows use of a different + datum, but recommends this one. We enforce sanity by requiring + a consistent datum: a minimal compliant implementation of this + specification in terms of XEP-0080 would simply ignore the + <lat> and <lon> elements if <datum> exists + and has a value other than WGS-84, while an advanced + implementation might correct for the different datum. + +
    • +
  • lon - d: Longitude in decimal degrees east, -180 to +180, + relative to the WGS-84 datum + + Same rationale as 'lat' + +
    • +
  • alt - d: altitude in metres above sea level (negative + if below sea level) + + This is from XEP-0080 + +
    • + + + +
  • accuracy - d: horizontal position error in metres if + known + + This is from XEP-0080 + +
    • +
+ +

Velocities are represented by the following well-known keys:

+ +
    +
  • speed - d: speed in metres per second + + This is from XEP-0080 + +
    • +
  • bearing - d: direction of movement in decimal degrees, + where North is 0 and East is 90 + + This is from XEP-0080, and is equivalent to the struct field + called "direction" in GeoClue + +
    • +
+ +

Other well-known keys:

+ +
    +
  • timestamp - x (Unix_Timestamp64): the time + that the contact was at this location, in seconds since + 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC) + + XEP-0080 uses an ISO 8601 string for this, but a number of + seconds since the epoch is probably easier to work with. + +
    • +
+ + + + + + The value corresponding to the well-known key. + + + + + + + A map from contacts to their locations. + + + A contact + + + The contact's location, which MAY be empty to indicate + that the contact's location is unknown + + + + + +

Return the current locations of the given contacts, if they are + already known. If any of the given contacts' locations are not known, + request their current locations, but return immediately without waiting + for a reply; if a reply with a non-empty location is later received + for those contacts, the LocationUpdated + signal will be emitted for them.

+ + +

This method is appropriate for "lazy" location finding, for instance + displaying the location (if available) of everyone in your contact + list.

+ + +

For backwards compatibility, if this method is called by a client + whose "interest count" for this interface, as defined by Connection.AddClientInterest, is zero, the + Connection SHOULD behave as if AddClientInterest had been called for + this interface just before that method call. Clients that do not + explicitly call AddClientInterest SHOULD NOT call Connection.RemoveClientInterest either.

+ + + + + The contacts whose locations should be returned or signalled. + + + + + + The contacts' locations, if already known. Contacts whose locations + are not already known are omitted from the mapping; contacts known + to have no location information appear in the mapping with an empty + Location dictionary. + + + + + + + + + + + + Return the current location of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + + + + + + The contact whose location should be returned. + + + + + + The contact's location. It MAY be empty, indicating that no location + information was found. + + + + + + + + + + The requested contact does not allow the local user to see their + location information. + + + + + + + + Emitted when a contact's location changes or becomes known. + + + + + The contact + + + + + The contact's location, or empty to indicate that nothing is known + about the contact's location. + + + + + + + Set the local user's own location. + + + + + The location to advertise. If the user wants to obscure their + exact location by reducing the precision or accuracy, clients + MUST do this themselves, rather than relying on the connection + manager to do so. Clients that interact with more than one + connection SHOULD advertise the same reduced-accuracy location + to all of them, so that contacts cannot obtain an undesirably + accurate location by assuming that random errors have been added + and averaging the locations advertised on multiple connections. + + + + + + + + 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. + + + + + + + + The types of access control that are supported by this + connection. + + + + The current access control mechanism and settings + for this connection. Before publishing location for the first time, + if this has not been set by a client, implementations SHOULD + set it to be as restrictive as possible (an empty whitelist, if + supported). + + + + + + 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. + + + + + +

The same mapping that would be returned by + GetLocations for this contact. + Omitted from the result if the contact's location + is not known.

+ +

For backwards compatibility, if contact attributes that include + this interface are requested + by a client whose "interest count" for this interface, as defined by + Connection.AddClientInterest, is zero, the + Connection SHOULD behave as if AddClientInterest was called for this + interface just before that request. Clients that do not explicitly + call AddClientInterest SHOULD NOT call Connection.RemoveClientInterest either.

+ + + + + + diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml new file mode 100644 index 0000000..395e101 --- /dev/null +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -0,0 +1,624 @@ + + + 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.

+ + + + (as stable API) + + + + A client MUST notify interest in this feature before it will be + enabled. + + + + + + + This Connection provides the number of unread e-mails (or e-mail + threads) in the main folder of your e-mail account, as the + UnreadMailCount property. The + connection manager will update this value by emitting the + UnreadMailsChanged signal. + + + + + This Connection provides a detailed list of unread e-mails, as the + UnreadMails property. If this flag + is set, Supports_Unread_Mail_Count MUST be set, and + Emits_Mails_Received MUST NOT be set. + The Connection will update the list by emitting the + UnreadMailsChanged signals. + + + + + This Connection emits the MailsReceived + signal, which provides details about newly arrived e-mails but does + not maintain their read/unread status afterwards. This flag MUST NOT + be combined with Supports_Unread_Mails. + + + + + This Connection can provide a URL (with optional POST data) to + open the the inbox of the e-mail account in a web-based client, via + the RequestInboxURL method. + + + + +

This Connection can provide a URL (with optional POST data) to open + a specific mail in a web-based client, via the + RequestMailURL method. This feature + is not useful unless either Emits_Mails_Received or + Supports_Unread_Mails is set.

+ +

If this flag is not set, clients SHOULD fall back to using + RequestInboxURL if available.

+ + + + +

Each Mail represents a thread of e-mails, which + MAY have more than one sender.

+ + +

Google Talk notifies users about new mail in terms of unread + threads, rather than unread e-mails.

+ + + + + +

Flags representing capabilities provided by a connection manager. + Those values can be used as bitfield. Some flags depend on, or + conflict with, each other.

+ +

Connections SHOULD implement as many of these features as the + underlying protocol allows, preferring to implement + Supports_Unread_Mails instead of Emits_Mails_Received if both are + possible.

+ + + + + + + Use the GET method when opening the URL. + + + + + Use the POST method when opening the URL. Refer to + HTTP_Post_Data for more details. + + + + The HTTP Method with which to request a URL. + + + + + +

A pair (key, value) representing POST data compatible with the + application/x-www-form-urlencoded MIME type. The strings MUST be + valid UTF-8 strings, and the characters used in the key MUST obey + the requirements of the + + HTML CDATA type. The value MUST NOT be + encoded with HTML entities.

+ +

For example, if the POST data should contain a key "less-than" with value + "<", and a key "percent" with value "%", this should be represented as + two HTTP_Post_Data structures, ("less-than", "<") and ("percent", "%"), + resulting in a POST request whose request body is "less-than=&lt;&percent=%25". + If a client passes this to a browser by writing it into an HTML form, it + could do so by representing it as:

+ + 
+        <input type="hidden" name="less-than">&lt;</input>
+        <input type="hidden" name="percent">%</input>
+
+ + +

This data can be used to generate a HTML file that will + automatically load the URL with appropriate POST data, in which case + the client MUST convert any characters that are special within HTML + into HTML entities. Alternatively, it can be used in an API that will + instruct the browser how to load the URL (like the Netscape Plug-in + API), in which case the client MUST escape + characters that are + reserved in URLs, if appropriate for that API.

+ +

An array of pairs is used instead of a map from keys to values, + because it's valid to repeat keys in both HTML and + x-www-form-urlencoded data.

+ + + + The key, corresponding to a HTML control + name + + + The value + + + + + +

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 + address + + + The actual e-mail address + + + + + +

A structure containing the required information to open a web-based + e-mail UI, without needing re-authentication (if possible).

+ +

Because the URL and POST data frequently contain short-lived + credential tokens, a new URL should be requested (by calling one of + the methods that returns a Mail_URL) for each visit to the web-based + UI, and the URL should be visited soon after it is returned.

+ + + + The URL to which to send a request. + + + + + The HTTP method of the request. + + + + + An array of name-value pairs containing the POST data to use when + opening the URL. This MUST be an empty array if the Method is not + POST. + + + + + + + An extensible map representing a mail, or (on protocols where + Thread_Based appears in + MailNotificationFlags) a thread of + mails. All keys are optional where not otherwise stated; however, at + least one of "senders" and "subject" must be included. + + + + +

A key providing information about the mail or thread. Well-known + keys are as follows:

+ +
+
id — s
+
+

A unique ID for this e-mail. CMs with + Supports_Unread_Mails set in + MailNotificationFlags MUST provide + this key in each Mail.

+ +

If provided, the ID SHOULD be unique to a Mail at least until + that mail is removed with the + UnreadMailsChanged signal + (in protocols with Supports_Unread_Emails), or + unique for the duration of a session (otherwise).

+ + +

In protocols with Supports_Unread_Mails, this key is used to + indicate which mail was removed. In protocols without that + feature, it's impossible to tell when a mail has been removed + (and hence how long the identifier will remain valid for use + with RequestMailURL).

+ +
+ +
url-data — any type
+
An opaque identifier (typically a string or list of strings) + provided to the Connection when calling + RequestMailURL, + containing information used by the Connection to build the URL. +
+ +
senders — a(ss) (Mail_Address)
+
+ An array of sender display name and e-mail address pairs. Note that + only e-mails represented as a thread can have multiple senders. +
+ +
to-addresses — a(ss) (Mail_Address)
+
+ An array of display name and e-mail address pairs representing + the recipients. +
+ +
cc-addresses — a(ss) (Mail_Address)
+
+ An array of display name and e-mail address pairs representing + the carbon-copy recipients. +
+ +
sent-timestamp — x (Unix_Timestamp64)
+
A UNIX timestamp indicating when the message was sent, or for + a thread, when the most recent message was sent. +
+ +
received-timestamp — x (Unix_Timestamp64)
+
A UNIX timestamp indicating when the message was received, or for + a thread, when the most recent message was received. +
+ +
has-attachments — b
+
If true, this mail has attachments.
+ +
subject — s
+
+ The subject of the message. This MUST be encoded in UTF-8. +
+ +
content-type — s
+
+

The MIME type of the message content. Two types are currently + supported: "text/plain" for plain text, and "text/html" for a + HTML document. If omitted, "text/plain" MUST be assumed. + Regardless of MIME type, the content MUST be valid UTF-8 (which + may require that the Connection transcodes it from a legacy + encoding).

+ + +

All strings on D-Bus must be UTF-8.

+ +
+ +
truncated — b
+
+ If true, the content is only a partial message; if false or + omitted, the content is the entire message. +
+ +
content — s
+
+ The body of the message, possibly truncated, encoded as appropriate + for "content-type". +
+ +
folder — s
+
+ The name of the folder containing this e-mails. + If omitted, the inbox SHOULD be assumed. +
+
+ + + + + The value, of whatever type is appropriate for the + key. + + + + + + Integer representing the bitwise-OR of supported features for e-mails + notification on this server. This property MUST NOT change after the + Connection becomes CONNECTED. + + + This property indicates the behavior and availability + of the other properties and signals within this interface. A + connection manager that cannot at least set one of the flags + in the Mail_Notification_Flags + SHOULD NOT provide this interface. + + + + + + +

The number of unread messages in the Inbox. Change notification is + via UnreadMailsChanged.

+ +

This property is only useful if Supports_Unread_Mail_Count + is set in the MailNotificationFlags; + otherwise, it MUST be zero.

+ +

If Thread_Based appears in the + MailNotificationFlags, this property + counts the number of threads, not the number of mails.

+ +

Note that this count MAY be bigger than the number of items in + UnreadMails. See + UnreadMails for more details.

+ + + + + +

An array of unread Mails. Change notification is + via UnreadMailsChanged. This property + is only useful if Supports_Unread_Mails is set in + MailNotificationFlags; otherwise, it + MUST be an empty list.

+

The array size MAY be shorter than + UnreadMailCount.

+ +

Some servers may limits the amount of detailed e-mails sent. This + can significantly reduce the network traffic for large inbox. For + this reason, it is normal that + UnreadMailCount be bigger or equal + to the size of this array.

+ + + + + + + A string representing the e-mail address of the account. The CMs MUST + provide this information. + + In close integration of MailNotification with other e-mail services, + the e-mail address can be used has a unique identifier for the + account. Possible integration could be between Telepathy and + Evolution where the e-mail address is the common information in + both interfaces. + + + + + + + +

An array of Mails. Those e-mail MUST NOT have + the "id" key.

+ + +

On connections that emit this signal, it's impossible to tell + when a mail has been removed, and hence when "id" has become + invalid.

+ + + + + + Emitted when new e-mails messages arrive to the inbox associated with + this connection. This signal is used for protocols that are not able + to maintain the UnreadMails list, but + do provide real-time notification about newly arrived e-mails. It MUST + NOT be emitted unless Emits_Mails_Received is set in + MailNotificationFlags. + + + + + + + Number of unread messages in the inbox (the new value of + UnreadMailCount). + + + + +

A list of Mail that are being added or updated + in UnreadMails.

+ + +

Mails may be updated when the URL information (URL and POST data) + have changed, or senders were added or removed from an e-mail + thread.

+ + +

If the Supports_Unread_Mails flag is not set, this list + MUST be empty, even if Count has increased.

+ + + + + A list of e-mail IDs that are being removed from + UnreadMails. + If the Supports_Unread_Mails flag is not set, this list + MUST be empty, even if Count has decreased. + + + +

Emitted when UnreadMails or + UnreadMailCount have changed. It MUST + NOT be emited if Supports_Unread_Mail_Count flag is not set + in MailNotificationFlags.

+ +

Mails_Added and + Mails_Removed MUST be empty if the + Supports_Unread_Mails flag is not set.

+ + + + + + + A struture containing a URL and optional additional data to open a + webmail client, without re-authentication if possible. + + + + This method creates and returns a URL and an optional POST data that + allow opening the Inbox folder of a webmail account. This URL MAY + contain tokens with a short lifetime, so clients SHOULD request a new + URL for each visit to the webmail interface. This method is implemented + only if the Supports_Request_Inbox_URL flag is set in + MailNotificationFlags. + + + We are not using properties here because the tokens are unsuitable + for sharing between clients, and network round-trips may be required + to obtain the information that leads to authentication free webmail + access. + + + + + + + + + + + + + The mail's id as found in the Mail + structure, or the empty string if no id key was provided. + + + + + Whatever url-data was found in the Mail + structure, or the boolean value False (D-Bus type 'b') if no + url-data was provided in the Mail. + + + + + A struture that contains a URL and optional additional data to open a + webmail client, without re-authentication if possible. + + + + This method creates and returns a URL and optional POST data that + allow opening a specific mail in a webmail interface. This + method is implemented only if Supports_Request_Mail_URL flag + is set in MailNotificationFlags. + + See RequestInboxURL for design + rationale. + + + + + + + + + + + +

An interface to support receiving notifications about a e-mail + account associated with this connection.

+ +

In protocols where this is possible, this interface also allows the + connection manager to provide the necessary information for clients + to open a web-based mail client without having to re-authenticate.

+ +

To use this interface, a client MUST first subscribe by passing the + name of this interface to the Connection.AddClientInterest method. The subscription + mechanic aims at reducing network traffic and memory footprint in the + situation where nobody is currently interesting in provided + information. When done with this interface, clients SHOULD call + Connection.RemoveClientInterest to allow the CM to + release resources.

+ +

Protocols have various different levels of Mail Notification support. + To describe the level of support, the interface provides a property + called MailNotificationFlags. + Not all combinations are valid; protocols can be divided into four + categories as follows.

+ +

Connections to the most capable protocols, such as Google's XMPP Mail + Notification extension, have the Supports_Unread_Mails flag (this + implies that they must also have Supports_Unread_Mail_Count, but not + Emits_Mails_Received). On these connections, clients + requiring change notification MUST monitor the + UnreadMailsChanged signal, and + either recover the initial state from the + UnreadMails property (if they require + details other than the number of mails) or the + UnreadMailCount property (if they + are only interested in the number of unread mails). The + MailsReceived signal is never emitted + on these connections, so clients that will display a short-term + notification for each new mail MUST do so in response to emission of + the UnreadMailsChanged signal.

+ +

The most common situation, seen in protocols like MSN and Yahoo, is + that the number of unread mails is provided and kept up-to-date, + and a separate notification is emitted with some details of each new + mail. This is a combination of the following two features, and clients + SHOULD implement one or both as appropriate for their requirements.

+ +

On protocols that have the Emits_Mails_Received flag (which implies + that they do not have Supports_Unread_Mails), the CM does not keep + track of any mails; it simply emits a notification whenever new mail + arrives. Those events may be used for short term display (like a + notification popup) to inform the user. No protocol is known to support + only this feature, but it is useful for integration with libraries that + that do not implement tracking of the number of mails. Clients + requiring these notifications MUST monitor the + MailsReceived signal on any connections + with this flag.

+ +

On protocols that have the Supports_Unread_Mail_Count flag but not + the Supports_Unread_Mails flag, clients cannot display complete + details of unread email, but can display an up-to-date count of the + number of unread mails. To do this, they must monitor the + UnreadMailsChanged signal, and + retrieve the initial state from the + UnreadMailCount property.

+ +

+ Orthogonal features described by the + MailNotificationFlags property include the + RequestSomethingURL methods, which are used to obtain URLs allowing + clients to open a webmail client. Connections SHOULD support as many + of these methods as possible.

+ + + + + diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml new file mode 100644 index 0000000..571bf6d --- /dev/null +++ b/spec/Connection_Interface_Power_Saving.xml @@ -0,0 +1,109 @@ + + + Copyright © 2007-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 +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.

+ + + (as stable API) + +

Some protocols support mechanisms for reducing bandwidth usage—and + hence power usage, on mobile devices—when the user is not directly + interacting with their IM client. For instance, Google Talk's XMPP + server supports queueing incoming presence updates at the client's + instruction; the client can instruct the server to deliver all + outstanding presence updates at a later time. This interface may be + used to instruct the connection manager to enable and disable such + protocol-level features when a screensaver is activated, the device + screen is locked, and so on, by calling the + SetPowerSaving method.

+ +

Enabling power saving SHOULD NOT change behaviour in any way + that is noticable to a user not actively interacting with their client. + For example, delaying presence updates somewhat is unlikely to be + noticed by a user not staring at their device waiting for a contact to + come online; on the other hand, requesting that the server queue + incoming messages would be noticable by the user, so is not an + acceptable effect of calling + SetPowerSaving.

+ + + + +

Turn power saving mode on or off.

+ + +

Depending on the device's activity level, the + connection can have its 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 if protocol-level power saving features should be + activated; False if they should be de-activated. + + + + + + + The current connection has no power saving features. + + + + + + + + +

True if protocol-level power saving features are + currently activated. This property can be changed using the + SetPowerSaving method; change + notifications is via the + PowerSavingChanged signal.

+ + + + + + + The new state of the power saving feature. + + + + The PowerSavingActive + property changed. + + + + + diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml new file mode 100644 index 0000000..8a344d4 --- /dev/null +++ b/spec/Connection_Interface_Presence.xml @@ -0,0 +1,346 @@ + + + + Copyright (C) 2005, 2006 Collabora Limited + + +Copyright (C) 2005, 2006 Nokia Corporation + + +Copyright (C) 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.

+ + + + + + + Mapping used in + Last_Activity_And_Statuses and passed to + SetStatus, representing a collection of + statuses. Use of this mapping with more than one member is + deprecated. + + + + + Structure representing a contact's presence, containing + a last-activity time (deprecated) and a Multiple_Status_Map. + + + + + + Mapping returned by + GetPresence and signalled by + PresenceUpdate, where the keys are + contacts and the values represent their presences. + + + + + + + + + + + + + + + + + + The string identifier of the desired status + + + + + A dictionary of optional parameter names mapped to their variant-boxed values + + + + Request that a single presence status is published for the user, along + with any desired parameters. Changes will be indicated by + PresenceUpdate signals being emitted. + + + + + + + + + + + + Request that all of a user's presence statuses be removed. Be aware + that this request may simply result in the statuses being replaced by a + default available status. Changes will be indicated by + PresenceUpdate signals being emitted. + + + + + + + + + + + An array of the contacts whose presence should be obtained + + + + + Presence information in the same format as for the + PresenceUpdate signal + + + + Get presence previously emitted by + PresenceUpdate for the given contacts. + Data is returned in the same structure as the PresenceUpdate signal. + Using this method in favour of + RequestPresence has the advantage that + it will not wake up each client connected to the PresenceUpdate signal. + + + + + + + + + + + A dictionary of string identifiers mapped to a struct for each status, containing: +
    +
  • a type value from one of the values above
    • +
  • a boolean to indicate if this status may be set on yourself
    • +
  • a boolean to indicate if this is an exclusive status which you + may not set alongside any other
    • +
  • a dictionary of valid optional string argument names mapped to + their types
    • +
+ + + + Get a dictionary of the valid presence statuses for this connection. + This is only available when online because only some statuses will + be available on some servers. + + + + + + + + + + A dictionary of contact handles mapped to a struct containing + a UNIX timestamp of the last activity time (in UTC), and + a dictionary mapping the contact's current status identifiers to + a dictionary of optional parameter names mapped to their + variant-boxed values + + + + This signal should be emitted when your own presence has been changed, + or the presence of the member of any of the connection's channels has + been changed, or when the presence requested by + RequestPresence is available. + + + + + + The string identifier of the status not to publish anymore for the user + + + + Request that the given presence status is no longer published for the + user. Changes will be indicated by + PresenceUpdate signals being emitted. As + with ClearStatus, removing a status may + actually result in it being replaced by a default available status. + + + + + + + The status requested is not currently set + + + + + + + An array of the contacts whose presence should be obtained + + + + Request the presence for contacts on this connection. A PresenceUpdate + signal will be emitted when they are received. This is not the same as + subscribing to the presence of a contact, which must be done using the + 'subscription' ContactList, + and on some protocols presence information may not be available unless + a subscription exists. + + + + + + + + + The presence of the requested contacts is not reported to this connection + + + + + + + + A UNIX timestamp of the user's last activity time (in UTC) + + + + Request that the recorded last activity time for the user be updated on + the server. + + + + + + + This protocol has no concept of idle time + + + + + + + + A dictionary mapping status identifiers to dictionaries, which + map optional parameter names to their variant-boxed values + + + +

Request that the user's presence be changed to the given statuses + and desired parameters. Changes will be reflected by + PresenceUpdate + signals being emitted.

+ +

Statuses whose Connection_Presence_Type + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.

+ + +

The same rationale as for SimplePresence.SetPresence + applies.

+ + +

On certain protocols, this method may be + called on a newly-created connection which is still in the + DISCONNECTED state, and will sign on with the requested status. + If the requested status is not available after signing on, + NotAvailable will be returned and the connection will remain + offline, or if the protocol does not support signing on with + a certain status, Disconnected will be returned.

+ + + + + + + + + + + Client implementations + SHOULD use SimplePresence + instead. + Connection managers implementing + Presence MUST implement SimplePresence too. + + + +

This interface is for services which have a concept of presence which + can be published for yourself and monitored on your contacts. + Telepathy's definition of presence is based on that used by + the Galago project.

+ +

Presence on an individual (yourself or one of your contacts) is modelled as + a last activity time along with a set of zero or more statuses, each of + which may have arbitrary key/value parameters. Valid statuses are defined + per connection, and a list of them can be obtained with the + GetStatuses method.

+ +

(The SimplePresence interface which replaces this one restricts + presences to one status per contact, with an optional message, which is + in practice all that was implemented on this interface.)

+ +

Each status has an arbitrary string identifier which should have an agreed + meaning between the connection manager and any client which is expected to + make use of it. The well-known values defined by the SimplePresence + interface SHOULD be used where possible

+ +

As well as these well-known status identifiers, every status also has a + numerical type value chosen from + Connection_Presence_Type which can be used by the client + to classify even unknown statuses into different fundamental types.

+ +

These numerical types exist so that even if a client does not understand + the string identifier being used, and hence cannot present the presence to + the user to set on themselves, it may display an approximation of the + presence if it is set on a contact.

+ +

The dictionary of variant types allows the connection manager to exchange + further protocol-specific information with the client. It is recommended + that the string (s) argument 'message' be interpreted as an optional + message which can be associated with a presence status.

+ +

If the connection has a 'subscribe' contact list, + PresenceUpdate signals should be emitted to + indicate changes of contacts on this list, and should also be emitted for + changes in your own presence. Depending on the protocol, the signal may + also be emitted for others such as people with whom you are communicating, + and any user interface should be updated accordingly.

+ +

On some protocols, RequestPresence may + only succeed on contacts on your 'subscribe' list, and other contacts will + cause a PermissionDenied error. On protocols where there is no 'subscribe' + list, and RequestPresence succeeds, a client may poll the server + intermittently to update any display of presence information.

+ + + + + diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml new file mode 100644 index 0000000..b89d968 --- /dev/null +++ b/spec/Connection_Interface_Privacy.xml @@ -0,0 +1,94 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + + A string representing the current privacy mode + + + + Return the current privacy mode, which must be one of the values + returned by GetPrivacyModes. + + + + + + + + + + An array of valid privacy modes for this connection + + + + Returns the privacy modes available on this connection. The following + well-known names should be used where appropriate: +
+
allow-all
any contact may initiate communication
+
allow-specified
only contacts on your 'allow' list may initiate communication
+
allow-subscribed
only contacts on your subscription list may initiate communication
+
+ + + + + + The current privacy mode + + + + Emitted when the privacy mode is changed or the value has been + initially received from the server. + + + + + + The desired privacy mode + + + + Request that the privacy mode be changed to the given value, which + must be one of the values returned by GetPrivacyModes. Success is + indicated by the method returning and the PrivacyModeChanged + signal being emitted. + + + + + + + + + + An interface to support getting and setting privacy modes to configure + situations such as not being contactable by people who are not on your + subscribe list. If this interface is not implemented, the default can be + presumed to be allow-all (as defined in GetPrivacyModes). + + + + diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml new file mode 100644 index 0000000..d08b748 --- /dev/null +++ b/spec/Connection_Interface_Renaming.xml @@ -0,0 +1,98 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + + The handle of the original identifier + + + + + The handle of the new identifier + + + +

Emitted when the unique identifier of a contact on the server + changes.

+ +

Any channels associated with the contact's original handle will + continue to be to that handle, and so are no longer useful (unless + the contact renames back, or another contact connects with that + unique ID). Clients may open a similar channel associated with the + new handle to continue communicating with the contact.

+ +

For example, if a GUI client associates text + channels with chat windows, it should detach the old channel + from the chat window, closing it, and associate a channel to the + new handle with the same window.

+ +

If the contact's old handle is in any of the member lists of + a channel which has the groups interface, it will be removed from + the channel and the new handle will be added. The resulting + MembersChanged + signal must be emitted after the + Renamed signal; the reason should be + RENAMED. +

+ +

The handles may be either general-purpose or channel-specific. + If the original handle is general-purpose, the new handle must be + general-purpose; if the original handle is channel-specific, the + new handle must be channel-specific in the same channel. +

+ + + + + + The desired identifier + + + +

Request that the user's own identifier is changed on the server. + If successful, a Renamed signal will + be emitted for the current "self handle" as returned by GetSelfHandle.

+

It is protocol-dependent how the identifier that's actually + used will be derived from the supplied identifier; some sort of + normalization might take place.

+ + + + + + + + + + + An interface on connections to support protocols where the unique + identifiers of contacts can change. Because handles are immutable, + this is represented by a pair of handles, that representing the + old name, and that representing the new one. + + + + diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml new file mode 100644 index 0000000..2f233fa --- /dev/null +++ b/spec/Connection_Interface_Requests.xml @@ -0,0 +1,628 @@ + + + Copyright (C) 2008 Collabora Limited + Copyright (C) 2008 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.

+ + + + + (as stable API) + + +

An enhanced version of the Telepathy connection interface, which can + represent bundles of channels that should be dispatched together, and + does not assume any particular properties by which channels are + uniquely identifiable.

+ +

If this interface is implemented on a connection, then + NewChannels MUST be emitted for + all new channels, even those created with RequestChannel.

+ + + + (as stable API) + + + Enough details of a channel that clients can work out how to dispatch + or handle it. + + + + + The object path of the channel. + + + + + +

Properties of the channel.

+ +

Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.

+ + +

If properties that could change were included, the following + race condition would be likely to exist in some cases:

+ +
    +
  • NewChannels or Get("Channels") includes a property P with + value V1
    • +
  • Client creates a proxy object for the channel
    • +
  • The value of P changes to V2
    • +
  • Client connects to PChanged signal
    • +
  • Client should call Get("P") or GetAll here, to avoid the + race, but client's author has forgotten to do so
    • +
  • Proxy object thinks P == V1, but actually P == V2
    • +
+ +

We've taken the opportunity to make the API encourage the + client author to get it right. Where possible, we intend that + properties whose value will be used in channel dispatching + or other "early" processing will be defined so that they are + immutable (can never change).

+ + +

Each dictionary MUST contain the keys + org.freedesktop.Telepathy.Channel.ChannelType, + org.freedesktop.Telepathy.Channel.TargetHandleType, + org.freedesktop.Telepathy.Channel.TargetHandle, + org.freedesktop.Telepathy.Channel.TargetID + and + org.freedesktop.Telepathy.Channel.Requested. +

+ + +

We expect these to be crucial to the channel-dispatching + process.

+ + + + + + + (as stable API) + It is now guaranteed that + CreateChannel returns the channel before NewChannels announces it + (the reverse was previously guaranteed). + + +

Request that an entirely new channel is created.

+ + +

There is deliberately no flag corresponding to the + suppress_handler argument to + Connection.RequestChannel, + because passing a FALSE value for that argument is deprecated. + Requests made using this interface always behave as though + suppress_handler was TRUE.

+ + + + + + +

A dictionary containing desirable properties, which MUST include + ChannelType. + Some properties + are defined such that only an exact match makes sense, and + connection managers MUST NOT satisfy a request with a channel + where that property does not match; some properties are defined + such that the connection manager MAY treat the request as merely + a hint, and make a best-effort attempt to satisfy it. This is + documented separately for each property.

+ +

If this dictionary contains a property whose semantics + are not known to the connection manager, this method MUST fail + without side-effects (in particular it must not create a new + channel).

+ + +

This is necessary if we want to be able to invent properties + in future that, when used in a request, are hard requirements + rather than just hints. A connection manager that did not know + the semantics of those properties could incorrectly return a + new channel that did not satisfy the requirements.

+ + +

The connection manager MUST NOT respond successfully, + and SHOULD NOT create a new channel or cause any other + side-effects, unless it can create a new channel that satisfies + the client's requirements.

+ +

Properties that will be set by this argument need not have write + access after the channel has been created - indeed, it is + expected that most will be read-only.

+ + + + + +

The Channel object, which MUST NOT be signalled with + NewChannels until after this method + returns.

+ + +

This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.

+ + + + + + +

Properties of the channel that was produced, equivalent to + the properties in Channel_Details. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + Channel_Details.

+ + + + + + + + + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + + + + + An invalid handle was requested as the value of a property whose + value is a handle (like + Channel.TargetHandle), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like Channel.TargetID). + + + + + The request matched the fixed properties of a + Requestable_Channel_Class in + RequestableChannelClasses, but the + allowed arguments did not make sense; for example, a RoomList + was requested, but the Server + property provided was not a valid DNS name. + + + + + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + + + + + The requested channel cannot be created because the target is + offline. + + + + +

The requested channel cannot be created, but in + principle, a similar request might succeed in future. + For instance, this might be because:

+ +
    +
  • a channel matching the request already exists and the + protocol requires that only one such channel can exist at a + time
    • +
  • a channel matching the request has already been requested + (by a previous call to CreateChannel, + EnsureChannel, + Connection.RequestChannel + or similar) and the protocol requires that only one such + channel can exist at a time
    • +
+ + + + + + + + + + + + It is now guaranteed that if + the channel was created by this call to EnsureChannel, it's returned + before NewChannels announces it (the reverse was previously + guaranteed). + + +

Request that channels are ensured to exist.

+ + +

The connection manager is in the best position to determine which + existing channels could satisfy which requests.

+ + + + + + +

A dictionary containing desirable properties, with the same + semantics as the corresponding parameter to + CreateChannel.

+ + + + + +

If false, the caller of EnsureChannel MUST assume that some + other process is handling this channel; if true, the caller of + EnsureChannel SHOULD handle it themselves or delegate it to another + client.

+ +

If the creation of a channel makes several calls to EnsureChannel + (and no other requests) successful, exactly one of those calls MUST + return a true value for this argument.

+ +

If the creation of a channel makes other requests successful, + the value returned for this argument MUST be such that exactly + one of the clients making requests ends up responsible for the + channel. In particular, if + CreateChannel returns a channel + C, any EnsureChannel calls that also return C + MUST return a false value for this argument.

+ + + + + + The Channel object. If it was created as a result of this method + call, it MUST NOT be signalled by + NewChannels until after this method + returns. + + +

This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.

+ + + + + + +

Properties of the channel that was produced, equivalent to + the properties in Channel_Details. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + Channel_Details.

+ + + + + + + + + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + + + + + An invalid handle was requested as the value of a property whose + value is a handle (like + Channel.TargetHandle), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like Channel.TargetID). + + + + + The request matched the fixed properties of a + Requestable_Channel_Class in + RequestableChannelClasses, but the + allowed arguments did not make sense; for example, a RoomList + was requested, but the Server + property provided was not a valid DNS name. + + + + + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + + + + + The requested channel cannot be created because the target is + offline. + + + + + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + + + + + + + + + + + (as stable API) + Added a guarantee of ordering + relative to NewChannel + + +

New channels have been created. The connection manager SHOULD emit + a single signal for any group of closely related channels that are + created at the same time, so that the channel dispatcher can try to + dispatch them to a handler as a unit.

+ +

In particular, if additional channels are created as a side-effect + of a call to CreateChannel, + these channels SHOULD appear in the same NewChannels signal as + the channel that satisfies the request.

+ + +

Joining a MUC Tube in XMPP requires joining the corresponding + MUC (chatroom), so a Text + channel can be created as a side-effect.

+ + +

Every time NewChannels is emitted, it MUST be followed by + a Connection.NewChannel + signal for each channel.

+ + +

The double signal emission is for the benefit of older Telepathy + clients, which won't be listening for NewChannels.

+ +

The more informative NewChannels signal comes first so that + clients that did not examine the connection to find + out whether Requests is supported will see the more informative + signal for each channel first, and then ignore the less + informative signal because it announces a new channel of which + they are already aware.

+ + + + + + The channels and their details. All channels that are signalled + together like this MUST have the same + Bundle + property, which may + either refer to an existing bundle, or establish a new bundle. + + + + + + (as stable API) + + A list of all the channels which currently exist on this connection. + Change notification is via the + NewChannels and + ChannelClosed signals. + + + + + (as stable API) + + Emitted when a channel is closed and hence disappears from the + Channels property. + + + This is redundant with the Closed + signal on the channel itself, but it does provide full change + notification for the Channels property. + + + + + + The channel which has been removed from the Channels property + + + + + + (as stable API) + +

Mapping representing a class of channels that can be requested + from a connection manager, can be handled by a user interface, + are supported by a contact, etc.

+ +

Classes of channel are identified by the fixed values of + a subset of their properties.

+ +

Channel classes SHOULD always include the keys + org.freedesktop.Telepathy.Channel.ChannelType + and + org.freedesktop.Telepathy.Channel.TargetHandleType. +

+ + + + + A D-Bus interface name, followed by a dot and a D-Bus property name. + + + + + + The value of the property. + + + + + + (as stable API) + +

Structure representing a class of channels that can be requested, + identified by a set of properties that identify that class of + channel.

+ + +

This will often just be the channel type and the handle type, + but can include other properties of the channel - for instance, + encrypted channels might require properties that + unencrypted channels do not, like an encryption key.

+ + +

In some cases, these classes of channel may overlap, in the sense + that one class fixes all the properties that another class does, + plus some more properties.

+ + +

For older clients to still be able to understand how to request + channels in the presence of a hypothetical "encryption" interface, + we'd need to represent it like this:

+ +
    +
  • class 1: ChannelType = Text, TargetHandleType = CONTACT
    • +
  • class 2: Channel.ChannelType = Text, + Channel.TargetHandleType = CONTACT, + Encryption.Encrypted = TRUE
    • +
+ + + + + +

The property values that identify this requestable channel class. + These properties MUST be included in requests for a channel of this + class, and MUST take these values.

+ +

Clients that do not understand the semantics of all the + Fixed_Properties MUST NOT request channels of this class, since + they would be unable to avoid making an incorrect request.

+ +

This implies that connection managers wishing to make channels + available to old or minimal clients SHOULD have a channel class + with the minimum number of Fixed_Properties, and MAY additionally + have channel classes with extra Fixed_Properties.

+ +

Interface designers SHOULD avoid introducing fixed properties + whose types are not serializable in a .manager + file.

+ + +

Connection managers with a fixed property that is not + serializable cannot have a complete .manager + file.

+ + + + + + +

Properties that MAY be set when requesting a channel of this + channel type and handle type.

+ +

This array MUST NOT include properties that are in the + Fixed_Properties mapping.

+ +

Properties in this array may either be required or optional, + according to their documented semantics.

+ + +

For instance, if + TargetHandleType takes a value that is not Handle_Type_None, + one or the other of TargetHandle and TargetID is required. + Clients are expected to understand the documented relationship + between the properties, so we do not have separate arrays + of required and optional properties.

+ + +

If this array contains the + Bundle + property, then this class of channel can be combined with other + channels with that property in a request, or added to an existing + bundle. If not, this signifies that the connection manager is + unable to mark channels of this class as part of a bundle - this + means that to the remote contact they are likely to be + indistinguishable from channels requested separately.

+ + + + + + (as stable API) + +

The classes of channel that are expected to be available on this + connection, i.e. those for which + CreateChannel can reasonably + be expected to succeed. User interfaces can use this information + to show or hide UI components.

+ +

This property cannot change after the connection has gone to + state Connection_Status_Connected, so there is no change + notification (if the connection has context-dependent capabilities, + it SHOULD advertise support for all classes of channel that it might + support during its lifetime). Before this state has been reached, + the value of this property is undefined.

+ + +

This is not on an optional interface, because connection + managers can always offer some sort of clue about the channel + classes they expect to support (at worst, they can announce + support for everything for which they have code).

+ + + + + + + diff --git a/spec/Connection_Interface_Resources.xml b/spec/Connection_Interface_Resources.xml new file mode 100644 index 0000000..716089c --- /dev/null +++ b/spec/Connection_Interface_Resources.xml @@ -0,0 +1,212 @@ + + + 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 1) + + + +

An interface on connections to show contact attributes for + specific resources of a contact, if the protocol supports + multiple resources. Resources are most common in XMPP, hence the + name of this interface, but they are also present in MSN, where + they are called points of presence.

+ +

When a client requests some attribute of a contact using its + handle on the connection, the CM uses an algorithm to choose the + most appropriate resource for the job. If there is only one + resource, then the choice is obvious. If, however, there is more + than one resource connected at any one time, the CM either + aggregates all appropriate information to return (in the case of + capabilities), or chooses one specific resource (in the case of + presence).

+ +

Resources in XMPP have names, and it can be extremely useful + for the user to be able to know which resources of a contact are + online, providing the names are human-readable. Before now, + resources have not been exposed in Telepathy, but this interface + attempts to change this.

+ +

When using this interface, it is a little like using the + Contacts interface, but only resource-specific + attributes are ever returned. The resource-specific contact + attributes are decided on by the CM, but XMPP's are listed + below:

+ +
    +
  • SimplePresence/presence
    • +
  • ContactCapabilities/capabilities
    • +
  • ClientTypes/client-types
    • +
+ + + + + + Return the resource information of the given contacts. If any + of the contact attributes for specific resources of the given + contacts' are not known return immediately without waiting for + a reply. + + + + + The contacts whose resource attributes should be returned. + + + + + +

The contacts' resources and the contact attributes specific + to each resource. 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.

+ +

For every contact handle passed into this method, it is + guaranteed that there will be a key in the returned map + that corresponds to said handle. If there is no information + regarding the contact the resource information map will be + empty.

+ + + + + + + + + + + + + The resource string is never human-readable. + + + + + The resource string might be human-readable. + + + + + + +

Whether the resources returned from GetResources + are human readable or not.

+ +

If the connection manager knows that all resource names are + automatically generated, then the resource strings mean + nothing to the user. Showing these strings in the UI would + be confusing, so by setting this to + Resources_Human_Readability_Never, the UI is advised not to + show resources.

+ +

If on the other hand, all resources are set to nice names + (such as "office" or "home") then it might be wise to expose + these strings in the UI, so this property would be set to + Resources_Human_Readability_Maybe. This is the case in XMPP -- + most resources are set in a way that the user can deduce some + information from them. The absence of an Always enum value is + because in the case of XMPP, the resource string could be + partially human-readable (as on Google Talk, where a resource + of "home" is changed by the server to a unique string like + "home_1234fdec") or not at all human-readable.

+ + + + + + + Emitted when a contact has a resource added or removed, or any + contact attribute for any resource changes. + + + + + The contact. + + + + + The contact's resource information. All resource information + is given, not just the details which have changed. + + + + + + + A map of a contact's resources to their resource-specific + information. + + + + +

The name of the resource.

+ + + + + + A map of contact attributes whose data is specific to this + resource. + + + + + + Mapping returned by + GetResources, representing a + collection of Contacts, their resources, and their + resource-specific contact attributes. + + + + A contact. + + + + + + A map of the contact's resources to their resource-specific + information. + + + + + + +

The same mapping that would be returned by + GetResources for this contact.

+ + + + + + diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml new file mode 100644 index 0000000..b135c04 --- /dev/null +++ b/spec/Connection_Interface_Service_Point.xml @@ -0,0 +1,136 @@ + + + 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.

+ + + (as stable API) + + +

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 the InitialServicePoint + property in a channel request. + + + +

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

+ +

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

+ +
+  ServicePointInfo = (
+    Service_Point: (
+      Service_Point_Type: 1 (Emergency),
+      Service_Point: "urn:service:sos"
+    ),
+    Service_IDs: [ "911", "112" ]
+  )
+
+ + + + + + The list of all (known) service points. + + + + + + +

The new value of + KnownServicePoints.

+ + + + Emitted when the list of known service points (or their IDs) has + changed. + + + + + A service point. + + + The service type. + + + + + String representation of the service point. The representation is + service specific; it may be a 'service' Uniform Resource Name as + specified by RFC 5031, + or may be in some other form. Empty, unused or unknown value is + represented by "". + + + + + + + The various types of service points a channel might connect to. + + + + + The channel is not communicating with a service point, or it is not + known whether it is communicating with a service point (e.g. an + ordinary call). + + + + + + The service point is a generic emergency point. + + + + + + The service point is some kind of counseling service (ie, mental health + or child-services counseling). + + + + + + diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml new file mode 100644 index 0000000..7788161 --- /dev/null +++ b/spec/Connection_Interface_Simple_Presence.xml @@ -0,0 +1,634 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + + + A struct representing the presence of a contact. + + + + The presence type, e.g. Connection_Presence_Type_Away. + + + + + The string identifier of the status, e.g. "brb", as defined in the + Statuses property. + + + + +

The user-defined status message, e.g. "Back soon!".

+ +

Clients SHOULD set the status message for the local + user to the empty string, unless the user has actually provided + a specific message (i.e. one that conveys more information than the + Status).

+ +

User interfaces SHOULD regard an empty status message as unset, + and MAY replace it with a localized string corresponding to the + Status or Type.

+ + + Use case: Daf sets his status in Empathy by choosing the Welsh + translation of "Available" from a menu. + It is more informative for his English-speaking colleagues + to see the English translation of "Available" (as localized + by their own clients) than to see "Ar Gael" (which they don't + understand anyway). + + + + + + + + Mapping returned by GetPresences + and signalled by PresencesChanged, + indicating the presence of a number of contacts. + + + + A contact + + + + + The contact's presence + + + + + + + A struct containing information about a status. + + + + The type of a presence. This SHOULD NOT be used as a way to set + statuses that the client does not recognise (as explained in + SetPresence), but MAY be used to check + that the client's assumptions about a particular status name + match the connection manager's. + + + + + If true, the user can set this status on themselves using + SetPresence. + + + + + If true, a non-empty message can be set for this status. Otherwise, + the empty string is the only acceptable message. + + + On IRC you can be Away with a status message, but if you are + available you cannot set a status message. + + + + + + + + A mapping describing possible statuses. + + + + + The string identifier of this status. + + + + + Details of this status. + + + + + + + +

The string identifier of the desired status. Possible status + identifiers are defined in the + Statuses property.

+ +

Clients MUST NOT set a status whose string value they do not + recognise, even if its presence type in Statuses + matches what the user requested.

+ + +

Suppose a protocol has statuses that include 'phone' (of type + BUSY) and 'in-a-meeting' (of type BUSY), but there is no + generic 'busy' status.

+ +

If the user requests "Busy" status from a menu, a + client author might be tempted to pick an arbitrary status + that has type BUSY. However, on this protocol, neither of + the choices would be appropriate, and incorrect information + about the user would be conveyed.

+ + +

Statuses whose Connection_Presence_Type + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.

+ + +

To go offline, call Disconnect + instead. The "error" and "unknown" statuses make no sense.

+ + + + + + The status message associated with the current status. + + + +

Request that the presence status and status message are published for + the connection. Changes will be indicated by + PresencesChanged + signals being emitted.

+ +

This method may be called on a newly-created connection while it + is still in the DISCONNECTED state, to request that when the + connection connects, it will do so with the selected status.

+ +

In DISCONNECTED state the + Statuses + property will indicate which statuses are allowed to be set + while DISCONNECTED (none, if the Connection Manager doesn't allow + this). This value MUST NOT be cached, as the set of allowed + presences might change upon connecting.

+ + + + + + Either the specified status is not supported, the specified + status cannot be set on the user themselves, or a non-empty + message was supplied for a status that does not + accept a message. + + + + + + + + + + An array of the contacts whose presence should be obtained. + + + + +

Presence information in the same format as for the + PresencesChanged signal. + The returned mapping MUST include an entry for each contact + in the method's argument.

+ +

The definition of the connection presence types Unknown + and Offline means that if a connection manager will return + Unknown for contacts not on the subscribe list, it MUST delay + the reply to this method call until it has found out which + contacts are, in fact, on the subscribe list.

+ + + + Get presence previously emitted by + PresencesChanged for the given + contacts. Data is returned in the same structure as the + PresencesChanged signal; no additional network requests are made. + + + + + + + While discovering the subscribe list in order to distinguish + between Unknown and Offline statuses, a network error occurred. + + + + + + + + +

A dictionary where the keys are the presence statuses that are + available on this connection, and the values are the corresponding + presence types.

+ +

While the connection is in the DISCONNECTED state, it contains + the set of presence statuses allowed to be set before connecting. + The connection manager will attempt to set the appropriate status + when the connection becomes connected, but cannot necessarily + guarantee it. The available statuses cannot change until the + connection status changes, so there is no change notification.

+ +

While the connection is in the CONNECTED state, this property + contains the set of presence statuses which are actually available + on this protocol. This set is constant for the remaining lifetime + of the connection, so again, there is no change notification.

+ +

While the connection is in the CONNECTING state, the value of + this property is undefined and SHOULD NOT be used. It can change + at any time without notification (in particular, any cached values + from when the connection was in the DISCONNECTED or CONNECTING + state MUST NOT be assumed to still be correct when the state has + become CONNECTED).

+ +

This property MUST include the special statuses "unknown" and + "error" if and only if the connection manager can emit them + as a contact's status.

+ + + For instance, connection managers for local-xmpp (XEP-0174) would + omit "unknown" since there is no such concept. + + + + + + + + A dictionary of contact handles mapped to the status, + presence type and status message. + + + + This signal should be emitted when your own presence has been changed, + or the presence of the member of any of the connection's channels has + been changed. + + + + + + + An invalid presence type used as a null value. This value MUST NOT + appear in the Statuses property, + or in the result of GetStatuses + on the deprecated Presence + interface. + + + + + Offline + + + + + Available + + + + + Away + + + + + Away for an extended time + + + + + Hidden (invisible) + + + + + + Busy, Do Not Disturb. + + + + + + Unknown, unable to determine presence for this contact, for example + if the protocol only allows presence of subscribed contacts. + + + + + + Error, an error occurred while trying to determine presence. The + message, if set, is an error from the server. + + + + + + +

A type for communication access control. These control + policies are used in + CommunicationPolicy.DRAFT + as well as most rich presence interfaces.

+ +

New interfaces should use this type, and NOT + Rich_Presence_Access_Control_Type.

+ + + +

Only allow contacts that are in a certain whitelist.

+ +

The associated variant + in Access_Control is a list of + Contact_Handle representing + the whitelist, with signature au.

+ + + + + Allow contacts in the user's 'publish' list. The associated + variant in Access_Control is ignored. + + + + +

Only allow contacts that are in a certain group.

+ +

The associated variant in Access_Control is a + Group_Handle representing the permitted + group.

+ + + + + Allow all contacts. The associated + variant in Access_Control is ignored. + + + + + Allow all contacts in the user's 'subscribe' or 'publish' + list. The associated variant in Access_Control is + ignored. + + + + + Forbid all contacts. The associated variant in + Access_Control is ignored. + + + + +

The access control rule is too complex to be represented + in the current Telepathy API. The associated variant is + meaningless. Setting this mode is never valid; the + connection manager MUST raise an error if this is attempted.

+ + + XEP-0016 Privacy Lists can easily produce access control + mechanisms that can't be expressed in a simpler API. We + need to be able to at least indicate that fact. + + +

The associated variant in Access_Control is + ignored.

+ + + + + + +

A type of access control for Rich_Presence_Access_Control. + For most types, the exact access control is given by an associated + variant.

+ + +

These are the access control types from XMPP publish/subscribe + (XEP-0060).

+ + +

Location + uses this for historical reasons, new interfaces will use + Access_Control_Type.

+ + + + + The associated variant is a list of contacts (signature 'au', + Contact_Handle[]) who can see the extended presence information. + + + + + All contacts in the user's 'publish' contact list can see the + extended presence information. The associated variant is ignored. + + + + + The associated variant is a handle of type Group (signature 'u', + Group_Handle) representing a group of contacts who can see the + extended presence information. + + + + + Anyone with access to the service can see the extended presence + information. + + + + + + +

An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence + interfaces.

+ +

New interfaces should use this type, and NOT + Rich_Presence_Access_Control.

+ + + + + The type of access control to apply. + + + + + Any additional information required by the Type. The required + type and semantics are defined for each + Access_Control_Type. + + + + + + +

An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence interfaces + such as Location.

+ +

Location + uses this for historical reasons, new interfaces will use + Access_Control_Type.

+ + + + + The type of access control to apply. + + + + + Any additional information required by the Type. The required + type and semantics are defined for each + Rich_Presence_Access_Control_Type. + + + + + + +

The same struct that would be returned by + GetPresences + (always present with some value if information from the + SimplePresence interface was requested)

+ + + + +

This interface is for services which have a concept of presence which + can be published for yourself and monitored on your contacts.

+ +

Presence on an individual (yourself or one of your contacts) is + modelled as a status and a status message. Valid statuses are defined + per connection, and a list of those that can be set on youself + can be obtained from the + Statuses + property.

+ +

Each status has an arbitrary string identifier which should have an + agreed meaning between the connection manager and any client which is + expected to make use of it. The following well-known values should be + used where possible to allow clients to identify common choices:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
status identifierConnection_Presence_Typecomments
availableConnection_Presence_Type_Available
awayConnection_Presence_Type_Away
brbConnection_Presence_Type_AwayBe Right Back (a more specific form of Away)
busyConnection_Presence_Type_Busy
dndConnection_Presence_Type_BusyDo Not Disturb (a more specific form of Busy)
xaConnection_Presence_Type_Extended_AwayExtended Away
hiddenConnection_Presence_Type_HiddenAlso known as "Invisible" or "Appear Offline"
offlineConnection_Presence_Type_Offline
unknownConnection_Presence_Type_Unknownspecial, see below
errorConnection_Presence_Type_Errorspecial, see below
+ +

As well as these well-known status identifiers, every status also has + a numerical type value chosen from + Connection_Presence_Type which can be + used by the client to classify even unknown statuses into different + fundamental types.

+ +

These numerical types exist so that even if a client does not + understand the string identifier being used, and hence cannot present + the presence to the user to set on themselves, it may display an + approximation of the presence if it is set on a contact.

+ +

As well as the normal status identifiers, there are two special ones + that may be present: 'unknown' with type Unknown and 'error' with type + Error. 'unknown' indicates that it is impossible to determine the + presence of a contact at this time, for example because it's not on the + 'subscribe' list and the protocol only allows one to determine the + presence of contacts you're subscribed to. 'error' indicates that there + was a failure in determining the status of a contact.

+ +

If the connection has a 'subscribe' contact list, + PresencesChanged + signals should be emitted to indicate changes of contacts on this list, + and should also be emitted for changes in your own presence. Depending + on the protocol, the signal may also be emitted for others such as + people with whom you are communicating, and any user interface should + be updated accordingly.

+ + + + diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml new file mode 100644 index 0000000..d75d866 --- /dev/null +++ b/spec/Connection_Manager.xml @@ -0,0 +1,614 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005-2008 Nokia Corporation + Copyright (C) 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.

+ + + + + +

The name of a connection manager, found in its well-known + bus name and object path. This must be a non-empty string of + ASCII letters, digits and underscores, starting with a letter. + This is typically the name of the executable with any "telepathy-" + prefix removed, and any hyphen/minus signs replaced by + underscores.

+ +

Connection manager names SHOULD NOT be the same as the name of + the protocol they implement.

+ + +

This is likely to lead to conflicts between different + implementations of the same protocol (or indeed inability + to distinguish between the different implementations!). The + Telepathy project traditionally uses some sort of pun (Haze is + based on libpurple, Salut implements a protocol often called + Bonjour, and Wilde implements the OSCAR protocol).

+ + +

Connection manager names SHOULD NOT be the same as the name of + a library on which they are based.

+ + +

We often abbreviate, for instance, telepathy-haze as "Haze", + but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause + confusion between the connection manager and the library it + uses. Please don't repeat that mistake.

+ + + Prior to version 0.17.1, the allowed + characters were not specified + + + + +

An instant messaging protocol. It must consist only of ASCII + letters, digits and hyphen/minus signs (U+002D "-"), and must start + with a letter. Where possible, this SHOULD be + chosen from the following well-known values:

+ +
    +
  • aim - AOL Instant Messenger (OSCAR or TOC)
    • +
  • gadugadu - Gadu-Gadu
    • +
  • groupwise - Novell Groupwise
    • +
  • icq - ICQ (OSCAR)
    • +
  • irc - Internet Relay Chat (RFC 1459, 2810-2813)
    • +
  • jabber - XMPP (RFC 3920, 3921) or Jabber
    • +
  • local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)
    • +
  • msn - MSNP (Windows Live Messenger)
    • +
  • myspace - MySpaceIM
    • +
  • mxit - MXit
    • +
  • napster - Napster
    • +
  • qq - Tencent QQ
    • +
  • sametime - IBM Lotus Sametime
    • +
  • silc - SILC
    • +
  • sip - Session Initiation Protocol (SIP), with or without + SIMPLE support
    • +
  • skype - Skype
    • +
  • tel - telephony (the + PSTN, + including GSM, CDMA and fixed-line telephony)
    • +
  • trepia - Trepia
    • +
  • yahoo - YMSG (Yahoo! Messenger)
    • +
  • yahoojp - Japanese version of YMSG
    • +
  • zephyr - Zephyr
    • +
+ + Prior to version 0.17.1, the allowed + characters were not specified + + + + A struct representing an allowed parameter, as returned + by GetParameters on the ConnectionManager interface. + + A string parameter name + + + A bitwise OR of the parameter flags + + + A string containing the D-Bus type signature + for this parameter + + + The default value (if the Has_Default flag is not + present, there is no default and this takes some dummy value, + which SHOULD be of the appropriate D-Bus type) + + + + + + + This parameter is required for connecting to the server. + + + + + This parameter is required for registering an account on the + server. + + + + + This parameter has a default value, which is returned in + GetParameters; not providing this parameter is equivalent to + providing the default. + + + + +

This parameter should be considered private or secret; for + instance, clients should store it in a "password safe" like + gnome-keyring or kwallet, omit it from debug logs, and use a + text input widget that hides the value of the parameter.

+ +

(Clients that support older connection managers may also treat + any parameter whose name contains "password" as though it had this + flag.)

+ + + + + +

This parameter is also a D-Bus property on the resulting + Connection; a + parameter named com.example.Duck.Macaroni with this + flag corresponds to the Macaroni property on the + com.example.Duck interface. Its value can be queried + and possibly changed on an existing Connection using methods on the + org.freedesktop.DBus.Properties interface.

+ +

When a parameter with this flag is changed with Account.UpdateParameters, the + account manager will attempt to update its value on any running + connections. Thus, clients generally do not need to directly access + or update the connection property; instead, they SHOULD manipulate + Account.Parameters.

+ + +

This allows runtime-configurable options to be stored and + maintained by the AccountManager, without needing to + invent a separate account preference for “properties that should + be set on the connection as soon as it is created”. It was + originally invented to manage Cellular + preferences.

+ + + + + + + + + + The required protocol name + + + + + An array of structs representing possible parameters. + + + + Get a list of the parameters which must or may be provided to the + RequestConnection method when connecting + to the given protocol, + or registering (the boolean "register" parameter is available, + and set to true). + + + + + The requested protocol is not supported by this manager + + + + + + + +

A map from protocol identifiers supported by a connection + manager to the immutable properties of the corresponding + Protocol objects.

+ + + + A protocol name + + + + The immutable properties of the corresponding + Protocol object + + + + + +

A map from protocol identifiers supported by this connection + manager to the immutable properties of the corresponding + Protocol objects.

+ + +

Providing the immutable properties here means that + when the API of Protocol objects has been finalized, + most clients will only need one D-Bus round trip to interrogate + the ConnectionManager about all its protocols.

+ + +

If this map is empty or missing, clients SHOULD fall back to + calling ListProtocols and + GetParameters.

+ + + + + + + The keys of the Protocols map. + + + + Get a list of protocol identifiers that are implemented by this + connection manager. + + + + + + + The D-Bus service where the connection object can be found + + + + + The object path of the Connection object on this service + + + + + The identifier for the protocol this connection uses + + + + Emitted when a new Connection object + is created. + + + + + + + The protocol identifier + + + + + A dictionary mapping parameter names to values of the appropriate + type, as indicated by GetParameters + and the well-known list of names and value types documented on the + Connection_Parameter_Name type. + + + + + A D-Bus service name where the new Connection object can be found + + + + + The D-Bus object path to the Connection on this service + + + +

Request a + Connection + object representing a given account on a given + protocol with the given parameters. The method returns the bus name + and the object path where the new Connection object can be found, + which should have the status of Connection_Status_Disconnected, to + allow signal handlers to be attached before connecting is started + with the + Connect + method.

+ +

The parameters which must and may be provided in the parameters + dictionary can be discovered with the + GetParameters method. These + parameters, their types, and their default values may be cached + in files so that all available connection managers do not need to be + started to discover which protocols are available.

+ +

To request values for these parameters from the user, a client must + have prior knowledge of the meaning of the parameter names, so the + well-known names and types defined by the + Connection_Parameter_Name type should be used where + appropriate.

+ +

Connection manager authors SHOULD avoid introducing parameters + whose default values would not be serializable in a + .manager file.

+ + +

The same serialization format is used in Mission Control + to store accounts.

+ + +

Every successful RequestConnection call will cause the emission of a + NewConnection signal for the same newly + created connection. The + requester can use the returned object path and service name + independently of the emission of that signal. In that case this signal + emission is most useful for, e.g. other processes that are monitoring + the creation of new connections.

+ + + + + + The requested protocol is not supported by this manager + + + + + The requested connection already appears to exist + + + + + Unrecognised connection parameters + + + + + + + + +

Well-known connection parameter names, along with their expected + type. Where possible, connection managers should use names and types + from this list in the Parameters that may be passed + to RequestConnection.

+ +
+
account (s)
+
The identifier for the user's account on the server
+ +
server (s)
+
A fully qualified domain name or numeric IPv4 or IPv6 address. + Using the fully-qualified domain name form is recommended whenever + possible. If this parameter is specified and the account for that + protocol also specifies a server, this parameter should override + that in the user id.
+ +
port (q)
+
A TCP or UDP port number. If this parameter is specified and the + account for that protocol also specifies a port, this parameter + should override that in the account.
+ +
password (s)
+
A password associated with the account.
+ +
require-encryption (b)
+
Require encryption for this connection. A connection should fail + to connect if require-encryption is set and an encrypted connection + is not possible.
+ +
register (b)
+
This account should be created on the server if it does not + already exist.
+ +
ident (s)
+
The local username to report to the server if necessary, such as + in IRC.
+ +
fullname (s)
+
The user's full name if the service requires this when + authenticating or registering.
+ +
stun-server (s)
+
The IP address or FQDN of a STUN server to use for NAT traversal, + without any ":port" suffix.
+ +
stun-port (q)
+
The UDP port number on the stun-server to use for STUN. Only + significant if the stun-server is also supplied.
+ +
keepalive-interval (u)
+
+

The time in seconds between pings sent to the server to ensure + that the connection is still alive, or 0 to disable such + pings.

+ +

This parameter is superseded by the KeepaliveInterval + property, which can be updated on an already-established + connection as well as being specified when requesting the + connection. Clients SHOULD provide that parameter instead, if + allowed; new connection managers SHOULD implement it in + preference to this one.

+
+
+ +

The following well-known parameter names correspond to D-Bus + properties, and thus their Conn_Mgr_Param_Flags + should include DBus_Property. See that flag for more details on this + kind of parameter.

+ + + + + + + +

A list of the extra interfaces provided by this connection manager + (i.e. extra functionality that can be provided even before a + connection has been created).

+ +

No interfaces suitable for listing in this property are currently + defined; it's provided as a hook for possible future + functionality.

+ +

To be compatible with older connection managers, if retrieving + this property fails, clients SHOULD assume that its value is + an empty list.

+ +

Connection managers with a non-empty list of Interfaces MUST + represent them in the .manager file, if they have one, + as an Interfaces key in the + group headed [ConnectionManager], whose value is a list + of strings each followed by a semicolon.

+ + + + + +

A D-Bus service which allows connections to be created. The manager + processes are intended to be started by D-Bus service activation.

+ +

For service discovery, each Telepathy connection manager must have + a connection manager name (see + Connection_Manager_Name for syntax).

+ +

The connection manager must then provide a well-known bus name of + org.freedesktop.Telepathy.ConnectionManager.cmname + where cmname is its connection manager name. If it makes sense + to start the connection manager using D-Bus service activation, it + must register that well-known name for service activation by installing + a .service file.

+ +

Clients can list the running connection managers by calling the + ListNames method on the D-Bus daemon's org.freedesktop.DBus interface + and looking for names matching the above pattern; they can list the + activatable connection managers by calling ListActivatableNames, and + they should usually combine the two lists to get a complete list of + running or activatable connection managers.

+ +

When the connection manager is running, it must have an object + implementing the ConnectionManager interface at the object path + /org/freedesktop/Telepathy/ConnectionManager/cmname. +

+ +

Connection managers' capabilities can be determined dynamically by + calling their ListProtocols method, then + for each protocol of interest, calling + GetParameters to discover the required and + optional parameters. + However, since it is inefficient to activate all possible connection + managers on the system just to find out what they can do, there + is a standard mechanism to store static information about CMs in + ".manager files".

+ +

To look up a connection manager's supported protocols, clients + should search the data directories specified by + the + freedesktop.org XDG Base Directory Specification ($XDG_DATA_HOME, + defaulting to $HOME/.local/share if unset, followed by + colon-separated paths from $XDG_DATA_DIRS, defaulting to + /usr/local/share:/usr/share if unset) for the first file named + telepathy/managers/cmname.manager that can be + read without error. This file has the same syntax as a + freedesktop.org Desktop Entry file.

+ +

Clients must still support connection managers for which no + .manager file can be found, which they can do by activating + the connection manager and calling its methods; the + .manager file is merely an optimization. Connection managers + whose list of protocols can change at any time (for instance, via + a plugin architecture) should not install a .manager + file.

+ +

The .manager file SHOULD have a group headed + [ConnectionManager], containing a key + Interfaces representing + Interfaces as a sequence of strings + each followed by a semicolon (the "localestrings" type from the Desktop + Entry Specification).

+ +

The [ConnectionManager] group SHOULD NOT contain keys + ObjectPath or BusName. If it does, they MUST + be ignored.

+ + +

The object path and bus name are derivable from the connection + manager's name, which is part of the filename, so these keys are + redundant. They were required in very old versions of Telepathy.

+ + +

For each protocol name proto that would be returned by + ListProtocols, the .manager file contains a group + headed [Protocol proto]. For each parameter + p that would be returned by GetParameters(proto), the + .manager file contains a key param-p with a value + consisting of a D-Bus signature (a single complete type), optionally + followed by a space and a space-separated list of flags. The supported + flags are:

+ +
    +
  • required, corresponding to + Conn_Mgr_Param_Flag_Required
    • +
  • register, corresponding + to Conn_Mgr_Param_Flag_Register
    • +
  • secret, corresponding + to Conn_Mgr_Param_Flag_Secret
    • +
  • dbus-property, corresponding + to Conn_Mgr_Param_Flag_DBus_Property
    • +
+ +

The group may also contain a key default-p + whose value is a string form of the default value for the parameter. + If this key exists, it sets the default, and also sets the flag + Conn_Mgr_Param_Flag_Has_Default. The default value is formatted + according to the D-Bus signature as follows:

+ +
+
s (string)
+
The UTF-8 string, with the standard backslash escape + sequences supported by the Desktop Entry Specification + (the "localestring" type from the Desktop Entry Specification)
+
o (object path)
+
The object path as an ASCII string
+
b (boolean)
+
"true" (case-insensitively) or "1" means True, "false" + (case-insensitively) or "0" means False; when writing a file, + "true" and "false" SHOULD be used
+
y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)
+
ASCII decimal integer
+
n, i, x (16-, 32-, 64-bit signed integer)
+
ASCII decimal integer, optionally prefixed with "-"
+
d (double-precision floating point)
+
ASCII decimal number
+
as (array of string)
+
A sequence of UTF-8 strings each followed by a semicolon, with + any semicolons they contain escaped with a backslash + (the "localestrings" type from the Desktop Entry Specification)
+
+ +

Currently, no other D-Bus signatures are allowed to have default values, + but clients parsing the .manager file MUST ignore defaults + that they cannot parse, and treat them as if the + default-p key was not present at all.

+ +

It is not required that a connection manager be able to support multiple + protocols, or even multiple connections. When a connection is made, a + service name where the connection object can be found is returned. A + manager which can only make one connection may then remove itself from its + well-known bus name, causing a new connection manager to be activated when + somebody attempts to make a new connection.

+ + + Prior to version 0.17.2, support for + CMs with no .manager file was not explicitly required. + Prior to version 0.17.16 the serialization + of string arrays (signature 'as') was not defined + + + diff --git a/spec/Debug.xml b/spec/Debug.xml new file mode 100644 index 0000000..70a82e9 --- /dev/null +++ b/spec/Debug.xml @@ -0,0 +1,165 @@ + + + Copyright (C) 2009 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 stable API) + + +

An interface for providing debug messages.

+ +

This interface is primarily provided by one object per + service, at the path /org/freedesktop/Telepathy/debug.

+ + + + + TRUE if the NewDebugMessage signal + should be emitted when a new debug message is generated. + + + + + + Retrieve buffered debug messages. An implementation could have a + limit on how many message it keeps and so the array returned from + this method should not be assumed to be all of the messages in + the lifetime of the service. + + + + + A list of debug messages. + + + + + + + Emitted when a debug messages is generated if the + Enabled property is set to TRUE. + + + + + Timestamp of the debug message. + + + + + Domain of the debug message, as described in the Debug_Message struct. + + + + + Level of the debug message. + + + + + The text of the debug message. + + + + + + + + Log level for errors. Error messages are always fatal, resulting + in the service terminating after something completely + unexpected occurred. + + + + + Log level for critical messages. Critical messages are messages + that the service might predict and it is up to the service itself + to decide whether to terminate following a critical message. + + + + + Log level for warnings. + + + + + Log level for messages. + + + + + Log level for information messages. + + + + + Log level for debug messages. + + + + + + + A struct representing a debug message, as returned by + GetMessages. + + + + + Timestamp of the debug message. This is a double to allow + more accuracy in the time the message was logged. + + + + + +

Domain of the debug message. This is used to identify + the source of debug messages. For example, debug messages + from a connection manager could have this Domain struct + member be the name of the connection manager, and logs + from any helper library could have the name of the helper + library.

+ +

The domain could also contain a category as to where + the log message originated separated by a forward-slash. + For example, if a debug message was output in a connection + manager called "dummy", in the file-transfer code, this + Domain struct member might be dummy/file-transfer.

+ + + + + + Level of the debug message. This states the severity of the + debug message. + + + + + + The text of the debug message. + + + + + + + diff --git a/spec/Media_Session_Handler.xml b/spec/Media_Session_Handler.xml new file mode 100644 index 0000000..70aa750 --- /dev/null +++ b/spec/Media_Session_Handler.xml @@ -0,0 +1,81 @@ + + + Copyright (C) 2005, 2006 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + + + Use StreamHandler.Error + on each StreamHandler object instead. + + + Informs the connection manager that an error occured in this session. + If used, the connection manager must terminate the session and all of + the streams within it, and may also emit a StreamError + signal on the channel for each stream within the session. + + + + + + The path of a new object implementing the StreamHandler + interface. + + + + + The unique ID of the new stream + + + + + Type of media that this stream should handle + + + + + Direction of this stream + + + + Emitted when a new stream handler has been created for this + session. + + + + + Inform the connection manager that a client is ready to handle + this session handler (i.e. that it has connected to the + NewStreamHandler signal and done any + other necessary setup). + + + + An media session handler is an object that handles a number of synchronised + media streams. + + + + diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml new file mode 100644 index 0000000..123ea8b --- /dev/null +++ b/spec/Media_Stream_Handler.xml @@ -0,0 +1,725 @@ + + + Copyright (C) 2005-2008 Collabora Limited + Copyright (C) 2005-2008 Nokia Corporation + Copyright (C) 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.

+ + + + + + + + + + + + + + + + + + + + + + + + Information about a codec supported by a client or a peer's client. + + + + + The codec's payload identifier, as per RFC 3551 (static or dynamic) + + + + The codec's name + + + Type of stream this codec supports + + + Sampling frequency in Hertz + + + Number of supported channels + + + Codec-specific optional parameters + + + + + + + The IP addresses of possible STUN servers to use for NAT traversal, as + dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. + This property cannot change once the stream has been created, so there + is no change notification. The IP addresses MUST NOT be given as DNS + hostnames. + + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + + + + + + + + True if we were the creator of this stream, false otherwise. + + This information is needed for some nat traversal mechanisms, such + as ICE-UDP, where the creator gets the role of the controlling agent. + + + + + + + +

The transport (NAT traversal technique) to be used for this + stream. Well-known values include:

+ +
+
none
+
Raw UDP, with or without STUN, should be used. If the + STUNServers property is non-empty, + STUN SHOULD be used.
+ +
stun
+
A deprecated synonym for 'none'.
+ +
gtalk-p2p
+
Google Talk peer-to-peer connectivity establishment should be + used, as implemented in libjingle 0.3.
+ +
ice-udp
+
Interactive Connectivity Establishment should be used, + as defined by the IETF MMUSIC working group.
+ +
wlm-8.5
+
The transport used by Windows Live Messenger 8.5 or later, + which resembles ICE draft 6, should be used.
+ +
wlm-2009
+
The transport used by Windows Live Messenger 2009 or later, + which resembles ICE draft 19, should be used.
+
+ +

This property cannot change once the stream has been created, so + there is no change notification.

+ + + + + +

A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:

+ +
+
ip - s
+
The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + +
+ +
type - s
+
+

Either udp for UDP (UDP MUST be assumed if this + key is omitted), tcp for TCP, or + tls.

+ +

The precise meaning of this key depends on the + NATTraversal property: if + NATTraversal is ice-udp, tls means + TLS over TCP as referenced by ICE draft 19, and if + NATTraversal is gtalk-p2p, tls means + a fake SSL session over TCP as implemented by libjingle.

+
+ +
port - q
+
The UDP or TCP port of the relay server as an ASCII unsigned + integer
+ +
username - s
+
The username to use
+ +
password - s
+
The password to use
+ +
component - u
+
The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + +
+
+ + +

An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.

+ + +

The type of relay server that this represents depends on + the value of the NATTraversal + property. If NATTraversal is ice-udp, this is a TURN server; + if NATTraversal is gtalk-p2p, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.

+ +

If relaying is not possible for this stream, the list is empty.

+ +

This property cannot change once the stream has been created, so + there is no change notification.

+ + + + + + + String identifier for this candidate + + + + + Array of transports for this candidate with fields, + as defined in NewNativeCandidate + + + + Signal emitted when the connection manager wishes to inform the + client of a new remote candidate. + + + + + Signal emitted when the connection manager wishes the stream to be + closed. + + + + + + Inform the connection manager of codec used to receive data. + + + + + + ID of error, from the MediaStreamError enumeration + + + + + String describing the error + + + + Inform the connection manager that an error occured in this stream. The + connection manager should emit the StreamError signal for the stream on + the relevant channel, and remove the stream from the session. + + + + + + An unknown error occured. + + + + + The end of the stream was reached. + + + This error has no use anywhere. In Farsight 1 times, it was used to + indicate a GStreamer EOS (when the end of a file is reached). But + since this is for live calls, it makes no sense. + + + + + + There are no common codecs between the local side + and the other particpants in the call. The possible codecs are not + signalled here: the streaming implementation is assumed to report + them in an implementation-dependent way, e.g. Farsight should use + GstMissingElement. + + + + + + A network connection for the Media could not be established or was + lost. + + + + + + There was an error in the networking stack + (other than the connection failure). + + + + + + There are no installed codecs for this media type. + + + + + + The CM is doing something wrong. + + + + + + There was an error in the media processing stack. + + + + + + Informs the connection manager that all possible native candisates + have been discovered for the moment. + + + + + + + Informs the connection manager that a valid candidate pair + has been discovered and streaming is in progress. + + + + + + + + +

Informs the connection manager that a valid transport pair + has been discovered and streaming is in progress. Component + id MUST be the same for both transports and the pair is + only valid for that component.

+ + +

The connection manager might need to send the details of + the active transport pair (e.g. c and o parameters of SDP + body need to contain address of selected native RTP transport + as stipulated by RFC 5245). However, the candidate ID might + not be enough to determine these info if the transport was + found after NativeCandidatesPrepared + has been called (e.g. peer reflexive ICE candidate).

+ + +

This method must be called before + NewActiveCandidatePair.

+ + +

This way, connection managers supporting this method can + safely ignore subsequent + NewActiveCandidatePair call.

+ + +

Connection managers SHOULD NOT implement this method unless + they need to inform the peer about selected transports. As a + result, streaming implementations MUST NOT treat errors raised + by this method as fatal.

+ + +

Usually, connection managers only need to do one answer/offer + round-trip. However, some protocols give the possibility to + to send an updated offer (e.g. ICE defines such mechanism to + avoid some race conditions and to properly set the state of + gateway devices).

+ + + + + + UDP (User Datagram Protocol) + + + TCP (Transmission Control Protocol) + + + + + + String identifier for this candidate + + + + + Array of transports for this candidate, with fields: +
    +
  • component number
    • +
  • IP address (as a string)
    • +
  • port
    • +
  • base network protocol (one of the values of MediaStreamBaseProto)
    • +
  • proto subtype (e.g. RTP)
    • +
  • proto profile (e.g. AVP)
    • +
  • our preference value of this transport (double in range 0.0-1.0 + inclusive); 1 signals the most preferred transport
    • +
  • transport type, one of the values of MediaStreamTransportType
    • +
  • username if authentication is required
    • +
  • password if authentication is required
    • +
+ + + + Inform this MediaStreamHandler that a new native transport candidate + has been ascertained. + + + + + + A local address + + + + + An external address derived by a method such as STUN + + + + + An external stream relay + + + + + + + Locally-supported codecs. + + + + Inform the connection manager that a client is ready to handle + this StreamHandler. Also provide it with info about all supported + codecs. + + + + + + Locally-supported codecs + + + +

Used to provide codecs after Ready(), so the media client can go + ready for an incoming call and exchange candidates/codecs before + knowing what local codecs are available.

+ +

This is useful for gatewaying calls between two connection managers. + Given an incoming call, you need to call + Ready to get the remote codecs before + you can use them as the "local" codecs to place the outgoing call, + and hence receive the outgoing call's remote codecs to use as the + incoming call's "local" codecs.

+ +

In this situation, you would pass an empty list of codecs to the + incoming call's Ready method, then later call SetLocalCodecs on the + incoming call in order to respond to the offer.

+ + + + + + String identifier for remote candidate to drop + + + + There is no case where you want to release candidates (except + for an ICE reset, and there you'd want to replace then all, + using SetRemoteCandidateList). + + + Signal emitted when the connection manager wishes to inform the + client that the remote end has removed a previously usable + candidate. + + + It seemed like a good idea at the time, but wasn't. + + + + + + + + Emitted by the connection manager to inform the client that a + valid candidate pair has been discovered by the remote end + and streaming is in progress. + + + + + + A list of candidate id and a list of transports + as defined in NewNativeCandidate + + + + Signal emitted when the connection manager wishes to inform the + client of all the available remote candidates at once. + + + + + + Codecs supported by the remote peer. + + + + Signal emitted when the connection manager wishes to inform the + client of the codecs supported by the remote end. + If these codecs are compatible with the remote codecs, then the client + must call SupportedCodecs, + otherwise call Error. + + + + + + If emitted with argument TRUE, this means that the connection manager + wishes to set the stream playing; this means that the streaming + implementation should expect to receive data. If emitted with argument + FALSE this signal is basically meaningless and should be ignored. + + + We're very sorry. + + + + + + + Signal emitted when the connection manager wishes to set whether or not + the stream sends to the remote end. + + + + + + A telephony event code. + + + + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. + + + + + + + A telephony event code as defined by RFC 4733. + + + + + The payload type to use when sending events. The value 0xFFFFFFFF + means to send with the already configured event type instead of using + the specified one. + + + + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as a RFC 4733 named event, not as sound. You can also force a specific + Codec ID. + + + + + + + A telephony event code as defined by RFC 4733. + + + + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as sound instead of as a named event. + + + + + Request that any ongoing telephony events (as defined by RFC 4733) + being transmitted over this stream are stopped. + + + + + + Informs the connection manager of the stream's current state, as + as specified in Channel.Type.StreamedMedia::ListStreams. + + + + + + + Locally supported codecs. + + + + Inform the connection manager of the supported codecs for this session. + This is called after the connection manager has emitted SetRemoteCodecs + to notify what codecs are supported by the peer, and will thus be an + intersection of all locally supported codecs (passed to Ready) + and those supported by the peer. + + + + + + + Locally supported codecs, which SHOULD be the same as were previously + in effect, but possibly with different parameters. + + + + Inform the connection manager that the parameters of the supported + codecs for this session have changed. The connection manager should + send the new parameters to the remote contact. + + + This is required for H.264 and Theora, for example. + + + + + + +

Emitted when the connection manager wishes to place the stream on + hold (so the streaming client should free hardware or software + resources) or take the stream off hold (so the streaming client + should reacquire the necessary resources).

+ +

When placing a channel's streams on hold, the connection manager + SHOULD notify the remote contact that this will be done (if + appropriate in the protocol) before it emits this signal.

+ + +

It is assumed that relinquishing a resource will not fail. + If it does, the call is probably doomed anyway.

+ + +

When unholding a channel's streams, the connection manager + SHOULD emit this signal and wait for success to be indicated + via HoldState before it notifies the remote contact that the + channel has been taken off hold.

+ + +

This means that if a resource is unavailable, the remote + contact will never even be told that we tried to acquire it.

+ + + + + + + If true, the stream is to be placed on hold. + + + + + + + Notify the connection manager that the stream's hold state has + been changed successfully in response to SetStreamHeld. + + + + + If true, the stream is now on hold. + + + + + + + Notify the connection manager that an attempt to reacquire the + necessary hardware or software resources to unhold the stream, + in response to SetStreamHeld, has failed. + + + + + + Handles signalling the information pertaining to a specific media stream. + A client should provide information to this handler as and when it is + available. + + + + diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml new file mode 100644 index 0000000..bc9c8b2 --- /dev/null +++ b/spec/Properties_Interface.xml @@ -0,0 +1,194 @@ + + + Copyright (C) 2005-2007 Collabora Limited + Copyright (C) 2005, 2006 Nokia Corporation + Copyright (C) 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.

+ + + + + A struct (property ID, property name, D-Bus signature, + flags) representing a property, as returned by ListProperties on the + Properties interface. + + + + + + + + A struct (property ID, flags) representing a change to + a property's flags, as seen in the PropertyFlagsChanged signal on + the Properties interface. + + + + + + + An unsigned integer used to represent a Telepathy property. + + + + + A struct (property ID, value) representing a + property's value, as seen in the PropertiesChanged signal on + the Properties interface, returned by the GetProperties method + and passed to the SetProperties method. + + + + + + + Returns an array of (identifier, value) pairs containing the current + values of the given properties. + + + An array of property identifiers + + + + +

An array of structs containing:

+
    +
  • integer identifiers
    • +
  • variant boxed values
    • +
+ + + + + + + Some property identifier requested is invalid + + + + + Some property requested does not have the PROPERTY_FLAG_READ flag + + + + + + + Returns a dictionary of the properties available on this channel. + + + + + An array of structs containing: +
    +
  • an integer identifier
    • +
  • a string property name
    • +
  • a string representing the D-Bus signature of this property
    • +
  • a bitwise OR of the flags applicable to this property
    • +
+ + + + + + Emitted when the value of readable properties has changed. + + + + +

An array of structs containing:

+
    +
  • integer identifiers
    • +
  • variant boxed values
    • +
+

The array should contain only properties whose values have + actually changed.

+ + + + + + Emitted when the flags of some room properties have changed. + + + + +

An array of structs containing:

+
    +
  • integer identifiers
    • +
  • a bitwise OR of the current flags
    • +
+

The array should contain only properties whose flags have actually + changed.

+ + + + + +

Takes an array of (identifier, value) pairs containing desired + values to set the given properties. In the case of any errors, no + properties will be changed. When the changes have been acknowledged + by the server, the PropertiesChanged signal will be emitted.

+ +

All properties given must have the PROPERTY_FLAG_WRITE flag, or + PermissionDenied will be returned. If any variants are of the wrong + type, NotAvailable will be returned. If any given property identifiers + are invalid, InvalidArgument will be returned.

+ + + + + + An array mapping integer property identifiers to boxed values + + + + + + + + + + + +

Interface for channels and other objects, to allow querying and setting + properties. ListProperties returns which properties are valid for + the given channel, including their type, and an integer handle used to + refer to them in GetProperties, SetProperties, and the PropertiesChanged + signal. The values are represented by D-Bus variant types, and are + accompanied by flags indicating whether or not the property is readable or + writable.

+ +

Each property also has a flags value to indicate what methods are + available. This is a bitwise OR of PropertyFlags values.

+ + + + The property can be read + + + The property can be written + + + + + diff --git a/spec/Protocol.xml b/spec/Protocol.xml new file mode 100644 index 0000000..5e2c9b1 --- /dev/null +++ b/spec/Protocol.xml @@ -0,0 +1,485 @@ + + + + Copyright © 2009-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 stable API) + + +

An object representing a protocol for which this ConnectionManager + can create Connections.

+ +

Each Protocol object has the same well-known bus name as its parent + ConnectionManager. Its object path is formed by taking the + ConnectionManager's object path and appending '/', followed by the + Protocol name with any hyphen/minus '-' converted + to underscores '_'.

+ + +

This is the same as the representation of protocol names + in Account object paths, and in Connection object paths and bus + names. For instance, telepathy-gabble and telepathy-salut would + implement objects at + /org/freedesktop/Telepathy/ConnectionManager/gabble/jabber + and + /org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp, + respectively.

+ + +

If the ConnectionManager has a .manager file, each + Protocol's immutable properties must be represented in that file; + the representation is described as part of the documentation for + each property. For instance, a very simple ConnectionManager with one + Protocol might be represented like this:

+ +
+[ConnectionManager]
+Interfaces=
+
+[Protocol example]
+Interfaces=
+ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests;
+param-account=s required
+param-password=s required secret
+RequestableChannelClasses=text;
+VCardField=x-example
+EnglishName=Example
+Icon=im-example
+AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication;
+
+[text]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+
+ + + + +

A list of interfaces supported by this Protocol object.

+ +

This property should not be confused with + ConnectionInterfaces, + which refers to the interfaces of connections to this + protocol.

+ +

Connection managers with a .manager file + (as described as part of the + ConnectionManager interface) MUST cache this + property in the protocol's section of the .manager + file, using the key Interfaces. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.

+ + + + + +

The parameters which must or may be provided to the + RequestConnection method when connecting to the + given protocol.

+ +

Connection managers with a .manager file + (as described as part of the + ConnectionManager interface) MUST cache this + property in the protocol's section of the .manager + file via keys of the form param-p and + default-p, as documented in the + ConnectionManager interface.

+ + + + + +

A list of interface names which might be in the + Interfaces property of a + Connection to this protocol. Whether a Connection + will have all, some or none of these interfaces depends on server + capabilities.

+ +

This property should not be confused with + Interfaces.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file, using the key + ConnectionInterfaces. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.

+ + + + + +

A list of channel classes which might be requestable from a + Connection to this protocol (i.e. they will, + or might, appear in the Connection's RequestableChannelClasses property).

+ +

Whether a Connection will have all, some or none of these + requestable channel classes depends on server capabilities; + similarly, individual contacts are not guaranteed to support + all of these channel classes.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file, using the key + RequestableChannelClasses. The corresponding value + is a list of opaque strings, each followed by a semicolon; each + of those strings is the name of a group in the .manager + file which represents a channel class.

+ +

The names of the groups representing channel classes are not + significant, and MUST NOT be interpreted. When writing + .manager files, authors MAY choose mnemonic group names, + generate group names mechanically (e.g. with an incrementing + integer), or use some combination of these.

+ +

Each group representing a channel class has a key + allowed which is a list of D-Bus property names + representing allowed parameters. Any other keys that do not contain + a space MUST be ignored. Any key containing a space represents + a fixed property; the key has the form + "propertyname type", and the value + is encoded in the same way as for the default-p + keys described in the ConnectionManager documentation.

+ +

Connection managers that have channel classes whose fixed + properties are not representable in this form SHOULD NOT have + .manager files.

+ +

For instance, this .manager file could represent + a connection manager that supports 1-1 Text messages and + StreamedMedia audio calls:

+ +
[Protocol jabber]
+param-account=s required
+param-password=s required
+RequestableChannelClasses=rcc0;rcc1;
+
+[rcc0]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+
+[rcc1]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio;
+
+ + + + + +

The name of the most common vCard field used for this protocol's + contact identifiers, normalized to lower case, or the empty string + if there is no such field.

+ +

For example, this would be x-jabber for + 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 + contact's vCard containing an X-JABBER field, how can you + communicate with the contact? By iterating through protocols + looking for an x-jabber VCardField, one can build up a list of + 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.

+ + +

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 + VCardField. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

+ + + + + +

The name of the protocol in a form suitable for display to users, + such as "AIM" or "Yahoo!", or the empty string if none is + available.

+ +

This is effectively in the C locale (international English); + user interfaces requiring a localized protocol name SHOULD look + one up in their own message catalog based on either the Telepathy + Protocol name or this property, but SHOULD use + this English version as a fallback if no translated version can be + found.

+ + +

Many protocols are named after a company or product which isn't + translated in non-English locales. This also provides a fallback + display name, for UIs with no prior knowledge of a particular + protocol.

+ + +

If this property's value is empty, clients MAY fall back to using + the Telepathy Protocol name, possibly with its + capitalization adjusted.

+ +

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 + EnglishName. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

+ + + + + +

The name of an icon in the system's icon theme, such as "im-msn", or + the empty string.

+ + +

This can be used as a default if the Icon + property is not set on an Account, or used by the AccountManager + to choose a default icon if none is set during account + creation.

+ + +

If this property's value is empty, clients MAY fall back to + generating a name based on the Protocol name.

+ +

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 + Icon. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

+ + + + + +

Return a string which uniquely identifies the account to which the + given parameters would connect.

+ + +

For many protocols, this would return the well-known 'account' + parameter. However, for IRC the returned string would be composed + from the 'account' (i.e. nickname) and 'server' parameters. + AccountManager implementations can use this to form the + account-specific part of an Account's object path.

+ + + + + + A set of parameters as would be provided to RequestConnection + + + + + +

An opaque string suitable for use as the account-specific part of + an Account's object path. This is not necessarily + globally unique, but should represent a "best-effort" + identification of the account.

+ + +

For a pathological case, consider a user signing in as + 'me@example.com' with 'server' set to either jabber1.example.com + or jabber2.example.com. Both of these should result in + me@example.com being returned from this method, even if the user + can actually be signed in to those two servers + simultaneously.

+ + + + + + + + The IdentifyAccount method is not supported by this connection + manager. The caller SHOULD fall back to deriving identification + from the parameters. + + + + + + + +

Attempt to normalize the given contact ID. Where possible, this + SHOULD return the same thing that would be returned by + InspectHandles(RequestHandles(CONTACT, [Contact_ID])) 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.

+ + +

One common example of a best-effort offline normalization + differing from the ideal normalization is XMPP.

+ +

On XMPP, contacts' JIDs should normally have the resource removed + during normalization, but for contacts in a MUC (chatroom), the + resource is an integral part of the JID - so the contact JID + alice@example.com/Empathy should normalize to alice@example.com, + but the in-MUC JID wonderland@conference.example.com/Alice should + normalize to itself.

+ +

While online, the connection manager has enough context to know + which chatrooms the user is in, and can infer from that whether + to remove resources, but the best-effort normalization performed + while offline does not have this context, so the best that can be + done is to remove the resource from all JIDs.

+ + +

This method MAY simply raise NotImplemented on some protocols.

+ + +

In link-local XMPP, you can't talk to someone who isn't present + on your local network, so normalizing identifiers in advance is + meaningless.

+ + + + + + The identifier of a contact in this protocol + + + + + + The identifier of a contact in this protocol, normalized as much + as possible + + + + + + + The NormalizeContact method is not supported by this connection + manager. The caller MAY recover by using the contact ID as-is. + + + + + + + + +

A list of D-Bus interfaces which provide information as to + what kind of authentication channels can possibly appear + before the connection reaches the CONNECTED state.

+ +

These can either be channel types, or where the channel + type isn't enough information to be useful, interfaces + indicating a specific use of a channel type. For example, + ServerTLSConnection + channels are obviously about TLS certificates so the channel + type would appear in this list. However, a + ServerAuthentication + channel type alone does not explain enough about the authentication type + in use as it is merely a base for the channel interfaces that appear in + said channels. In this case, CMs should use the value of the + ServerAuthentication.AuthenticationMethod + property in this list.

+ +

For example, if a protocol's + AuthenticationTypes contains + two values:

+ +
+ 
+[ ...Channel.Type.ServerTLSConnection,
+  ...Channel.Interface.SASLAuthentication ]
+ +

This tells a client that before the connection status + reached CONNECTED, a ServerTLSConnection + could appear carrying a TLS certificate. It also tells the + client that before the connection status reaches CONNECTED, a + ServerAuthentication + channel could also appear, where ServerAuthentication.AuthenticationMethod=SASLAuthentication. A + hypothetical future Channel.Interface.Captcha interface would + also appear in this list if the CM might require the user + solve a captcha before connecting.

+ + + + + + + diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml new file mode 100644 index 0000000..3722c3b --- /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/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml new file mode 100644 index 0000000..cd91351 --- /dev/null +++ b/spec/Protocol_Interface_Avatars.xml @@ -0,0 +1,157 @@ + + + + Copyright © 2009-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 stable API) + + + +

An interface for protocols where it might be possible to set the + user's avatar, and the expected size limits and supported MIME types + are known before connecting.

+ + +

If the avatar requirements cannot be discovered while offline, + it's impossible to avoid setting the Account's Avatar property to an unsupported avatar.

+ + +

Each property on this interface SHOULD be cached in the + .manager file, using a key of the same name as the + property in the [Protocol proto] + group. All properties are encoded in ASCII decimal in the obvious + way, except for + SupportedAvatarMIMETypes which is + encoded as a sequence of strings each followed by a semicolon + (as for the "localestrings" type in the Desktop Entry + Specification).

+ +

For instance, an XMPP connection manager might have this + .manager file:

+ +
[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars;
+param-account=s required
+param-password=s required
+SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif;
+MinimumAvatarHeight=32
+RecommendedAvatarHeight=64
+MaximumAvatarHeight=96
+MinimumAvatarWidth=32
+RecommendedAvatarWidth=64
+MaximumAvatarWidth=96
+MaximumAvatarBytes=8192
+
+ + + + + The expected value of the Connection.Interface.Avatars.SupportedAvatarMIMETypes + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.MinimumAvatarHeight + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.MinimumAvatarWidth + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.RecommendedAvatarHeight + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.RecommendedAvatarWidth + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.MaximumAvatarHeight + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.MaximumAvatarWidth + property on connections to this protocol. + + + + + + The expected value of the Connection.Interface.Avatars.MaximumAvatarBytes + property on connections to this protocol. + + + + diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml new file mode 100644 index 0000000..ddff332 --- /dev/null +++ b/spec/Protocol_Interface_Presence.xml @@ -0,0 +1,113 @@ + + + + Copyright © 2009-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 stable API) + + + +

An interface for protocols where it might be possible to set the + user's presence, and the supported presence types can be predicted + before connecting.

+ + +

This allows UIs to show or hide presence types that aren't + always supported, such as "invisible", while not online.

+ + +

The properties on this interface SHOULD be cached in the + .manager file, in the + [Protocol proto] + group. For each status s in + Statuses, that group should + contain a key of the form status-s whose value + is the Connection_Presence_Type as an ASCII + decimal integer, followed by a space-separated sequence of tokens + from the following set:

+ +
+
settable
+
If present, the user can set this status on themselves using + SetPresence; this corresponds to May_Set_On_Self + in the Simple_Status_Spec struct.
+ +
message
+
If present, the user can set a non-empty message for this status; + this corresponds to Can_Have_Message in the + Simple_Status_Spec struct.
+
+ +

Unrecognised tokens MUST be ignored.

+ +

For instance, an XMPP connection manager might have this + .manager file:

+ +
[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence;
+param-account=s required
+param-password=s required
+status-offline=1
+status-unknown=7
+status-error=8
+status-hidden=5 settable message
+status-xa=4 settable message
+status-away=3 settable message
+status-dnd=6 settable message
+status-available=2 settable message
+status-chat=2 settable message
+
+ +

which corresponds to these property values (using a Python-like + syntax):

+ +
Statuses = {
+    'offline': (OFFLINE, False, False),
+    'unknown': (UNKNOWN, False, False),
+    'error': (ERROR, False, False),
+    'hidden': (HIDDEN, True, True),
+    'xa': (EXTENDED_AWAY, True, True),
+    'away': (AWAY, True, True),
+    'dnd': (BUSY, True, True),
+    'available': (AVAILABLE, True, True),
+    'chat': (AVAILABLE, True, True),
+}
+
+ + + + +

The statuses that might appear in the Connection.Interface.SimplePresence.Statuses + property on a connection to this protocol that supports + SimplePresence. This property is immutable.

+ +

Depending on server capabilities, it is possible that not all + of these will actually appear on the Connection.

+ + + + + diff --git a/spec/all.xml b/spec/all.xml new file mode 100644 index 0000000..3123401 --- /dev/null +++ b/spec/all.xml @@ -0,0 +1,303 @@ + + +Telepathy D-Bus Interface Specification +0.21.8 + +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 +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.

+ + + + +

+ A Connection Manager is a factory for connections. +

+ + + + + + + + + +

+ Connections represent active protocol sessions. There are a number of core + interfaces which all connections should implement, and a number of optional + interfaces which provide various functionality related to contacts and to + the connection itself. +

+ + + + + + + + +

+ On protocols that support contact lists, these interface expose the user's + contact lists, along with presence subscription information and contact + list groups (if supported). +

+ + + + + + + + +

+ These optional Connection interfaces expose metadata about contacts on + this connection—from their current presence through to the type of client + they're connected with—and allow the local user to publish such metadata + back to their contacts. +

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

+ These optional Connection interfaces expose protocol-specific features, + and allow configuring the running connection. +

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

+ A Channel is used by Telepathy to exchange data between local + applications and remote servers. A given connection will have many + channels, each one represented by a D-Bus object. +

+

+ Each Channel has a type, represented by a D-Bus interface, and may + implement one or more additional interfaces from the list of channel + interfaces below. +

+ + + + + + +

+ Each Channel implements one of the following types: +

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

+ A Channel may also implement one or more of the following interfaces, + depending on its type. Some interfaces are only applicable to particular + channel types, while others may (in principle) appear on any type of + channel. +

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

These interfaces may only appear on channels of type Text.

+ + + + + + + + + + +

These interfaces are only applicable to channels of type StreamedMedia, with the + exception of the Hold interface, which + may also appear on Call.DRAFT channels.

+ + + + + + + + + + +

These interfaces provide functionality for ad-hoc conference calls and + chat rooms. They are primarily intended for Text, StreamedMedia and + Call.DRAFT + channels, but may also appear on other types of channel.

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

+ A set of objects to be used for authentication purposes, such + as TLS certificates or handshakes for negotiating end-to-end + security. +

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

+ The Account Manager is a desktop service that provides account configuration + and can manage the connection managers. In general, clients will use the + account manager to find out about instant messaging accounts and their + associated connections. +

+ + + + + + + + + + +

+ The Channel Dispatcher is a desktop service whose purpose is to dispatch + incoming Telepathy Channels to the appropriate client (e.g. incoming text + chat, file transfer, tubes, etc.). +

+ + + + + + + + + +

+ Clients should implement one or more of these interfaces to be able to + handle channels coming in from the Channel Dispatcher. +

+ + + + + + + + + + + + + + + + + + + + diff --git a/spec/errors.xml b/spec/errors.xml new file mode 100644 index 0000000..eccbd09 --- /dev/null +++ b/spec/errors.xml @@ -0,0 +1,564 @@ + + + + +

The D-Bus errors used in Telepathy all start with + org.freedesktop.Telepathy.Error.. They are used in + D-Bus messages of type ERROR, and also as plain strings annotated with + the DBus_Error_Name type.

+ +

In principle, any method can raise any error (this is a general fact + of IPC). For instance, generic D-Bus errors starting with + org.freedesktop.DBus.Error. will occur in some + situations.

+ +

Telepathy methods can also raise implementation-specific errors to + indicate specialized failure conditions. For better interoperability, + if a suitable Telepathy error exists, it should be preferred.

+ +

The namespace org.freedesktop.Telepathy.Qt4.Error. + is reserved for use by the D-Bus client implementation in telepathy-qt4, + which uses it to represent certain error situations that did not involve + a D-Bus ERROR message. These errors are defined and documented as part of + telepathy-qt4's C++ API, and should not be used on D-Bus.

+ + + + + Raised when there is an error reading from or writing to the network. + + + + + + Raised when the requested method, channel, etc is not available on this connection. + + + + + + Raised when one of the provided arguments is invalid. + + + + + + Raised when the requested functionality is temporarily unavailable. + + + + + + The user is not permitted to perform the requested operation. + + + + + + The connection is not currently connected and cannot be used. + This error may also be raised when operations are performed on a + Connection for which + StatusChanged + has signalled status Disconnected for reason None. + + + The second usage corresponds to None in the + Connection_Status_Reason enum; if a better reason + is available, the corresponding error should be used instead. + + + + + + + The handle specified is unknown on this channel or connection. + + + + + + You are banned from the channel. + + + + + + The channel is full. + + + + + + The requested channel is invite-only. + + + + + +

The requested channel or other resource already exists, and another + user interface in this session is responsible for it.

+ +

User interfaces SHOULD handle this error unobtrusively, since it + indicates that some other user interface is already processing the + channel.

+ + + + + + Raised by an ongoing request if it is cancelled by user request before + it has completed, or when operations are performed on an object which + the user has asked to close (for instance, a Connection where the user + has called Disconnect, or a Channel where the user has called Close). + + + The second form can be used to correspond to the Requested member in + the Connection_Status_Reason enum, or to + to represent the situation where disconnecting a Connection, + closing a Channel, etc. has been requested by the user but this + request has not yet been acted on, for instance because the + service will only act on the request when it has finished processing + an event queue. + + + + + + + Raised when authentication with a service was unsuccessful. + + This corresponds to Authentication_Failed in the + Connection_Status_Reason enum. + + + + + + + Raised if a user request insisted that encryption should be used, + but encryption was not actually available. + + + This corresponds to part of Encryption_Error in the + Connection_Status_Reason enum. It's been separated + into a distinct error here because the two concepts that were part + of EncryptionError seem to be things that could reasonably appear + differently in the UI. + + + + + + + Raised if encryption appears to be available, but could not actually be + used (for instance if SSL/TLS negotiation fails). + + This corresponds to part of Encryption_Error in the + Connection_Status_Reason enum. + + + + + + + Raised if the server did not provide a SSL/TLS certificate. This error + MUST NOT be used to represent the absence of a client certificate + provided by the Telepathy connection manager. + + This corresponds to Cert_Not_Provided in the + Connection_Status_Reason enum. That error + explicitly applied only to server SSL certificates, so this one + is similarly limited; having the CM present a client certificate + is a possible future feature, but it should have its own error + handling. + + + + + + + Raised if the server provided a SSL/TLS certificate signed by an + untrusted certifying authority. This error SHOULD NOT be used to + represent a self-signed certificate: see the Self Signed error for that. + + This corresponds to Cert_Untrusted in the + Connection_Status_Reason enum and to Untrusted in the + TLS_Certificate_Reject_Reason enum, with a clarification + to avoid ambiguity. + + + + + + + Raised if the server provided an expired SSL/TLS certificate. + + This corresponds to Cert_Expired in the + Connection_Status_Reason enum and to Expired in + the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised if the server provided an SSL/TLS certificate that will become + valid at some point in the future. + + This corresponds to Cert_Not_Activated in the + Connection_Status_Reason enum and to + Not_Activated in the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised if the server provided an SSL/TLS certificate that did not have + the expected fingerprint. + + This corresponds to Cert_Fingerprint_Mismatch in the + Connection_Status_Reason enum and to + Fingerprint_Mismatch in the TLS_Certificate_Reject_Reason enum. + + + + + + +

Raised if the server provided an SSL/TLS certificate that did not match + its hostname.

+

You MAY be able to get more details about the expected and certified + hostnames by looking up the 'expected-hostname' and 'certificate-hostname' + keys in the details map that came together with this error.

+ + This corresponds to Cert_Hostname_Mismatch in the + Connection_Status_Reason enum and to Hostname_Mismatch + in the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised if the server provided an SSL/TLS certificate that is self-signed + and untrusted. + + This corresponds to Cert_Self_Signed in the + Connection_Status_Reason enum and to Self_Signed + in the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised if the server provided an SSL/TLS certificate that has been + revoked. + + This corresponds to Cert_Revoked in the + Connection_Status_Reason enum and to Revoked + in the TLS_Certificate_Reject_Reason enum. + + + + + + + + Raised if the server provided an SSL/TLS certificate that uses an + insecure cipher algorithm or is cryptographically weak. + + This corresponds to Cert_Insecure in the + Connection_Status_Reason enum and to Insecure + in the TLS_Certificate_Reject_Reason enum. + + + + + + + + Raised if the server provided an SSL/TLS certificate that is + unacceptable in some way that does not have a more specific error. + + This corresponds to Cert_Other_Error in the + Connection_Status_Reason enum and to Unknown + in the TLS_Certificate_Reject_Reason enum. + + + + + + + + Raised if the length in bytes of the server certificate, or the depth of the + server certificate chain exceeds the limits imposed by the crypto + library. + + This corresponds to Cert_Limit_Exceeded in the + Connection_Status_Reason enum and to Limit_Exceeded + in the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised when requested functionality is unavailable due to contact + not having required capabilities. + + + + + + Raised when requested functionality is unavailable because a contact is + offline. + + + This corresponds to Offline in the + Channel_Group_Change_Reason enum. + + + + + + + Used to represent a user being ejected from a channel by another user, + for instance being kicked from a chatroom. + + + This corresponds to Kicked in the + Channel_Group_Change_Reason enum. + + + + + + + Used to represent a user being removed from a channel because of a + "busy" indication. This error SHOULD NOT be used to represent a server + or other infrastructure being too busy to process a request - for that, + see ServerBusy. + + + This corresponds to Busy in the + Channel_Group_Change_Reason enum. + + + + + + + Used to represent a user being removed from a channel because they did + not respond, e.g. to a StreamedMedia call. + + + This corresponds to No_Answer in the + Channel_Group_Change_Reason enum. + + + + + + + Raised when the requested user does not, in fact, exist. + + + This corresponds to Invalid_Contact in the + Channel_Group_Change_Reason enum, but can also be + used to represent other things not existing (like chatrooms, perhaps). + + + + + + + Raised when a channel is terminated for an unspecified reason. In + particular, this error SHOULD be used whenever normal termination of + a 1-1 StreamedMedia call by the remote user is represented as a D-Bus + error name. + + + This corresponds to None in the + Channel_Group_Change_Reason enum. + + + + + + + Raised when a connection is refused. + + + + + + Raised when a connection can't be established. + + + + + + Raised when a connection is broken. + + + + + + Raised when the user attempts to connect to an account but they are + already connected (perhaps from another client or computer), and the + protocol or account settings do not allow this. + + + XMPP can have this behaviour if the user chooses the same resource + in both clients (it is server-dependent whether the result is + AlreadyConnected on the new connection, ConnectionReplaced on the + old connection, or two successful connections). + + + + + + + Raised by an existing connection to an account if it is replaced by + a new connection (perhaps from another client or computer). + + + In MSNP, when connecting twice with the same Passport, the new + connection "wins" and the old one is automatically disconnected. + XMPP can also have this behaviour if the user chooses the same + resource in two clients (it is server-dependent whether the result is + AlreadyConnected on the new connection, ConnectionReplaced on the + old connection, or two successful connections). + + + + + + + Raised during in-band registration if the server indicates that the + requested account already exists. + + + + + + Raised if a server or some other piece of infrastructure cannot process + the request, e.g. due to resource limitations. Clients MAY try again + later. + + + This is not the same error as Busy, which indicates that a + user is busy. + + + + + + + Raised if a request cannot be satisfied because a process local to the + user has insufficient resources. Clients MAY try again + later. + + + For instance, the ChannelDispatcher + might raise this error for some or all channel requests if it has + detected that there is not enough free memory. + + + + + + + + Raised if a request cannot be satisfied without violating an earlier + request for anonymity, and the earlier request specified that raising + an error is preferable to disclosing the user's identity (for instance + via Connection.Interface.Anonymity.AnonymityMandatory or + Channel.Interface.Anonymity.AnonymityMandatory). + + + + + + + Raised when the requested functionality is not yet available, but is + likely to become available after some time has passed. + + + + + + + Raised when an incoming or outgoing Call.DRAFT is + rejected by the the receiver. + + + + + + + Raised when a call was terminated as a result of the local user + picking up the call on a different resource. + + + + + + + Raised when a server or other piece of infrastructure indicates an + internal error, or when a message that makes no sense is received from + a server or other piece of infrastructure. + + + For instance, this is appropriate for XMPP's + internal-server-error, and is also appropriate if + you receive sufficiently inconsistent information from a server that + you cannot continue. + + + + + + + + Raised if a server rejects protocol messages from a connection manager + claiming that they do not make sense, two local processes fail to + understand each other, or an apparently impossible situation is + reached. + + + For instance, this would be an appropriate mapping for XMPP's + errors bad-format, invalid-xml, etc., which can't happen unless + the local (or remote) XMPP implementation is faulty. This is + also analogous to + Media_Stream_Error_Invalid_CM_Behavior, + TP_DBUS_ERROR_INCONSISTENT in telepathy-glib, and + TELEPATHY_QT4_ERROR_INCONSISTENT in telepathy-qt4. + + + + + Copyright © 2005-2010 Collabora Limited + Copyright © 2005-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.

+ + diff --git a/spec/generic-types.xml b/spec/generic-types.xml new file mode 100644 index 0000000..014f8ad --- /dev/null +++ b/spec/generic-types.xml @@ -0,0 +1,215 @@ + + + + An unsigned 32-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z) + + + + An signed 64-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z); negative for times before the epoch + + The Text interface is the only user of Unix_Timestamp so + far, and we'd like to be Y2038 compatible in future + interfaces. + + + + A string representing a D-Bus bus name - either a well-known + name like "org.freedesktop.Telepathy.MissionControl" or a unique name + like ":1.123" + + + + A string representing a D-Bus well-known + name like "org.freedesktop.Telepathy.MissionControl". + + + + A string representing a D-Bus unique name, such as + ":1.123" + + + + An ASCII string representing a D-Bus interface - two or more + elements separated by dots, where each element is a non-empty + string of ASCII letters, digits and underscores, not starting with + a digit. The maximum total length is 255 characters. For example, + "org.freedesktop.DBus.Peer". + + + + An ASCII string representing a D-Bus error. This is + syntactically the same as a DBus_Interface, but the + meaning is different. + + + + A string representing a D-Bus signature + (the 'g' type isn't used because of poor interoperability, particularly + with dbus-glib) + + + + An ASCII string representing a D-Bus method, signal + or property name - a non-empty string of ASCII letters, digits and + underscores, not starting with a digit, with a maximum length of 255 + characters. For example, "Ping". + + + + A string representing the full name of a D-Bus method, + signal or property, consisting of a DBus_Interface, followed by + a dot, followed by a DBus_Member. For example, + "org.freedesktop.DBus.Peer.Ping". + + + + A mapping from strings representing D-Bus + properties (by their namespaced names) to their values. + + + A D-Bus interface name, followed by a dot and a D-Bus property name. + + + + + The value of the property. + + + + + + A mapping from strings to variants representing extra + key-value pairs. + + + + + + A mapping from strings to strings representing extra + key-value pairs. + + + + + + An IP address and port. + + Either a dotted-quad IPv4 address literal as for + Socket_Address_IPv4, or an RFC2373 IPv6 address + as for Socket_Address_IPv6. + + + + The TCP or UDP port number. + + + + + An IPv4 address and port. + + A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1". + + + The TCP or UDP port number. + + + + + An IPv6 address and port. + + An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171". + + + The TCP or UDP port number. + + + + + An IPv4 network or subnet. + + A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1". + + + The number of leading bits of the address that must + match, for this netmask to be considered to match an + address. + + + + + An IPv6 network or subnet. + + An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171". + + + The number of leading bits of the address that must + match, for this netmask to be considered to match an + address. + + + + + +

The time at which an user action occurred. This type has the 2 + following special values:

+ +

0: the action doesn't involve any user action. Clients + SHOULD avoid stealing focus when presenting the channel.

+ +

MAX_INT64: clients SHOULD behave as though the user action happened + at the current time, e.g. a client MAY request that its window gains + focus. +

+ + +

This can be used by clients that can't know the X server time like + command line applications for example.

+ + +

For all the other values it corresponds to the time of the user + action. Clients SHOULD use this for focus-stealing prevention, + if applicable. + Note that the time is dependant on the local + environment and so is not necessarily a wall-clock time. + For example in an X environment it's expected to be the X timestamp + of events. + This corresponds to the _NET_WM_USER_TIME property in + EWMH.

+ + + + + + A mapping from object path to the immutable properties of + the object. + + + The object path of an object + + + + + The immutable properties of the object + + + + + diff --git a/spec/template.xml b/spec/template.xml new file mode 100644 index 0000000..7264720 --- /dev/null +++ b/spec/template.xml @@ -0,0 +1,33 @@ + + + + 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 1) + + +

Foo.

+ + + + + -- cgit v1.2.3