Interface Media.StreamHandler

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

Methods

CodecChoice (u: Codec_ID) → nothing
Error (u: Error_Code, s: Message) → nothing
NativeCandidatesPrepared () → nothing
NewActiveCandidatePair (s: Native_Candidate_ID, s: Remote_Candidate_ID) → nothing
NewActiveTransportPair (s: Native_Candidate_ID, (usuussduss): Native_Transport, s: Remote_Candidate_ID, (usuussduss): Remote_Transport) → nothing
NewNativeCandidate (s: Candidate_ID, a(usuussduss): Transports) → nothing
Ready (a(usuuua{ss}): Codecs) → nothing
SetLocalCodecs (a(usuuua{ss}): Codecs) → nothing
StreamState (u: State) → nothing
SupportedCodecs (a(usuuua{ss}): Codecs) → nothing
CodecsUpdated (a(usuuua{ss}): Codecs) → nothing
HoldState (b: Held) → nothing
UnholdFailure () → nothing
SupportedFeedbackMessages (a{u(ua(sss))}: Messages) → nothing
SupportedHeaderExtensions (a(uuss): Header_Extensions) → nothing

Signals

AddRemoteCandidate (s: Candidate_ID, a(usuussduss): Transports)
Close ()
RemoveRemoteCandidate (s: Candidate_ID) (deprecated)
SetActiveCandidatePair (s: Native_Candidate_ID, s: Remote_Candidate_ID)
SetRemoteCandidateList (a(sa(usuussduss)): Remote_Candidates)
SetRemoteCodecs (a(usuuua{ss}): Codecs)
SetStreamPlaying (b: Playing)
SetStreamSending (b: Sending)
StartTelephonyEvent (y: Event)
StartNamedTelephonyEvent (y: Event, u: Codec_ID)
StartSoundTelephonyEvent (y: Event)
StopTelephonyEvent ()
SetStreamHeld (b: Held)
SetRemoteFeedbackMessages (a{u(ua(sss))}: Messages)
SetRemoteHeaderExtensions (a(uuss): Header_Extensions)

Properties

STUNServers a(sq) ( Socket_Address_IP_List) Read only
CreatedLocally b Read only
NATTraversal s Read only
RelayInfo aa{sv} ( String_Variant_Map_List) Read only

Types

Media_Stream_Error Enum u
Media_Stream_Base_Proto Enum u
Media_Stream_Transport_Type Enum u
RTCP_Feedback_Message_Map Mapping a{u(ua(sss))}
Media_Stream_Handler_Candidate Struct (sa(usuussduss))
Media_Stream_Handler_Transport Struct (usuussduss)
Media_Stream_Handler_Codec Struct (usuuua{ss})
RTCP_Feedback_Message_Properties Struct (ua(sss))
RTCP_Feedback_Message Struct (sss)
RTP_Header_Extension Struct (uuss)
Objects implementing this interface must also implement:

Description

Handles signalling the information pertaining to a specific media stream. A client should provide information to this handler as and when it is available.

Methods

(Permalink)

CodecChoice (u: Codec_ID) → nothing

Parameters

  • Codec_ID — u
Inform the connection manager of codec used to receive data.
(Permalink)

Error (u: Error_Code, s: Message) → nothing

Parameters

  • Error_Code — u (Media_Stream_Error)
    • ID of error, from the MediaStreamError enumeration
  • Message — s
    • String describing the error
Inform the connection manager that an error occured in this stream. The connection manager should emit the StreamError signal for the stream on the relevant channel, and remove the stream from the session.
(Permalink)

NativeCandidatesPrepared () → nothing

Informs the connection manager that all possible native candisates have been discovered for the moment.
(Permalink)

NewActiveCandidatePair (s: Native_Candidate_ID, s: Remote_Candidate_ID) → nothing

Parameters

  • Native_Candidate_ID — s
  • Remote_Candidate_ID — s
Informs the connection manager that a valid candidate pair has been discovered and streaming is in progress.
(Permalink)

NewActiveTransportPair (s: Native_Candidate_ID, (usuussduss): Native_Transport, s: Remote_Candidate_ID, (usuussduss): Remote_Transport) → nothing

Parameters

Informs the connection manager that a valid transport pair has been discovered and streaming is in progress. Component id MUST be the same for both transports and the pair is only valid for that component.

Rationale:

The connection manager might need to send the details of the active transport pair (e.g. c and o parameters of SDP body need to contain address of selected native RTP transport as stipulated by RFC 5245). However, the candidate ID might not be enough to determine these info if the transport was found after NativeCandidatesPrepared has been called (e.g. peer reflexive ICE candidate).

This method must be called before NewActiveCandidatePair.

Rationale:

This way, connection managers supporting this method can safely ignore subsequent NewActiveCandidatePair call.

Connection managers SHOULD NOT implement this method unless they need to inform the peer about selected transports. As a result, streaming implementations MUST NOT treat errors raised by this method as fatal.

Rationale:

Usually, connection managers only need to do one answer/offer round-trip. However, some protocols give the possibility to to send an updated offer (e.g. ICE defines such mechanism to avoid some race conditions and to properly set the state of gateway devices).

(Permalink)

NewNativeCandidate (s: Candidate_ID, a(usuussduss): Transports) → nothing

Parameters

  • Candidate_ID — s
    • String identifier for this candidate
  • Transports — a(usuussduss) (Media_Stream_Handler_Transport_List)
    • Array of transports for this candidate, with fields:
    • component number
    • IP address (as a string)
    • port
    • base network protocol (one of the values of MediaStreamBaseProto)
    • proto subtype (e.g. RTP)
    • proto profile (e.g. AVP)
    • our preference value of this transport (double in range 0.0-1.0 inclusive); 1 signals the most preferred transport
    • transport type, one of the values of MediaStreamTransportType
    • username if authentication is required
    • password if authentication is required
Inform this MediaStreamHandler that a new native transport candidate has been ascertained.
(Permalink)

Ready (a(usuuua{ss}): Codecs) → nothing

Parameters

Inform the connection manager that a client is ready to handle this StreamHandler. Also provide it with info about all supported codecs.
(Permalink)

SetLocalCodecs (a(usuuua{ss}): Codecs) → nothing

Parameters

Used to provide codecs after Ready(), so the media client can go ready for an incoming call and exchange candidates/codecs before knowing what local codecs are available.

This is useful for gatewaying calls between two connection managers. Given an incoming call, you need to call Ready to get the remote codecs before you can use them as the "local" codecs to place the outgoing call, and hence receive the outgoing call's remote codecs to use as the incoming call's "local" codecs.

In this situation, you would pass an empty list of codecs to the incoming call's Ready method, then later call SetLocalCodecs on the incoming call in order to respond to the offer.

(Permalink)

StreamState (u: State) → nothing

Parameters

Informs the connection manager of the stream's current state, as as specified in Channel.Type.StreamedMedia::ListStreams.
(Permalink)

SupportedCodecs (a(usuuua{ss}): Codecs) → nothing

Parameters

Inform the connection manager of the supported codecs for this session. This is called after the connection manager has emitted SetRemoteCodecs to notify what codecs are supported by the peer, and will thus be an intersection of all locally supported codecs (passed to Ready) and those supported by the peer.
(Permalink)

CodecsUpdated (a(usuuua{ss}): Codecs) → nothing

Parameters

  • Codecs — a(usuuua{ss}) (Media_Stream_Handler_Codec_List)
    • Locally supported codecs, which SHOULD be the same as were previously in effect, but possibly with different parameters.
Inform the connection manager that the parameters of the supported codecs for this session have changed. The connection manager should send the new parameters to the remote contact.
Rationale:
This is required for H.264 and Theora, for example.
(Permalink)

HoldState (b: Held) → nothing

Added in 0.17.3.

Parameters

  • Held — b
    • If true, the stream is now on hold.
Notify the connection manager that the stream's hold state has been changed successfully in response to SetStreamHeld.
(Permalink)

UnholdFailure () → nothing

Added in 0.17.3.
Notify the connection manager that an attempt to reacquire the necessary hardware or software resources to unhold the stream, in response to SetStreamHeld, has failed.
(Permalink)

SupportedFeedbackMessages (a{u(ua(sss))}: Messages) → nothing

Added in 0.22.1.

Parameters

Inform the connection manager of the supported feedback messages for this session. This is called a before calling SupportedCodecs, Ready or CodecsUpdated to indicate the local, or negotiated feedback messages.
(Permalink)

SupportedHeaderExtensions (a(uuss): Header_Extensions) → nothing

Added in 0.22.1.

Parameters

Inform the connection manager of the supported RTP header extensions for this session. This is called before calling SupportedCodecs, Ready or CodecsUpdated to indicate the local or negotiated RTP header extensions.

Signals

(Permalink)

AddRemoteCandidate (s: Candidate_ID, a(usuussduss): Transports)

Parameters

  • Candidate_ID — s
    • String identifier for this candidate
  • Transports — a(usuussduss) (Media_Stream_Handler_Transport_List)
    • Array of transports for this candidate with fields, as defined in NewNativeCandidate
Signal emitted when the connection manager wishes to inform the client of a new remote candidate.
(Permalink)

Close ()

Signal emitted when the connection manager wishes the stream to be closed.
(Permalink)

RemoveRemoteCandidate (s: Candidate_ID)

Deprecated since 0.17.18. There is no case where you want to release candidates (except for an ICE reset, and there you'd want to replace then all, using SetRemoteCandidateList).

Parameters

  • Candidate_ID — s
    • String identifier for remote candidate to drop
Signal emitted when the connection manager wishes to inform the client that the remote end has removed a previously usable candidate.
Rationale:
It seemed like a good idea at the time, but wasn't.
(Permalink)

SetActiveCandidatePair (s: Native_Candidate_ID, s: Remote_Candidate_ID)

Parameters

  • Native_Candidate_ID — s
  • Remote_Candidate_ID — s
Emitted by the connection manager to inform the client that a valid candidate pair has been discovered by the remote end and streaming is in progress.
(Permalink)

SetRemoteCandidateList (a(sa(usuussduss)): Remote_Candidates)

Parameters

Signal emitted when the connection manager wishes to inform the client of all the available remote candidates at once.
(Permalink)

SetRemoteCodecs (a(usuuua{ss}): Codecs)

Parameters

Signal emitted when the connection manager wishes to inform the client of the codecs supported by the remote end. If these codecs are compatible with the remote codecs, then the client must call SupportedCodecs, otherwise call Error.
(Permalink)

SetStreamPlaying (b: Playing)

Parameters

  • Playing — b
If emitted with argument TRUE, this means that the connection manager wishes to set the stream playing; this means that the streaming implementation should expect to receive data. If emitted with argument FALSE this signal is basically meaningless and should be ignored.
Rationale:
We're very sorry.
(Permalink)

SetStreamSending (b: Sending)

Parameters

  • Sending — b
Signal emitted when the connection manager wishes to set whether or not the stream sends to the remote end.
(Permalink)

StartTelephonyEvent (y: Event)

Parameters

  • Event — y (DTMF_Event)
    • A telephony event code.
Request that a telephony event (as defined by RFC 4733) is transmitted over this stream until StopTelephonyEvent is called.
(Permalink)

StartNamedTelephonyEvent (y: Event, u: Codec_ID)

Added in 0.21.2.

Parameters

  • Event — y (DTMF_Event)
    • A telephony event code as defined by RFC 4733.
  • Codec_ID — u
    • The payload type to use when sending events. The value 0xFFFFFFFF means to send with the already configured event type instead of using the specified one.
Request that a telephony event (as defined by RFC 4733) is transmitted over this stream until StopTelephonyEvent is called. This differs from StartTelephonyEvent in that you force the event to be transmitted as a RFC 4733 named event, not as sound. You can also force a specific Codec ID.
(Permalink)

StartSoundTelephonyEvent (y: Event)

Added in 0.21.2.

Parameters

  • Event — y (DTMF_Event)
    • A telephony event code as defined by RFC 4733.
Request that a telephony event (as defined by RFC 4733) is transmitted over this stream until StopTelephonyEvent is called. This differs from StartTelephonyEvent in that you force the event to be transmitted as sound instead of as a named event.
(Permalink)

StopTelephonyEvent ()

Request that any ongoing telephony events (as defined by RFC 4733) being transmitted over this stream are stopped.
(Permalink)

SetStreamHeld (b: Held)

Added in 0.17.3.

Parameters

  • Held — b
    • If true, the stream is to be placed on hold.

Emitted when the connection manager wishes to place the stream on hold (so the streaming client should free hardware or software resources) or take the stream off hold (so the streaming client should reacquire the necessary resources).

When placing a channel's streams on hold, the connection manager SHOULD notify the remote contact that this will be done (if appropriate in the protocol) before it emits this signal.

Rationale:

It is assumed that relinquishing a resource will not fail. If it does, the call is probably doomed anyway.

When unholding a channel's streams, the connection manager SHOULD emit this signal and wait for success to be indicated via HoldState before it notifies the remote contact that the channel has been taken off hold.

Rationale:

This means that if a resource is unavailable, the remote contact will never even be told that we tried to acquire it.

(Permalink)

SetRemoteFeedbackMessages (a{u(ua(sss))}: Messages)

Added in 0.22.1.

Parameters

Signal emitted when the connection manager wishes to inform the client of the feedback messages supported by the remote end. This signal is emitted before SetRemoteCodecs. If the client supports any of these messages, it must call SupportedFeedbackMessages before calling SupportedCodecs.
(Permalink)

SetRemoteHeaderExtensions (a(uuss): Header_Extensions)

Added in 0.22.1.

Parameters

Signal emitted when the connection manager wishes to inform the client of the RTP header extensions supported by the remote end. This signal is emitted before SetRemoteCodecs. If the client supports any of these messages, it must call SupportedHeaderExtensions before calling SupportedCodecs.

Properties

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

STUNServers — a(sq) (Socket_Address_IP_List)

Read only
Added in 0.17.22.
The IP addresses of possible STUN servers to use for NAT traversal, as dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. This property cannot change once the stream has been created, so there is no change notification. The IP addresses MUST NOT be given as DNS hostnames.
Rationale:
High-quality connection managers already need an asynchronous DNS resolver, so they might as well resolve this name to an IP to make life easier for streaming implementations.
(Permalink)

CreatedLocally — b

Read only
Added in 0.17.22.
True if we were the creator of this stream, false otherwise.
Rationale:
This information is needed for some nat traversal mechanisms, such as ICE-UDP, where the creator gets the role of the controlling agent.
(Permalink)

NATTraversal — s

Read only
Added in 0.17.22.

The transport (NAT traversal technique) to be used for this stream. Well-known values include:

none
Raw UDP, with or without STUN, should be used. If the STUNServers property is non-empty, STUN SHOULD be used.
stun
A deprecated synonym for 'none'.
gtalk-p2p
Google Talk peer-to-peer connectivity establishment should be used, as implemented in libjingle 0.3.
ice-udp
Interactive Connectivity Establishment should be used, as defined by the IETF MMUSIC working group.
wlm-8.5
The transport used by Windows Live Messenger 8.5 or later, which resembles ICE draft 6, should be used.
wlm-2009
The transport used by Windows Live Messenger 2009 or later, which resembles ICE draft 19, should be used.

This property cannot change once the stream has been created, so there is no change notification.

(Permalink)

RelayInfo — aa{sv} (String_Variant_Map_List)

Read only

A list of mappings describing TURN or Google relay servers available for the client to use in its candidate gathering, as determined from the protocol. Map keys are:

ip - s
The IP address of the relay server as a dotted-quad IPv4 address literal or an RFC2373 IPv6 address literal. This MUST NOT be a DNS hostname.
Rationale:
High-quality connection managers already need an asynchronous DNS resolver, so they might as well resolve this name to an IP and make life easier for streaming implementations.
type - s

Either udp for UDP (UDP MUST be assumed if this key is omitted), tcp for TCP, or tls.

The precise meaning of this key depends on the NATTraversal property: if NATTraversal is ice-udp, tls means TLS over TCP as referenced by ICE draft 19, and if NATTraversal is gtalk-p2p, tls means a fake SSL session over TCP as implemented by libjingle.

port - q
The UDP or TCP port of the relay server as an ASCII unsigned integer
username - s
The username to use
password - s
The password to use
component - u
The component number to use this relay server for, as an ASCII unsigned integer; if not included, this relay server may be used for any or all components.
Rationale:
In ICE draft 6, as used by Google Talk, credentials are only valid once, so each component needs relaying separately.
Rationale:

An equivalent of the gtalk-p2p-relay-token property on MediaSignalling channels is not included here. The connection manager should be responsible for making the necessary HTTP requests to turn the token into a username and password.

The type of relay server that this represents depends on the value of the NATTraversal property. If NATTraversal is ice-udp, this is a TURN server; if NATTraversal is gtalk-p2p, this is a Google relay server; otherwise, the meaning of RelayInfo is undefined.

If relaying is not possible for this stream, the list is empty.

This property cannot change once the stream has been created, so there is no change notification.

Types

Enum (Permalink)

Media_Stream_Error — u

  • Unknown (0)
    • An unknown error occured.
  • EOS (1)
    • Deprecated since 0.17.27. This error has no use anywhere. In Farsight 1 times, it was used to indicate a GStreamer EOS (when the end of a file is reached). But since this is for live calls, it makes no sense.
    The end of the stream was reached.
  • Codec_Negotiation_Failed (2)
    • Added in 0.17.27.
    There are no common codecs between the local side and the other particpants in the call. The possible codecs are not signalled here: the streaming implementation is assumed to report them in an implementation-dependent way, e.g. Farsight should use GstMissingElement.
  • Connection_Failed (3)
    • Added in 0.17.27.
    A network connection for the Media could not be established or was lost.
  • Network_Error (4)
    • Added in 0.17.27.
    There was an error in the networking stack (other than the connection failure).
  • No_Codecs (5)
    • Added in 0.17.27.
    There are no installed codecs for this media type.
  • Invalid_CM_Behavior (6)
    • Added in 0.17.27.
    The CM is doing something wrong.
  • Media_Error (7)
    • Added in 0.17.27.
    There was an error in the media processing stack.
Enum (Permalink)

Media_Stream_Base_Proto — u

  • UDP (0)
    • UDP (User Datagram Protocol)
  • TCP (1)
    • TCP (Transmission Control Protocol)
Enum (Permalink)

Media_Stream_Transport_Type — u

  • Local (0)
    • A local address
  • Derived (1)
    • An external address derived by a method such as STUN
  • Relay (2)
    • An external stream relay
Mapping (Permalink)

RTCP_Feedback_Message_Map — a{u(ua(sss))}

Added in 0.22.1.
A map of codec and its feedback properties.
  • Codec_Identifier — u
    • Numeric identifier for the codec. This will be used as the PT in the SDP or content description.
  • Properties — (ua(sss)) (RTCP_Feedback_Message_Properties)
    • The RTCP feedback properties for this codec.
Struct (Permalink)

Media_Stream_Handler_Candidate — (sa(usuussduss))

Struct (Permalink)

Media_Stream_Handler_Transport — (usuussduss)

Struct (Permalink)

Media_Stream_Handler_Codec — (usuuua{ss})

Information about a codec supported by a client or a peer's client.
  • Codec_ID — u
    • The codec's payload identifier, as per RFC 3551 (static or dynamic)
  • Name — s
    • The codec's name
  • Media_Type — u (Media_Stream_Type)
    • Type of stream this codec supports
  • Clock_Rate — u
    • Sampling frequency in Hertz
  • Number_Of_Channels — u
    • Number of supported channels
  • Parameters — a{ss} (String_String_Map)
    • Codec-specific optional parameters
Struct (Permalink)

RTCP_Feedback_Message_Properties — (ua(sss))

Added in 0.22.1.
Changed in 0.23.4. This struct is also used by Call, but in call, the CM should know about RTP profiles, and never use MAXUINT as a default value, because it complicates things unnecessarily.
  • RTCPMinimumInterval — u
    • The minimum interval between two regular RTCP packets in milliseconds for this content. If no special value is desired, one should put MAXUINT (0xFFFFFFFF). Implementors and users of Call's RTCPFeedback should not use the MAXUINT default. Instead, in RTP/AVP, the default should be 5000 (5 seconds). If using the RTP/AVPF profile, it can be set to a lower value, the default being 0.
  • Messages — a(sss) (RTCP_Feedback_Message_List)
    • The RTCP feedback messages for this codec.
Struct (Permalink)

RTCP_Feedback_Message — (sss)

Added in 0.22.1.
A struct defining an RTCP feedback message.
  • Type — s
    • Feedback type, for example "ack", "nack", or "ccm".
  • Subtype — s
    • Feedback subtype, according to the Type, can be an empty string (""), if there is no subtype. For example, generic nack is Type="nack" Subtype="".
  • Parameters — s
    • Feedback parameters as a string. Format is defined in the relevant RFC
Struct (Permalink)

RTP_Header_Extension — (uuss)

Added in 0.22.1.
A struct defining a RTP Header extension
  • ID — u
    • Identifier to be negotiated
  • Direction — u (Media_Stream_Direction)
    • Direction in which the Header Extension is negotiated.
  • URI — s
    • URI defining the extension
  • Parameters — s
    • Feedback parameters as a string. Format is defined in the relevant RFC