Methods
Ringing | () | → | nothing | |
Accept | () | → | nothing | |
Hangup | (u: Reason, s: Detailed_Hangup_Reason, string: Message) | → | nothing | |
AddContent | (s: ContentName, u: ContentType) | → | o: Content |
Signals
ContentAdded | (o: Content, u: ContentType) | |
ContentRemoved | (o: Content) | |
CallStateChanged | (u: CallState, u: CallFlags, (uus): CallStateReason, a{sv}: CallStateDetails) | |
CallMembersChanged | (a{uu}: FlagsChanged, 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
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) |
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
Accept () → nothing
Hangup (u: Reason, s: Detailed_Hangup_Reason, string: Message) → nothing
Parameters
- Reason — u (Call_State_Change_Reason)
- Detailed_Hangup_Reason — s (DBus_Error_Name)
- Message — string
AddContent (s: ContentName, u: ContentType) → o: Content
Parameters
- ContentName — s
- ContentType — u (Media_Stream_Type)
Returns
- Content — o
Possible Errors
Signals
ContentAdded (o: Content, u: ContentType)
Parameters
- Content — o
- ContentType — u (Media_Stream_Type)
Emitted when a new content is added to the call
ContentRemoved (o: Content)
Parameters
- Content — o
Emitted when a contents is removed from a call
CallStateChanged (u: CallState, u: CallFlags, (uus): CallStateReason, a{sv}: CallStateDetails)
Parameters
- CallState — u (Call_State)
- CallFlags — u (Call_Flags)
- CallStateReason — (uus)
- CallStateDetails — a{sv}
Emitted when the state of a contact on the call changed
CallMembersChanged (a{uu}: FlagsChanged, au: Removed)
Parameters
- FlagsChanged — a{uu} (Call_Member_Map)
- Removed — au (Contact_Handle_List)
Properties
Contents — ao
The list of Content.Draft objects that are part of this call. ChangeNotification happens via the ContentAdded and ContentRemoved signals.
CallStateReason — (uus) (Call_State_Reason)
The reason the call is in the state it is in :)
HardwareStreaming — b
If this property is TRUE then all the media streaming is done by a specialized component If this is FALSE then the handler should handle the media streaming at least some parts itself.
CallMembers — a{uu} (Call_Member_Map)
InitialTransport — s
If set on a requested channel this indicates the transport that should be used for this call.
InitialAudio — b
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
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
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
org.freedesktop.Telepathy.Channel.Type.Call.Draft/gtalk-p2p
The client can implement streaming for streams whose NATTraversal
property is gtalk-p2p
.
org.freedesktop.Telepathy.Channel.Type.Call.Draft/ice-udp
The client can implement streaming for streams whose NATTraversal
property is ice-udp
.
org.freedesktop.Telepathy.Channel.Type.Call.Draft/wlm-8.5
The client can implement streaming for streams whose NATTraversal
property is wlm-8.5
.
org.freedesktop.Telepathy.Channel.Type.Call.Draft/wlm-2009
The client can implement streaming for streams whose NATTraversal
property is wlm-2009
.
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
Call_State — u
- PendingInitiator (1)
- PendingReceiver (2)
- Accepted (3)
- Ended (4)
Call_State_Change_Reason — u
- Unknown (0)
- UserRequested (1)
- UserRequested (1)
Call_Flags — u
- Ringing (1)
- Queued (2)
- Held (4)
- Forwarded (8)
- In_Progress (16)
- Clearing (32)
Call_Member_Flags — u
- Ringing (1)
- Held (2)
Call_Member_Map — a{uu}
- key — u (Handle)
- Flag — u (Call_Member_Flags)
Call_State_Reason — (uus)
- actor — u (Handle)
- Reason — u (Call_State_Change_Reason)
- DbusReason — s (DBus_Error_Name)