Requesting StreamedMedia channels

The many ways to request a StreamedMedia channel

Assume that CONTACT handle 123 is the handle of a contact "fred@example.com".

These are in order from newest to oldest mechanism.

CreateChannel or EnsureChannel with Initial{Audio,Video}

This is the newest mechanism. It requires the Requests interface, and the CM including InitialAudio and/or InitialVideo in the Allowed properties for StreamedMedia requests. To start an audio-only call: 

CreateChannel({
    '...ChannelType': '...StreamedMedia',
    'TargetHandleType': CONTACT,
    '...TargetHandle': 123,
    '...Channel.Type.StreamedMedia.InitialAudio': True,
})
# the resulting channel should have TargetHandle = 123 (to represent the fact
# that this is a 1-1 channel with Fred); 123 in remote-pending (to represent
# the fact that we are waiting for Fred to answer); the self handle in members.

To start a video-only call, or an audio+video call, request InitialVideo similarly.

CreateChannel or EnsureChannel

(in Gabble 0.7.13: tests/twisted/jingle/test-outgoing-call-requestotron.py, ...-ensure.py)

This is the second-newest mechanism. It requires the Requests interface. 

CreateChannel({'...ChannelType': '...StreamedMedia', 'TargetHandleType': CONTACT, '...TargetHandle': 123})
# the channel has TargetHandle = 123 (to represent the fact that this is a 1-1 channel with Fred)
# but 123 is not in members or in remote-pending, because we haven't actually sent anything to Fred
# (so Fred is unaware that a call is about to happen)

RequestStreams(handle, [MEDIA_STREAM_TYPE_AUDIO])
# now that we have sent a message to Fred, 123 is in the remote-pending set

or: 

EnsureChannel({ ... the same arguments ... })
# if the channel is ours (EnsureChannel returns Yours = TRUE) then
# the channel has TargetHandle = 123 but 123 is not in members or in remote-pending;

# to make the call we do...
RequestStreams(handle, [MEDIA_STREAM_TYPE_AUDIO])
# now that we have sent a message to Fred, 123 is in the remote-pending set

RequestChannel (handle 0) + RequestStreams

(in Gabble 0.7.13: tests/twisted/jingle/test-outgoing-call.py)

This is what we recommended before Requests was stable. 

RequestChannel('...StreamedMedia', HANDLE_TYPE_NONE, 0, TRUE)
# the channel has TargetHandle = 0 (we don't know who it will be with)
# it must keep this handle forever, because TargetHandle cannot change

RequestStreams(handle, [MEDIA_STREAM_TYPE_AUDIO])
# now that we have sent a message to Fred, 123 is in the remote-pending set

RequestChannel (handle 0) + AddMembers + RequestStreams

(in Gabble 0.7.13: tests/twisted/jingle/test-outgoing-call-deprecated2.py)

Older connection managers required that you do this, so some clients might still use this calling pattern. 

RequestChannel('...StreamedMedia', HANDLE_TYPE_NONE, 0, TRUE)
# the channel has TargetHandle = 0 (we don't know who it will be with)
# it must keep this handle forever, because TargetHandle cannot change

# older connection managers required this call before RequestStreams:
AddMembers([123], '')
# now 123 is in remote-pending, even though we haven't sent Fred any messages
# this is rather stupid, which is why we removed this requirement

RequestStreams(handle, [MEDIA_STREAM_TYPE_AUDIO])
# now we actually send a message to Fred, but this is not indicated by the Group interface :-(

RequestChannel (with a handle)

(in Gabble 0.7.13: tests/twisted/jingle/test-outgoing-call-deprecated.py)

This is the oldest and most deprecated mechanism that we still support. 

RequestChannel('...StreamedMedia', HANDLE_TYPE_CONTACT, 123, TRUE)
# as of Gabble 0.7.x the channel has TargetHandle = 123 (to represent the fact that this is a
# 1-1 channel with Fred). 123 is in remote-pending even though Fred is unaware, because
# backwards compatibility requires this (this mechanism was defined to be equivalent to calling
# AddMembers)

RequestStreams(handle, [MEDIA_STREAM_TYPE_AUDIO])
# now we actually send a message to Fred, but this is not indicated by the Group interface :-(