Interface Channel.Type.Call1

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

Methods

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

Signals

ContentAdded (o: Content)
ContentRemoved (o: Content, (uuss): Reason)
CallStateChanged (u: Call_State, u: Call_Flags, (uuss): Call_State_Reason, a{sv}: Call_State_Details)
CallMembersChanged (a{uu}: Flags_Changed, a{us}: Identifiers, au: Removed, (uuss): Reason)

Properties

Contents ao Read only
CallStateDetails a{sv} Read only
CallState u (Call_State) Read only
CallFlags u (Call_Flags) Read only
CallStateReason (uuss) (Call_State_Reason) Read only
HardwareStreaming b Read only Immutable
CallMembers a{uu} (Call_Member_Map) Read only
MemberIdentifiers a{us} (Handle_Identifier_Map) Read only
InitialTransport u (Stream_Transport_Type) Read only Immutable, Requestable
InitialAudio b Read only Immutable, Requestable
InitialVideo b Read only Immutable, Requestable
InitialAudioName s Read only Immutable, Requestable
InitialVideoName s Read only Immutable, Requestable
MutableContents b Read only Immutable

Handler Capability Tokens

org.freedesktop.Telepathy.Channel.Type.Call1/audio
org.freedesktop.Telepathy.Channel.Type.Call1/video
org.freedesktop.Telepathy.Channel.Type.Call1/gtalk-p2p
org.freedesktop.Telepathy.Channel.Type.Call1/ice
org.freedesktop.Telepathy.Channel.Type.Call1/wlm-2009
org.freedesktop.Telepathy.Channel.Type.Call1/shm
org.freedesktop.Telepathy.Channel.Type.Call1/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 (uuss)
Added in 0.25.2. (as stable API)
Objects implementing this interface must also implement:

Description

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-farstream 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 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 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 interface page.

Outgoing calls

To make an audio-only call to a contact foo@example.com handlers should call:

CreateChannel({
  ...ChannelType: ...Call1,
  ...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 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 Initialising, which signifies that the call is waiting for the network to do something. When the CM has information indicating that the remote contact has been notified about the call (or immediately if the network is known not to convey such information) it should also change to Initialised. All changes to the 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 = Accepted.

At this point telepathy-farstream will signal that a pad is available for the handler to show in the user interface. Once media is correctly flowing in both directions, the state will change to Active, to inform the user that they have a correctly working call there is nothing amiss.

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 Ended, and the CallStateReason property changing to (remote contact, 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 Ended and the CallStateReason property changing to (remote contact, 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: ...Call1,
    ...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-farstream to work out how the two participants will connect together. telepathy-farstream will call the appropriate methods on the call's Contents to negotiate codecs and transports.

To pick up the call, the handler should call Accept. The CallState property changes to Accepted and once media is being transferred, telepathy-farstream will notify the handler of a new pad to be shown to the local user in the UI. Once media is correctly flowing in both directions, the state will change to Active, to inform the user that they have a correctly working call there is nothing amiss.

To reject the call, the handler should call the Hangup method. The CallState property will change to Ended and the CallStateReason property will change to (self handle, 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",
           Video)

Assuming no errors, the new video content will be added to the call. telepathy-farstream will pick up the new content and perform the transport and codec negotiation automatically. telpathy-farstream 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 object.

Ending the call

To end the call, the handler should call the Hangup method. The CallState property will change to Ended and CallStateReason will change to (self handle, User_Requested, "org.freedesktop.Telepathy.Error.Cancelled").

If the other participant hangs up first then the CallState property will change to Ended and CallStateReason will change to (remote contact, User_Requested, "org.freedesktop.Telepathy.Error.Terminated").

Multi-party calls

Requestable channel classes

The RequestableChannelClasses for Call1 channels can be:

[( Fixed = { ...ChannelType: ...Call1,
            ...TargetHandleType: Contact,
            ...InitialVideo: True
          },
  Allowed = [ ...InitialVideoName,
              ...InitialAudio,
              ...InitialAudioName
            ]
),
( Fixed = { ...ChannelType: ...Call1,
            ...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 Call1 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(User_Requested, "org.freedesktop.Telepathy.Error.Terminated", "") before actually closing the channel.

Methods

(Permalink)

SetRinging () → nothing

Changed in 0.21.2. 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 Initialised (an incoming call is ready and waiting for the user to be notified). Calling this method SHOULD set CallFlags' bit Locally_Ringing, and notify the remote contact that the local user has been alerted (if the protocol supports 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)

SetQueued () → nothing

Changed in 0.21.2. renamed from Ringing

Notifies the CM that the local user is already in a call, so this call has been put in a call-waiting style queue.

This method is only useful if the channel's Requested property is False, and the CallState is Initialising or Initialised. Calling this method SHOULD set CallFlags' bit Locally_Queued, and notify the remote contact that the call is in a queue (if the protocol supports this); repeated calls to this method SHOULD succeed, but have no further effect.

Locally_Queued is a little like Locally_Held, but applies to calls that have not been Accepted (the Locally_Queued flag should be unset by the CM when Accept is called). It should also be set in response to the state of the world, rather than in response to user action.


Possible Errors

(Permalink)

Accept () → nothing

For incoming calls in state Initialised, accept the incoming call. This changes the CallState to Accepted.

For outgoing calls in state Pending_Initiator, actually call the remote contact; this changes the CallState to Initialising.

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 whose Disposition is Initial, any streams where the LocalSendingState is Pending_Send will be moved to 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).
    Rationale:
    XMPP Jingle allows calls to be terminated with a human-readable message.
Request that the call is ended. All contents will be removed from the Call so that the Contents property will be the empty list.

Possible Errors

(Permalink)

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

Parameters

  • Content_Name — s
  • The suggested name of the content to add.

    Rationale:
    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)".

  • Content_Type — u (Media_Stream_Type)
  • The media stream type of the content to be added to the call.
  • InitialDirection — u (Media_Stream_Direction)
  • The requested initial direction of the new content.

Returns

Request that a new Content of type Content_Type is added to the Call1. Handlers should check the value of the MutableContents property before trying to add another content as it might not be allowed.

Possible Errors

  • Invalid Argument
  • The media stream type given is invalid.
  • Not Implemented
  • The media stream type requested is not implemented by the CM.
  • Media.Unsupported Type
  • The media stream type requested is not supported by either the local or remote side.
  • Not Capable
  • 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.

Signals

(Permalink)

ContentAdded (o: Content)

Parameters

  • Content — o
  • Path to the newly-created Content object.

Emitted when a new Content is added to the call.

(Permalink)

ContentRemoved (o: Content, (uuss): Reason)

Parameters

Emitted when a Content is removed from the call.

(Permalink)

CallStateChanged (u: Call_State, u: Call_Flags, (uuss): 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, a{us}: Identifiers, au: Removed, (uuss): Reason)

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.
  • Identifiers — a{us} (Handle_Identifier_Map)
  • The identifiers of the contacts in the Flags_Changed map.
  • Removed — au (Contact_Handle_List)
  • A list of members who have left the call, i.e. keys to be removed from CallMembers.
  • Reason — (uuss) (Call_State_Reason)
  • A structured reason for the change.
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 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 Ended.
Rationale:
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 Locally_Queued is in the call flags.
Rationale:
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 Ended.
balance-required - i
Optionally included when a call cannot be connected because there is InsufficientBalance, indicating what the required balance would be to place this call. The value of this key has the same units and scale as AccountBalance.
forwarded-to - u
Optionally included when the CallStateReason is Forwarded. It indicates the handle to whom the Call was forwarded.
forwarded-to-id - s
The string that would result from inspecting the forwarded-to key (i.e. the contact's identifier in the IM protocol).
(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.

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.

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

When an ongoing call is active and not on hold or has any other problems, this property will be 0.

(Permalink)

CallStateReason — (uuss) (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
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.

If this property is True, all of the media streaming is done by some mechanism outside the scope of Telepathy.

Rationale:

A connection manager might be intended for a specialized hardware device, which will take care of the audio streaming (e.g. telepathy-ring, 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 interface, to communicate the necessary information to a streaming implementation. Connection managers SHOULD operate like this, if possible.

Rationale:

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

(Permalink)

MemberIdentifiers — a{us} (Handle_Identifier_Map)

Read only
The string identifiers for handles mentioned in CallMembers, to give clients the minimal information necessary to create contacts without waiting for round-trips.
(Permalink)

InitialTransport — u (Stream_Transport_Type)

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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 Unknown, in particular, on CMs with hardware streaming.

Rationale:
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
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by 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.

Rationale:

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
Rationale:

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
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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)

InitialAudioName — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.
Added in 0.21.2.

If InitialAudio is set to True, then this property will name the intial audio content with the value of this property.

Rationale:

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.

(Permalink)

InitialVideoName — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.
Added in 0.21.2.

The same as InitialAudioName, but for a video stream created by setting InitialVideo to True. This property is immutable and so cannot change.

(Permalink)

MutableContents — b

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.

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.

Rationale:

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 "Call1" button with the option to add and remove video once the call has started for contacts without this flag.

Handler Capability Tokens

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

org.freedesktop.Telepathy.Channel.Type.Call1/audio

This client supports audio calls.

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/video

This client supports video calls.

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/gtalk-p2p

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

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/ice

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

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/wlm-2009

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

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/shm

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

(Permalink)

org.freedesktop.Telepathy.Channel.Type.Call1/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.

Rationale:

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.Call1/audio
  • org.freedesktop.Telepathy.Channel.Type.Call1/audio/speex
  • org.freedesktop.Telepathy.Channel.Type.Call1/video
  • org.freedesktop.Telepathy.Channel.Type.Call1/video/theora
  • org.freedesktop.Telepathy.Channel.Type.Call1/video/h264

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

Rationale:

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 → Initialising (for outgoing calls, when Accept is called)
  • Initialising → Initialised (for outgoing calls, when the remote client indicates that the user has been notified about the call. If the network is known not to provide feedback about whether the remote side is ringing, then the call should immediately be set to Initialised.
  • Initialising → Initialised (for incoming calls, when e.g. the implementation has been initialised far enough that it is sensible to notify the user about the call (to reduce the probability that the user will pick up the call and have it immediately fail). The UI should then alert the user about the call, and call SetRinging)
  • Initialised → Accepted (for outgoing calls to a contact, when the remote contact accepts the call; for incoming calls, when Accept is called.)
  • Accepted → Active (when the local user successfully joins the call/conference, and media is known to be flowing successfully; also, when temporary connection problems are resolved (See below)). If the network is known not to provide feedback about when the call is properly connected, the call should immediately be set to Active.
  • Active → Accepted (when there are temporary connection problems that the CM is aware of and able to recover from)
  • any state → Ended (when the call is terminated normally, or when an error occurs that the CM is unable to recover from)

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.
  • Initialising (2)
  • Progress has been made in placing the call, but the contact has not been made aware of the call yet. This corresponds to SIP's status code 183 Session Progress, and should be used for the period where the CM is waiting for the streaming implementation to initialise (before sending the initial INVITE or equivalent) and when the outgoing call has reached a gateway or ICE negotiation is pending. UIs should not produce a dialtone or start ringing if the call is in this state.
  • Initialised (3)
  • In the outgoing case: at least one called user has been alerted about the call (a SIP 180 (Ringing) packet or equivalent has been received) but none have answered, so the call cannot go to Accepted (use Ringing to determine which members have been informed and which haven't, if you care). UIs SHOULD produce a dialtone for outgoing calls in this state. In the incoming case, the local user should be informed of the call as soon as the call reaches this state (and SetRinging should be called to inform the CM that this has happened, so that it can relay this fact to the caller using a SIP 180 (Ringing) packet or equivalent).
  • Accepted (4)
  • The contact being called has accepted the call, but the call is not in the Active state (The most common reason for this is that the streaming implementation hasn't connected yet).
  • Active (5)
  • The contact being called has accepted the call, and discourse between at least two parties should now be possible.
  • Ended (6)
  • 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.
  • Progress_Made (1)
  • Situation normal. Progress has been made in the setup/teardown of the call (and it didn't require any user interaction).
  • User_Requested (2)
  • The change was requested by the contact indicated by the Actor member of a Call_State_Reason struct.

    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 (kicked from a conference by a moderator, etc.).

  • Forwarded (3)
  • The call was forwarded. If known, the handle of the contact the call was forwarded to will be indicated by the "forwarded-to" member of a CallStateDetails dictionnary in the CallStateChanged signal.

  • Rejected (4)
  • Added in 0.21.2.

    The CallState changed from Initialised or Ended (or a content's direction changed) because it was rejected by the remote user.

    Corresponds to Rejected

  • No_Answer (5)
  • Added in 0.21.2.

    The CallState changed from Initialised or Ended because the initiator ended the call before the receiver accepted it. With an incoming call this state change reason signifies a missed call, or one that was picked up elsewhere before it was picked up here.

    Corresponds to NoAnswer or PickedUpElsewhere

  • Invalid_Contact (6)
  • Added in 0.21.2.

    The CallState changed because one of the addresses does not exist on the network.

    Corresponds to DoesNotExist

  • Permission_Denied (7)
  • Added in 0.21.2.

    The CallState changed because the local user is not authorised.

    Corresponds to PermissionDenied or InsufficientBalance

  • Busy (8)
  • Added in 0.21.2.

    The CallState changed from Initialised Ended because the receiver is busy (e.g. is already engaged in another call, and has not placed the initiator in a call-waiting queue).

    Corresponds to Busy

  • Internal_Error (9)
  • Added in 0.21.2.

    There has been an unexpected error in either the CM or some other local component.

    Corresponds to Confused or Media.StreamingError

  • Service_Error (10)
  • Added in 0.21.2.

    There has been an unexpected error in the server or some other remote component.

    Corresponds to ServiceConfused

  • Network_Error (11)
  • Added in 0.21.2.

    There has been a network error related to the CM or the signalling part of the call (compare and contrast: Streaming_Error).

    Corresponds to NetworkError

  • Media_Error (12)
  • Some aspect of the content is unsupported so has to be removed from the call.

    Corresponds to Media.UnsupportedType or Media.CodecsIncompatible

  • Connectivity_Error (13)
  • It was not possible for the streaming implementation to connect to any of the users participating in this call or content.

    Corresponds to ConnectionFailed or ConnectionLost

Flags (Permalink)

Call_Flags — u

A set of flags representing additional information than is available in CallState. Many of these flags only make sense in a particular (or may explain why a call is in a specific state).
  • Locally_Held (1)
  • 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.
    Rationale:
    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! This flag exists as a simplified proxy for HoldStateChanged, to reduce the number of signals that need to be listened to by a simple UI.
  • Locally_Ringing (2)
  • This flag exists for observability of the SetRinging method (e.g. so that loggers can tell whether the call got as far as alerting the user, or whether something went wrong before then). It should be set when the SetRinging is called, and unset when the call leaves Initialised.
  • Locally_Queued (4)
  • This flag exists for observability of the SetQueued method. It should be set when the SetQueued is called, and unset when the call leaves Initialising or Initialised.
  • 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. It SHOULD be set or unset according to informational messages from other contacts.
  • Clearing (16)
  • 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.
    Rationale:
    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.

Rationale:

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.

    Rationale:

    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.

    Rationale:

    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.

  • Conference_Host (4)
  • 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.
Mapping (Permalink)

Call_Member_Map — a{uu}

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

Call_State_Reason — (uuss)

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. If User_Requested then the Actor member will dictate whether it was the local user or a remote contact responsible.
  • 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.

    Rationale:

    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.

  • Message — s
  • An optional debug message, to expediate debugging the potentially many processes involved in a call. This may be communicated across the network in protocols that support doing so, but it is not essential.