Gabble-specific extensions to the Telepathy interfaces

Interfaces

• org.freedesktop.Telepathy.ChannelBundle.DRAFT
• org.freedesktop.Telepathy.Channel.FUTURE
• org.laptop.Telepathy.BuddyInfo
• org.laptop.Telepathy.ActivityProperties
• org.freedesktop.Telepathy.Channel.Type.FileTransfer.FUTURE
• org.freedesktop.Telepathy.Connection.Interface.Gabble.Decloak
• org.freedesktop.Telepathy.Connection.Interface.MailNotification.DRAFT
• org.freedesktop.Telepathy.Connection.FUTURE
• org.freedesktop.Telepathy.Gabble.Plugin.Gateways
• org.freedesktop.Telepathy.Gabble.Plugin.Test
• org.freedesktop.Telepathy.Call.Content.DRAFT
• org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT
• org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT
• org.freedesktop.Telepathy.Call.Stream.DRAFT
• org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT
• org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT
• org.freedesktop.Telepathy.Channel.Type.Call.DRAFT
• org.freedesktop.Telepathy.Channel.Type.ServerAuthentication.DRAFT
• org.freedesktop.Telepathy.Channel.Interface.SaslAuthentication.DRAFT

org.freedesktop.Telepathy.ChannelBundle.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

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.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Interfaces − as (DBus_Interface[]), read-only

A list of the extra interfaces provided by this channel bundle.

org.freedesktop.Telepathy.Channel.FUTURE

This interface is a staging area for future Channel functionality and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

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.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Bundle − o, read-only

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

Added in version 0.17.9. (in Channel.FUTURE pseudo-interface)

org.laptop.Telepathy.BuddyInfo

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

An interface on connections to associate OLPC buddy information with contacts, providing methods for the user to set their own information and retrieve information of contacts. The user is automatically notified when information of contacts that are in his 'subscribe' contact list change.

The following types and names are used to request and set information (except for activities):

s:color

The color name of the buddy. Format used is #RRGGBB,#RRGGBB (stroke,fill).

ay:key

The public key of the buddy.

s:jid

For link-local connections, the JID of the buddy's server account.

Activities are represented by a struct containing:

• the identifier of the activity
• the handle of the activity channel

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Structure types

org.laptop.Telepathy.ActivityProperties

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

An interface on connections to associate OLPC activity properties with rooms.

The following types and names are used to request and set properties:

s:color

The color of the activity. Format used is #RRGGBB,#RRGGBB (stroke,fill).

s:name

The name of the activity.

s:type

The type of the activity.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Channel.Type.FileTransfer.FUTURE

This interface is a staging area for future File Transfer Channel functionality and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

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

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

FileCollection − s, read-only

The FileCollection to which this channel belongs.

A channel's FileCollection property can never change.

At least on GTalk and apparently also on iChat the user can send a set of files to a contact and that contact can then pick and choose which files to actually receive. The CM should emit all new FT channels belonging to one collection at the same time, UIs supporting this feature can then bundle all these channels together in some way and show a nice UI. UIs not supporting it will treat them as seperate transfers, which is not great but a reasonable fallback

Added in version 0.19.2. (in Channel.Type.FileTransfer.FUTURE pseudo-interface)

org.freedesktop.Telepathy.Connection.Interface.Gabble.Decloak

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

Added in version Gabble 0.9.4. (Gabble-specific)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

DecloakAutomatically − b, read/write

If true, the connection manager will automatically disclose the local user's capabilities (and hence the fact that they are online, but no further presence information) on request from any remote XMPP user.

This is necessary to allow incoming calls from arbitrary users.

This property SHOULD also be available as a connection manager parameter, with the DBus_Property flag. The default SHOULD be false since this constitutes a deliberate presence leak.

org.freedesktop.Telepathy.Connection.Interface.MailNotification.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

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 using the Subscribe 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 Unsubscribe to release resources in the CM.

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.

Added in version 0.19.1. (as draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

MailNotificationFlags − u (Mail_Notification_Flags), read-only

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.

UnreadMailCount − u, read-only

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.

UnreadMails − aa{sv} (Mail[]), read-only

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.

MailAddress − s, read-only

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.

Enumerated types:

HTTP_Method

HTTP_Method_Get = 0

Use the GET method when opening the URL.

HTTP_Method_Post = 1

Use the POST method when opening the URL. Refer to HTTP_Post_Data for more details.

Sets of flags:

Mail_Notification_Flags

Mail_Notification_Flag_Supports_Unread_Mail_Count = 1

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.

Mail_Notification_Flag_Supports_Unread_Mails = 2

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.

Mail_Notification_Flag_Emits_Mails_Received = 4

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.

Mail_Notification_Flag_Supports_Request_Inbox_URL = 8

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.

Mail_Notification_Flag_Supports_Request_Mail_URL = 16

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.

Mail_Notification_Flag_Thread_Based = 32

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.

Structure types

        <input type="hidden" name="less-than">&lt;</input>
        <input type="hidden" name="percent">%</input>
        

Mapping types

org.freedesktop.Telepathy.Connection.FUTURE

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

Methods:

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Gabble.Plugin.Gateways

A sidecar interface to register with XEP-0100 gateways.

Methods:

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Gabble.Plugin.Test

A sidecar interface implemented by a plugin used by the test suite.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Call.Content.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Added in version 0.19.0. (draft 1)

Interface has no methods.

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Name − s, read-only

The name of the content. [FIXME: rationale?]

Type − u (Media_Stream_Type), read-only

The media type of this content

Creator − u (Contact_Handle), read-only

The creator of this content

Disposition − u (Call_Content_Disposition), read-only

The disposition of this content. This property cannot change.

Streams − ao, read-only

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 via StreamAdded and StreamRemoved.

Enumerated types:

Call_Content_Disposition

Call_Content_Disposition_None = 0

The content has no specific disposition

Call_Content_Disposition_Early_Media = 1

[FIXME: what does this mean?]

Call_Content_Disposition_Initial = 2

The content was initially part of the call. When Accept is called on the channel, all streams of this content where the self-handle's sending state in Senders is Sending_State_Pending_Send will be moved to Sending_State_Sending as if SetSending(TRUE) had been called.

org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Added in version 0.19.0. (draft 1)

Methods:

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

RemoteContactCodecMap − a{ua(usuua{ss})} (Contact_Codec_Map), read-only

A map from remote contacts to the lists of codecs they support.

org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Call.Content

Added in version 0.19.0. (draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

ContactCodecMap − a{ua(usuua{ss})} (Contact_Codec_Map), read-only

A map from contact handles (including the local user's own handle) to the codecs supported by that contact. Change notification is via CodecsChanged.

CodecOffer − (oa{ua(usuua{ss})}) (Codec_Offering), read-only

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

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

Change notification is via 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).

Structure types

Mapping types

org.freedesktop.Telepathy.Call.Stream.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Added in version 0.19.0. (draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Senders − a{uu} (Contact_Sending_State_Map), read-only

A map from contacts to their sending state.

The local user's handle in this map (the Group.SelfHandle if the channel implements Group, or the Connection.SelfHandle otherwise) indicates whether the local user is sending media. Media sent on this stream should be assumed to be received, directly or indirectly, by every other contact in the Senders mapping. 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.

Enumerated types:

Sending_State

Sending_State_None = 0

The contact is not sending media and has not been asked to do so.

Sending_State_Pending_Send = 1

The contact has been asked to start sending media.

Sending_State_Sending = 2

The contact is sending media.

Mapping types

org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Added in version 0.19.0. (draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

RemoteCredentials − (ss) (Stream_Credentials), read-only

RemoteCandidates − a(usqa{sv}) (Candidate[]), read-only

SelectedCandidate − (usqa{sv}) (Candidate), read-only

StreamState − u (Media_Stream_State), read-only

Transport − u (Stream_Transport_Type), read-only

org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Call.Stream

Added in version 0.19.0. (draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Transport − u (Stream_Transport_Type), read-only

The transport for this stream. This property is immutable.

LocalCandidates − a(usqa{sv}) (Candidate[]), read-only

[FIXME]. Change notification is via LocalCandidatesAdded.

LocalCredentials − (ss) (Stream_Credentials), read-only

[FIXME]. Change notification is via LocalCredentialsSet.

STUNServers − a(sq) (Socket_Address_IP[]), read-only

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.

RelayInfo − aa{sv} (String_Variant_Map[]), read-only

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.

RetrievedServerInfo − b, read-only

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

Endpoints − ao, read-only

Enumerated types:

Stream_Transport_Type

Stream_Transport_Type_Raw_UDP = 0

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

Stream_Transport_Type_ICE = 1

Interactive Connectivity Establishment, as defined by the IETF MMUSIC working group. [FIXME: do we want this to cover both ICE-UDP and ICE-TCP, or split them?] [This corresponds to "ice-udp" in the old Media.StreamHandler interface.]

Stream_Transport_Type_GTalk_P2P = 2

Google Talk peer-to-peer connectivity establishment, as implemented by libjingle 0.3. [This corresponds to "gtalk-p2p" in the old Media.StreamHandler interface.]

Stream_Transport_Type_WLM_8_5 = 3

The transport used by Windows Live Messenger 8.5 or later, which resembles ICE draft 6. [This corresponds to "wlm-8.5" in the old Media.StreamHandler interface.]

Stream_Transport_Type_WLM_2009 = 4

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

Structure types

Mapping types

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

A channel type for making audio and video calls.

A Call channel can have one or more Content.DRAFT objects, which represent the actual Media that forms the Call (e.g. an audio content and a video content).

Added in version 0.19.0. (draft 1)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

Contents − ao, read-only

The list of Content.DRAFT objects that are part of this call. Change notification is via the ContentAdded and ContentRemoved signals.

CallStateDetails − a{sv}, read-only

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

CallState − u (Call_State), read-only

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.

Clients MAY consider unknown values in this property to be an error.

CallFlags − u (Call_Flags), read-only

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.

CallStateReason − (uus) (Call_State_Reason), read-only

The reason for the last change to the CallState and/or CallFlags. The CallStateDetails MAY provide additional information.

HardwareStreaming − b, read-only

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.

CallMembers − a{uu} (Call_Member_Map), read-only

A mapping from the remote contacts that are part of this call to flags discribing their status. This mapping never has the local user's handle as a key.

InitialTransport − s, read-only

If set on a requested channel this indicates the transport that should be used for this call.

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.

InitialAudio − b, read-only

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

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 Call.DRAFT 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 = 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.

InitialVideo − b, read-only

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.

MutableContents − b, read-only

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 property is immutable, and therefore SHOULD be announced in NewChannels, etc.

Enumerated types:

Call_State

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.

Call_State_Unknown = 0

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.

Call_State_Pending_Initiator = 1

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.

Call_State_Pending_Receiver = 2

The receiver (the contact being called) hasn't accepted the call yet.

Call_State_Accepted = 3

The contact being called has accepted the call.

Call_State_Ended = 4

The call has ended, either via normal termination or an error.

Call_State_Change_Reason

Call_State_Change_Reason_Unknown = 0

We just don't know. Unknown values of this enum SHOULD also be treated like this.

Call_State_Change_Reason_User_Requested = 1

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

Sets of flags:

Call_Flags

Call_Flag_Locally_Ringing = 1

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 Ringing is called successfully, and unset when the state changes.

Call_Flag_Queued = 2

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.

Call_Flag_Locally_Held = 4

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!

Call_Flag_Forwarded = 8

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.

Call_Flag_In_Progress = 16

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.

Call_Flag_Clearing = 32

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.

Call_Member_Flags

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.

Call_Member_Flag_Ringing = 1

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.

Call_Member_Flag_Held = 2

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.

Structure types

Mapping types

org.freedesktop.Telepathy.Channel.Type.ServerAuthentication.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

AuthenticationInformation − a{sv}, read-only

Dictionary of information given by the CM which can be used by the handler for authentication.

AuthenticationMethod − u (Authentication_Type), read-only

This property defines the Method used for the current authentication step. The method also defines which Interfaces the channel implements. For exmaple if for the SASL method the SaslAuthentication interface needs to be implemented.

Enumerated types:

Authentication_Type

Authentication_Type_Sasl = 0

SASL authentication.

Authentication_Type_Captcha = 1

Captcha authentication.

Mapping types

org.freedesktop.Telepathy.Channel.Interface.SaslAuthentication.DRAFT

This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel
• org.freedesktop.Telepathy.Channel.Type.Server.Authentication.DRAFT

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

AvailableMechanisms − as, read-only

Example: [ "PLAIN", "DIGEST-MD5", "SCRAM-SHA-1" ] The SASL mechanisms as offered by the server.

Secure − b, read-only

Is this exchange secure (ie. TLS)? Good to know if you need to take a calculated risk with plaintext.

CurrentChallenge − ay, read-only

The current challenge from the server. change notification via NewChallenge. The handler either needs to respond by calling Respond (if it needs to send reply data), Accept (If the challenge contained final data) or Abort (in case of errors).

CurrentState − (uss) (Sasl_State), read-only

The current state of the authentication. Change notification via StateChanged signal.

Enumerated types:

Abort_Reason

Abort_Reason_Invalid_Challenge = 0

Server sent an invalid challenge or data.

Abort_Reason_User_Abort = 1

User aborted the authentication.

Sasl_Status

Sasl_Status_Not_Started = 0

Need to call StartMechanism to start.

Sasl_Status_In_Progress = 1

Challenge/Response cycle in progress

Sasl_Status_Server_Succeeded = 2

Server indicated successful authentication, handler needs to Accept or Abort.

Sasl_Status_Client_Accepted = 3

Handler indicates that from its perspective the authentication has successfully finished.

Sasl_Status_Succeeded = 4

Everyone is happy (server sent success, client sent Accept), up to the handler to close the channel.

Sasl_Status_Server_Failed = 5

Server indicated an authentication failure, Authentication can be restarted by calling StartMechanism again or completely aborted by Closing the channel.

Sasl_Status_Client_Failed = 6

Client indicated an authentication failure, Authentication can be restarted by calling StartMechanism again or completely aborted by Closing the channel.

Structure types

Generic types

Types defined elsewhere

Room_Handle − u

Defined by: Telepathy specification

Handle_Type − u

Defined by: Telepathy specification

Contact_Handle − u

Defined by: Telepathy specification

DBus_Unique_Name − s

Defined by: Telepathy specification

Generic types

Simple types

Enumerated types:

Media_Stream_Type

Media_Stream_Type_Audio = 0

An audio stream

Media_Stream_Type_Video = 1

A video stream

Media_Stream_State

Media_Stream_State_Disconnected = 0

The stream is disconnected.

Media_Stream_State_Connecting = 1

The stream is trying to connect.

Media_Stream_State_Connected = 2

The stream is connected.

Structure types

Types defined elsewhere

Contact_Handle − u

Defined by: Telepathy specification

DBus_Interface − s

Defined by: Telepathy specification

DBus_Qualified_Member − s

Defined by: Telepathy specification

Qualified_Property_Value_Map − a{sv}

Defined by: Telepathy specification

DBus_Error_Name − s

Defined by: Telepathy specification

DBus_Well_Known_Name − s

Defined by: Telepathy specification

Handler_Capability_Token − s

Defined by: Telepathy specification

VCard_Field − s

Defined by: Telepathy specification

VCard_Type_Parameter − s

Defined by: Telepathy specification

Contact_Info_Field − (sasas)

Defined by: Telepathy specification

Rich_Presence_Access_Control_Type − u

Defined by: Telepathy specification

Rich_Presence_Access_Control − (uv)

Defined by: Telepathy specification

Unix_Timestamp64 − t

Defined by: Telepathy specification

Unix_Timestamp − u

Defined by: Telepathy specification

String_String_Map − a{ss}

Defined by: Telepathy specification

String_Variant_Map − a{sv}

Defined by: Telepathy specification

Channel_Class − a{sv}

Defined by: Telepathy specification

Socket_Address_Type − u

Defined by: Telepathy specification

Socket_Access_Control − u

Defined by: Telepathy specification

Supported_Socket_Map − a{uau}

Defined by: Telepathy specification

DBus_Tube_Member − (us)

Defined by: Telepathy specification

Requestable_Channel_Class − (a{sv}as)

Defined by: Telepathy specification

Connection_Status − u

Defined by: Telepathy specification

Index

Index of interfaces

• org.freedesktop.Telepathy.ChannelBundle.DRAFT
• org.freedesktop.Telepathy.Channel.FUTURE
• org.laptop.Telepathy.BuddyInfo
• org.laptop.Telepathy.ActivityProperties
• org.freedesktop.Telepathy.Channel.Type.FileTransfer.FUTURE
• org.freedesktop.Telepathy.Connection.Interface.Gabble.Decloak
• org.freedesktop.Telepathy.Connection.Interface.MailNotification.DRAFT
• org.freedesktop.Telepathy.Connection.FUTURE
• org.freedesktop.Telepathy.Gabble.Plugin.Gateways
• org.freedesktop.Telepathy.Gabble.Plugin.Test
• org.freedesktop.Telepathy.Call.Content.DRAFT
• org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT
• org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT
• org.freedesktop.Telepathy.Call.Stream.DRAFT
• org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT
• org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT
• org.freedesktop.Telepathy.Channel.Type.Call.DRAFT
• org.freedesktop.Telepathy.Channel.Type.ServerAuthentication.DRAFT
• org.freedesktop.Telepathy.Channel.Interface.SaslAuthentication.DRAFT

Index of types

• Abort_Reason − u
• Activity − ( s, u )
• AuthDetails − a{ s → v }
• Authentication_Type − u
• Call_Content_Disposition − u
• Call_Flags − u
• Call_Member_Flags − u
• Call_Member_Map − a{ u → u }
• Call_State − u
• Call_State_Change_Reason − u
• Call_State_Reason − ( u, u, s )
• Candidate − ( u, s, q, a{sv} )
• Candidate_Info − a{ s → v }
• Channel_Class − a{sv}
• Codec − ( u, s, u, u, a{ss} )
• Codec_Offering − ( o, a{ua(usuua{ss})} )
• Connection_Status − u
• Contact_Codec_Map − a{ u → a(usuua{ss}) }
• Contact_Handle − u
• Contact_Handle − u
• Contact_Info_Field − (sasas)
• Contact_Sending_State_Map − a{ u → u }
• DBus_Error_Name − s
• DBus_Interface − s
• DBus_Qualified_Member − s
• DBus_Tube_Member − (us)
• DBus_Unique_Name − s
• DBus_Well_Known_Name − s
• HTTP_Method − u
• HTTP_Post_Data − ( s, s )
• Handle − u
• Handle_Type − u
• Handler_Capability_Token − s
• Mail − a{ s → v }
• Mail_Address − ( s, s )
• Mail_Notification_Flags − u
• Mail_URL − ( s, u, a(ss) )
• Media_Stream_State − u
• Media_Stream_Type − u
• Qualified_Property_Value_Map − a{sv}
• Requestable_Channel_Class − (a{sv}as)
• Rich_Presence_Access_Control − (uv)
• Rich_Presence_Access_Control_Type − u
• Room_Handle − u
• Sasl_State − ( u, s, s )
• Sasl_Status − u
• Sending_State − u
• Socket_Access_Control − u
• Socket_Address_IP − ( s, q )
• Socket_Address_IPv4 − ( s, q )
• Socket_Address_IPv6 − ( s, q )
• Socket_Address_Type − u
• Stream_Credentials − ( s, s )
• Stream_Transport_Type − u
• String_String_Map − a{ss}
• String_Variant_Map − a{sv}
• Supported_Socket_Map − a{uau}
• Unix_Timestamp − u
• Unix_Timestamp64 − t
• VCard_Field − s
• VCard_Type_Parameter − s