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

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Handler Capability Tokens | Types

Methods

Ringing () nothing
Accept () nothing
Hangup (u: Reason, s: Detailed_Hangup_Reason, s: Message) nothing
AddContent (s: Content_Name, u: Content_Type) o: Content

Signals

ContentAdded (o: Content, u: Content_Type)
ContentRemoved (o: Content)
CallStateChanged (u: Call_State, u: Call_Flags, (uus): Call_State_Reason, a{sv}: Call_State_Details)
CallMembersChanged (a{uu}: Flags_Changed, au: Removed)

Properties

Contents ao Read only
CallStateDetails a{sv} Read only
CallState u (Call_State) Read only
CallFlags u (Call_Flags) Read only
CallStateReason (uus) (Call_State_Reason) Read only
HardwareStreaming b Read only
CallMembers a{uu} (Call_Member_Map) Read only
InitialTransport s Read only
InitialAudio b Read only
InitialVideo b Read only
MutableContents b Read only

Handler Capability Tokens

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/gtalk-p2p
org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/ice
org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/wlm-8.5
org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/wlm-2009
org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264 (etc.)

Types

Call_State Enum u
Call_State_Change_Reason Enum u
Call_Flags Flags u
Call_Member_Flags Flags u
Call_Member_Map Mapping a{uu}
Call_State_Reason Struct (uus)
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.17.UNRELEASED. (as a draft)
Objects implementing this interface must also implement:

Description

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

Methods

(Permalink)

Ringing () → nothing

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_Initiator. While this is the case, this method SHOULD change the CallFlags to include Call_Flag_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.


Possible Errors

(Permalink)

Accept () → nothing

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


Possible Errors

  • Not Available
  • The call is not in one of the states where this method makes sense.
(Permalink)

Hangup (u: Reason, s: Detailed_Hangup_Reason, s: Message) → nothing

Parameters

  • Reason — u (Call_State_Change_Reason)
  • A generic hangup reason.
  • Detailed_Hangup_Reason — s (DBus_Error_Name)
  • A more specific reason for the call hangup, if one is available, or an empty string otherwise.
  • Message — s
  • A human-readable message to be sent to the remote contact(s).
    XMPP Jingle allows calls to be terminated with a human-readable message.
Request that the call is ended.

Possible Errors

(Permalink)

AddContent (s: Content_Name, u: Content_Type) → o: Content

Parameters

  • Content_Name — s
  • The suggested name of the content to add
    [FIXME: rationale]
  • Content_Type — u (Media_Stream_Type)
  • The media type of the content to add

Returns

[FIXME]

Possible Errors

Signals

(Permalink)

ContentAdded (o: Content, u: Content_Type)

Parameters

Emitted when a new Content.DRAFT is added to the call.

(Permalink)

ContentRemoved (o: Content)

Parameters

Emitted when a Content.DRAFT is removed from the call.

(Permalink)

CallStateChanged (u: Call_State, u: Call_Flags, (uus): Call_State_Reason, a{sv}: Call_State_Details)

Parameters

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.

(Permalink)

CallMembersChanged (a{uu}: Flags_Changed, au: Removed)

Parameters

  • Flags_Changed — a{uu} (Call_Member_Map)
  • 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.
  • Removed — au (Contact_Handle_List)
  • A list of members who have left the call, i.e. keys to be removed from CallMembers.
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.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

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.

(Permalink)

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

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.

(Permalink)

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.

(Permalink)

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.

(Permalink)

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.

(Permalink)

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

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.

(Permalink)

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.

(Permalink)

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.

(Permalink)

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.

Handler Capability Tokens

Tokens representing capabilities that a Client.Handler can have.
(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/gtalk-p2p

The client can implement streaming for streams whose Transport property is Stream_Transport_Type_GTalk_P2P.

(Permalink)

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

The client can implement streaming for streams whose Transport property is Stream_Transport_Type_ICE.

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/wlm-8.5

The client can implement streaming for streams whose Transport property is Stream_Transport_Type_WLM_8_5.

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/wlm-2009

The client can implement streaming for streams whose Transport property is Stream_Transport_Type_WLM_2009.

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264 (etc.)

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 Speex, Theora and H264 by having three handler capability tokens, org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex, org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora and org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/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.

Types

Enum (Permalink)

Call_State — u

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.

  • 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.
  • 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.
  • Pending_Receiver (2)
  • The receiver (the contact being called) hasn't accepted the call yet.
  • Accepted (3)
  • The contact being called has accepted the call.
  • Ended (4)
  • The call has ended, either via normal termination or an error.
Enum (Permalink)

Call_State_Change_Reason — u

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.
  • Unknown (0)
  • We just don't know. Unknown values of this enum SHOULD also be treated like this.
  • 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.).

Flags (Permalink)

Call_Flags — u

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.
  • 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.
  • 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.
  • 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!
  • 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.
  • 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.
  • 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.
Flags (Permalink)

Call_Member_Flags — u

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.

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

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

Mapping (Permalink)

Call_Member_Map — a{uu}

A mapping from handles to their current state in the call.
Struct (Permalink)

Call_State_Reason — (uus)

A description of the reason for a change to the CallState and/or CallFlags.

  • Actor — u (Contact_Handle)
  • The contact responsible for the change, or 0 if no contact was responsible.
  • Reason — u (Call_State_Change_Reason)
  • The reason, chosen from a limited set of possibilities defined by the Telepathy specification.
  • DBus_Reason — s (DBus_Error_Name)
  • 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.