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, "im.telepathy1.Error.Rejected").

Incoming calls

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

NewChannels([
  /im/telepathy1/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, "im.telepathy1.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, "im.telepathy1.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, "im.telepathy1.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, "im.telepathy1.Error.Terminated", "") before actually closing the channel.