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.DRAFT objects represent the actual media that forms the Call (for example an audio content and a video content). Calls always have one or more Content objects associated with them. As a result, a new Call channel request MUST have either InitialAudio=True, or InitialVideo=True, or both, as the Requestable Channel Classes will document.

Content.DRAFT objects have one or more stream associated with them. More information on these streams and how to maniuplate them can be found on the Content.DRAFT interface page.

Outgoing calls

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

CreateChannel({
  ...ChannelType: ...Call.DRAFT,
  ...TargetHandleType: Contact,
  ...TargetID: 'foo@example.com',
  ...InitialAudio: True,
})

As always, TargetHandle may be used in place of TargetID if the contact's handle is already known. To make an audio and video call, the handler should also specify InitialVideo The connection manager SHOULD return a channel whose immutable properties contain the local user as the InitiatorHandle, the remote contact as the TargetHandle, Requested = True (indicating the call is outgoing).

After a new Call channel is requested, the CallState property will be Call_State_Pending_Initiator. As the local user is the initiator, the call must be accepted by the handler by calling the Accept method. At this point, CallState changes to Call_State_Pending_Receiver which signifies that the call is ringing, waiting for the remote contact to accept the call. All changes to CallState property are signalled using the CallStateChanged signal.

When the call is accepted by the remote contact, the CallStateChanged signal fires again to show that CallState = Call_State_Accepted.

At this point telepathy-farstream will signal that a pad is available for the handler to show in the user interface.

Missed calls

If the remote contact does not accept the call in time, then the call can be terminated by the server. Note that this only happens in some protocols. Most XMPP clients, for example, do not do this and rely on the call initiator terminating the call. A missed call is shown in a Call channel by the CallState property changing to Call_State_Ended, and the CallStateReason property changing to (remote contact, Call_State_Change_Reason_No_Answer, "").

Rejected calls

If the remote contact decides he or she does not feel like talking to the local user, he or she can reject his or her incoming call. This will be shown in the Call channel by CallState changing to Call_State_Ended and the CallStateReason property changing to (remote contact, Call_State_Change_Reason_User_Requested, "org.freedesktop.Telepathy.Error.Rejected").

Incoming calls

When an incoming call occurs, something like the following NewChannels signal will occur:

NewChannels([
  /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
  {
    ...ChannelType: ...Call.DRAFT,
    ...TargetHandleType: Contact,
    ...TargetID: 'foo@example.com',
    ...TargetHandle: 42,
    ...Requested: False,
    ...InitialAudio: True,
    ...InitialVideo: True,
    ...InitialAudioName: "audio",
    ...InitialVideoName: "video",
    ...MutableContents: True,
  }])

The InitialAudio and InitialVideo properties show that the call has been started with two contents: one for audio streaming and one for video streaming. The InitialAudioName and InitialVideoName properties also show that the aforementioned audio and video contents have names "audio" and "video".

Once the handler has notified the local user that there is an incoming call waiting for acceptance, the handler should call SetRinging to let the CM know. The new channel should also be given to telepathy-farstream to work out how the two participants will connect together. telepathy-farstream will call the appropriate methods on the call's Content.DRAFTs to negotiate codecs and transports.

To pick up the call, the handler should call Accept. The CallState property changes to Call_State_Accepted and once media is being transferred, telepathy-farstream will notify the handler of a new pad to be shown to the local user in the UI

To reject the call, the handler should call the Hangup method. The CallState property will change to Call_State_Ended and the CallStateReason property will change to (self handle, Call_State_Change_Reason_User_Requested, "org.freedesktop.Telepathy.Error.Rejected").

Ongoing calls

Adding and removing contents

When a call is open, new contents can be added as long as the CM supports it. The MutableContents property will let the handler know whether further contents can be added or existing contents removed. An example of this is starting a voice call between a contact and then adding a video content. To do this, the should call AddContent like this:

AddContent("video",
           Media_Stream_Type_Video)

Assuming no errors, the new video content will be added to the call. telepathy-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.DRAFT object.

Ending the call

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

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

Multi-party calls

Call states

There are many combinations of the CallState and CallStateReason properties which mean different things. Here is a table to try to make these meanings clearer:

Requestable channel classes

The RequestableChannelClasses for Call.DRAFT channels can be:

[( Fixed = { ...ChannelType: ...Call.DRAFT,
            ...TargetHandleType: Contact,
            ...InitialVideo: True
          },
  Allowed = [ ...InitialVideoName,
              ...InitialAudio,
              ...InitialAudioName
            ]
),
( Fixed = { ...ChannelType: ...Call.DRAFT,
            ...TargetHandleType: Contact,
            ...InitialAudio: True
          },
  Allowed = [ ...InitialAudioName,
              ...InitialVideo,
              ...InitialVideoName
            ]
)]

Clients aren't allowed to make outgoing calls that have neither initial audio nor initial video. Clearly, CMs which don't support video should leave out the first class and omit InitialVideo from the second class, and vice versa for CMs without audio support.

Handlers should not close Call.DRAFT channels without first calling Hangup on the channel. If a Call handler crashes, the ChannelDispatcher will call Close on the channel which SHOULD also imply a call to Hangup(Call_State_Change_Reason_User_Requested, "org.freedesktop.Telepathy.Error.Terminated", "") before actually closing the channel.