TpPrototype::StreamedMediaChannel Class Reference
[Connection Management]

#include <TelepathyQt4/Prototype/StreamedMediaChannel.h>

Collaboration diagram for TpPrototype::StreamedMediaChannel:

Collaboration graph
[legend]

List of all members.

Public Slots

void slotSetOutputVolume (uint streamId, uint volume)
void slotMuteInput (uint streamId, bool muteState)
void slotMuteOutput (uint streamId, bool muteState)
void slotSetOutputWindow (uint streamId, uint windowId)
void slotAddPreviewWindow (uint windowId)
void slotRemovePreviewWindow (uint windowId)
void slotShutDown ()

Signals

void signalIncomingChannel (TpPrototype::Contact *contact)
void signalStreamAdded (TpPrototype::StreamedMediaChannel *channel, uint streamId, Telepathy::MediaStreamType streamType)
void signalStreamRemoved (TpPrototype::StreamedMediaChannel *channel, uint streamId)
void signalContactAdded (TpPrototype::StreamedMediaChannel *channel, TpPrototype::Contact *addedContact)
void signalContactRemoved (TpPrototype::StreamedMediaChannel *channel, TpPrototype::Contact *removedContact)
void signalStreamStateChanged (TpPrototype::StreamedMediaChannel *channel, uint streamID, Telepathy::MediaStreamState streamState)
void signalStreamDirectionChanged (TpPrototype::StreamedMediaChannel *channel, uint streamID, uint streamDirection, uint pendingFlags)
void signalStreamError (TpPrototype::StreamedMediaChannel *channel, uint streamID, uint errorCode, const QString &message)
void signalLocalInvitationAccepted (TpPrototype::StreamedMediaChannel *channel)

Public Member Functions

bool isValid () const
 ~StreamedMediaChannel ()
bool acceptIncomingStream ()
bool rejectIncomingStream ()
bool requestChannel (QList< Telepathy::MediaStreamType > types)
bool requestStreams (TpPrototype::Contact *contact, QList< Telepathy::MediaStreamType > types)
bool addContactsToGroup (QList< QPointer< TpPrototype::Contact > > contacts)
bool removeContactsFromGroup (QList< QPointer< TpPrototype::Contact > > contacts)
QList< QPointer
< TpPrototype::Contact > > 
localPendingContacts ()
QList< QPointer
< TpPrototype::Contact > > 
members ()
bool removeStreams (const QList< uint > &streamIds)
Telepathy::MediaStreamInfoList requestStreams (QList< Telepathy::MediaStreamType > types)
Telepathy::MediaStreamInfoList listStreams ()

Protected Slots

void slotStreamAdded (uint streamID, uint contactHandle, uint streamType)
void slotStreamDirectionChanged (uint streamID, uint streamDirection, uint pendingFlags)
void slotStreamError (uint streamID, uint errorCode, const QString &message)
void slotStreamRemoved (uint streamID)
void slotStreamStateChanged (uint streamID, uint streamState)
void slotMembersChanged (const QString &message, const Telepathy::UIntList &added, const Telepathy::UIntList &removed, const Telepathy::UIntList &localPending, const Telepathy::UIntList &remotePending, uint actor, uint reason)

Protected Member Functions

 StreamedMediaChannel (Contact *contact, Telepathy::Client::ConnectionInterface *connectionInterface, QObject *parent=NULL)
void requestStreamedMediaChannel (uint handle)
void openStreamedMediaChannel (uint handle, uint handleType, const QString &channelPath, const QString &channelType)
void connectSignals ()
bool addMembers (QList< uint > handles)
bool removeMembers (QList< uint > handles)

Friends

class ContactManager
class Contact


Detailed Description

StreamedMedia Channel for VoIP and Video Over IP. The StreamedMedia channel object provides a simple API to manage the signalling of streamed media. The real encoding/decoding of the data is done by the telepathy stream engine. New/incoming channels are handed over to this stream engine internally.
The channel contains multiple streams each representing its own media (video, audio, ..) and provides its own group channel which can be used for conferences.

Important:
This implementation currently just supports the telepathy stream engine as backend (see http://telepathy.freedesktop.org/wiki/Streamed_Media).

Example opening a VoIP communication to a contact:
A valid streamed media channel object is provided by the remote contact object:
 TpPrototype::StreamedMediaChannel* media_channel = contact->streamedMediaChannel();
 if ( !media_channel )
 { return; }
Request a channel (in this case an audio channel):
 media_channel->requestChannel( QList<Telepathy::MediaStreamType>() << Telepathy::MediaStreamTypeAudio );
Whether the call was accepted or rejected is signalled by the following signals:
 connect( media_channel, SIGNAL( signalContactAdded( TpPrototype::Contact* ) ),
         this, SLOT( slotStreamContactAdded(  TpPrototype::Contact* ) ) );
 connect( media_channel, SIGNAL( signalContactRemoved( TpPrototype::Contact* ) ),
         this, SLOT( slotStreamContactRemoved( TpPrototype::Contact* ) ) );
Example receiving a VoIP communication from a contact:
First you have to be informed about incoming calls. The ContactManager provides the signal:
 connect( m_pContactManager, SIGNAL( signalStreamedMediaChannelOpenedForContact( TpPrototype::Contact* ) ),
          this, SLOT( slotStreamedMediaChannelOpenedForContact( TpPrototype::Contact* ) ) );
Then you have to accept or reject the incoming call:
 TpPrototype::StreamedMediaChannel* streamed_channel = contact->streamedMediaChannel();
 streamed_channel->acceptIncomingStream();
or
 streamed_channel->rejectIncomingStream();
Hint:
Before using this class set the capabilities with CapabilitiesManager::setCapabilities() according your requirements!
See also:
CapabiltiesManager

ChatChannel


Constructor & Destructor Documentation

StreamedMediaChannel::~StreamedMediaChannel (  ) 

Destructor. Deleting this object forces to drop all channels.

StreamedMediaChannel::StreamedMediaChannel ( Contact contact,
Telepathy::Client::ConnectionInterface connectionInterface,
QObject *  parent = NULL 
) [protected]

Constructor. Use Contact::streamedMediaChannel() to obtain an object of StreamedMediaChannel.

References TpPrototype::registerTypes().


Member Function Documentation

bool StreamedMediaChannel::acceptIncomingStream (  ) 

Accept the incoming media stream (call). This function must be called to accept the incoming media stream.

Returns:
Returns true if command was successful.

References addMembers().

bool StreamedMediaChannel::addContactsToGroup ( QList< QPointer< TpPrototype::Contact > >  contacts  ) 

Add contacts to the group. Multiple contacts may sharing the same stream. Use this function to invite a contact to this group. The contact will be added to the group after he accepted the invitation.

Returns:
Returns true if command was successful.

References addMembers().

bool StreamedMediaChannel::addMembers ( QList< uint >  handles  )  [protected]

Add members to interal group channel

Referenced by acceptIncomingStream(), and addContactsToGroup().

void StreamedMediaChannel::connectSignals (  )  [protected]

bool StreamedMediaChannel::isValid (  )  const

Validity check. Do not access any functions if this account is invalid.

Telepathy::MediaStreamInfoList StreamedMediaChannel::listStreams (  ) 

Begins a call to the D-Bus method "ListStreams" on the remote object.

Returns an array of structs representing the streams currently active within this channel. Each stream is identified by an unsigned integer which is unique for each stream within the channel.

Returns:
An array of structs containing:
  • the stream identifier
  • the contact handle who the stream is with (or 0 if the stream represents more than a single member)
  • the type of the stream
  • the current stream state
  • the current direction of the stream
  • the current pending send flags
The returned list is empty if an error occured.

QList< QPointer< TpPrototype::Contact > > StreamedMediaChannel::localPendingContacts (  ) 

Returns a list of contacts that are waiting locally for accaptance. A Contact that is local pending has requested membership of the channel, but the local user of the framework must accept their request before they may join.

Returns:
Returns the list of contacts that are waiting for acceptance.

References Telepathy::LocalPendingInfo::actor, Telepathy::LocalPendingInfo::message, Telepathy::LocalPendingInfo::reason, and Telepathy::LocalPendingInfo::toBeAdded.

QList< QPointer< TpPrototype::Contact > > StreamedMediaChannel::members (  ) 

Returns the list of members in the group. The StreamedMediaChannel contains a group of members that currently part of the group.

Returns:
Returns the list of contacts that are currently group members.

void StreamedMediaChannel::openStreamedMediaChannel ( uint  handle,
uint  handleType,
const QString &  channelPath,
const QString &  channelType 
) [protected]

bool StreamedMediaChannel::rejectIncomingStream (  ) 

Reject the incoming media stream (call). This function should be called if an incoming call should be rejected.

Returns:
Returns true if command was successful.

References removeMembers().

bool StreamedMediaChannel::removeContactsFromGroup ( QList< QPointer< TpPrototype::Contact > >  contacts  ) 

Remove contacts from the group. Multiple contacts may sharing the same stream. Use this function to remove a contact from this group.

Returns:
Returns true if command was successful.

References removeMembers().

bool StreamedMediaChannel::removeMembers ( QList< uint >  handles  )  [protected]

Remove members from interal group channel

Referenced by rejectIncomingStream(), and removeContactsFromGroup().

bool StreamedMediaChannel::removeStreams ( const QList< uint > &  streamIds  ) 

Remove streams. Use this function if a certain stream in a channel should be removed. This might be necessary if a video stream should be canceled without terminating the audio channel.

bool StreamedMediaChannel::requestChannel ( QList< Telepathy::MediaStreamType types  ) 

Request outgoing media channel (call). Ask remote contact to start a media channel.

Todo:
Describe what happens after this call ..
Parameters:
types The stream types that should be opened for this channel
Returns:
Returns true if request call was successful.

References connectSignals(), Telepathy::HandleTypeContact, and Telepathy::Client::ChannelTypeStreamedMediaInterface::staticInterfaceName().

void StreamedMediaChannel::requestStreamedMediaChannel ( uint  handle  )  [protected]

Request a new streamed media channel. This functions needs to be called if a new streamed media channel D-BUS object should be established.

References connectSignals(), and Telepathy::HandleTypeContact.

Telepathy::MediaStreamInfoList StreamedMediaChannel::requestStreams ( QList< Telepathy::MediaStreamType types  ) 

Request streams for the current channel.

Request that streams be established to exchange the given types of media with the given member. In general this will try and establish a bidirectional stream, but on some protocols it may not be possible to indicate to the peer that you would like to receive media, so a send-only stream will be created initially. In the cases where the stream requires remote agreement (eg you wish to receive media from them), the StreamDirectionChanged signal will be emitted with the MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied.

Parameters:
types An array of stream types (values of MediaStreamType)
Returns:
An array of structs (in the same order as the given stream types) containing:
  • the stream identifier
  • the contact handle who the stream is with (or 0 if the stream represents more than a single member)
  • the type of the stream
  • the current stream state
  • the current direction of the stream
  • the current pending send flags
The returned list is empty if an error occured.

bool StreamedMediaChannel::requestStreams ( TpPrototype::Contact contact,
QList< Telepathy::MediaStreamType types 
)

void TpPrototype::StreamedMediaChannel::signalContactAdded ( TpPrototype::StreamedMediaChannel channel,
TpPrototype::Contact addedContact 
) [signal]

A remote contact was added to the group. This signal has different meaning with regard to the context:

  • Outgoing call: The remote contact accapted the call. addedContact contains the remote contact in this case.
Parameters:
addedContact The contact that was removed from the group.
Todo:
: Are there any additional situations?

Referenced by slotMembersChanged().

void TpPrototype::StreamedMediaChannel::signalContactRemoved ( TpPrototype::StreamedMediaChannel channel,
TpPrototype::Contact removedContact 
) [signal]

A contact was removed from the channel. This signal has different meaning with regard to the context:

  • Ongoing chat: The remote contact disconnected or closed the chat.
  • Initiating chat: The remote contact rejected the incoming call.
  • Group Chat: A contact was removed from the group.
Parameters:
removedContact The contact that was removed from the group.

Referenced by slotMembersChanged().

void TpPrototype::StreamedMediaChannel::signalIncomingChannel ( TpPrototype::Contact contact  )  [signal]

Incoming channel detected. This signal is emitted when a valid incoming channel was detected and all needed interfaces were established successfully. Usually it does not make sense to connect to this signal, because this object might be created or removed without any prior notification. Thus, there is no chance to connect before this signal is emitted.
Use ContactManager::signalStreamedMediaChannelOpenedForContact() instead to get informed about new channels!

Parameters:
contact The contact that contains this StreamedMediaChannel object.
See also:
ContactManager

Referenced by openStreamedMediaChannel().

void TpPrototype::StreamedMediaChannel::signalLocalInvitationAccepted ( TpPrototype::StreamedMediaChannel channel  )  [signal]

Local invitation accepted. This signal is accepted if the local contact was added into the group channel

Referenced by slotMembersChanged().

void TpPrototype::StreamedMediaChannel::signalStreamAdded ( TpPrototype::StreamedMediaChannel channel,
uint  streamId,
Telepathy::MediaStreamType  streamType 
) [signal]

A stream was added. If a new stream was added to this media channel.

Parameters:
channel The channel where the stream was added to.
streamId The id of the stream.
streamType The type of the stream.

Referenced by slotStreamAdded().

void TpPrototype::StreamedMediaChannel::signalStreamDirectionChanged ( TpPrototype::StreamedMediaChannel channel,
uint  streamID,
uint  streamDirection,
uint  pendingFlags 
) [signal]

Emitted when the direction or pending flags of a stream are changed. If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has requested that we begin sending on this stream. RequestStreamDirection should be called to indicate whether or not this change is acceptable.

Parameters:
streamID The stream identifier (as defined in ListStreams)
streamDirection The new stream direction (as defined in listStreams)
pendingFlags The new pending send flags (as defined in listStreams)

Referenced by slotStreamDirectionChanged().

void TpPrototype::StreamedMediaChannel::signalStreamError ( TpPrototype::StreamedMediaChannel channel,
uint  streamID,
uint  errorCode,
const QString &  message 
) [signal]

Stream error. Emitted when a stream encounters an error.

Parameters:
streamID The stream identifier (as defined in ListStreams)
errorCode A stream error number, one of the values of MediaStreamError
message A string describing the error (for debugging purposes only)

Referenced by slotStreamError().

void TpPrototype::StreamedMediaChannel::signalStreamRemoved ( TpPrototype::StreamedMediaChannel channel,
uint  streamId 
) [signal]

Stream was removed. This signal is emmitted when a media stream was removed. This may happen on network errors, if the remote contact rejected/removed a stream or if the established connection was closed.

Parameters:
streamId The id of the stream.

Referenced by slotStreamRemoved().

void TpPrototype::StreamedMediaChannel::signalStreamStateChanged ( TpPrototype::StreamedMediaChannel channel,
uint  streamID,
Telepathy::MediaStreamState  streamState 
) [signal]

A stream changed its state

Parameters:
streamId The ID of the stream as returned by listStreams()
streamState The state as provided by Telepathy::MediaStreamInfo

Referenced by slotStreamStateChanged().

void StreamedMediaChannel::slotAddPreviewWindow ( uint  windowId  )  [slot]

Add a preview window.

Parameters:
windowId The window id of the window that should be used to show the preview image.
See also:
slotRemovePreviewWindow()
Todo:
Tell how to obtain a windowId

void StreamedMediaChannel::slotMembersChanged ( const QString &  message,
const Telepathy::UIntList added,
const Telepathy::UIntList removed,
const Telepathy::UIntList localPending,
const Telepathy::UIntList remotePending,
uint  actor,
uint  reason 
) [protected, slot]

Represents the signal "MembersChanged" on the remote object.

References signalContactAdded(), signalContactRemoved(), and signalLocalInvitationAccepted().

Referenced by openStreamedMediaChannel().

void StreamedMediaChannel::slotMuteInput ( uint  streamId,
bool  muteState 
) [slot]

Mute input.

Parameters:
streamId The id of the stream as emitted by signalStreamAdded()
muteState Muted on true.
Todo:
Check whether it is muted if muteState == true and correct API doc if needed.

void StreamedMediaChannel::slotMuteOutput ( uint  streamId,
bool  muteState 
) [slot]

Mute output.

Parameters:
streamId The id of the stream as emitted by signalStreamAdded()
muteState The volume (range?)
Todo:
Check whether it is muted if muteState == true and correct API doc if needed.

void StreamedMediaChannel::slotRemovePreviewWindow ( uint  windowId  )  [slot]

Remove a preview window.

Parameters:
windowId The window id of the window that was used to show the preview image.
See also:
slotAddPreviewWindow()
Todo:
Tell how to obtain a windowId

void StreamedMediaChannel::slotSetOutputVolume ( uint  streamId,
uint  volume 
) [slot]

Set output volume.

Parameters:
streamId The id of the stream as emitted by signalStreamAdded()
volume The volume (range?)

void StreamedMediaChannel::slotSetOutputWindow ( uint  streamId,
uint  windowId 
) [slot]

Set output Window.

Parameters:
streamId The id of the stream as emitted by signalStreamAdded()
windowId The window id of the window that should be used to embed the output.
Todo:
Tell how to obtain a windowId

void StreamedMediaChannel::slotShutDown (  )  [slot]

Shutdown. Shuts the stream engine down and deletes all internal interfaces.

Todo:
What does this function really does and how to handle this here?

void StreamedMediaChannel::slotStreamAdded ( uint  streamID,
uint  contactHandle,
uint  streamType 
) [protected, slot]

Represents the signal "slotStreamAdded" on the remote object.

References signalStreamAdded().

Referenced by connectSignals().

void StreamedMediaChannel::slotStreamDirectionChanged ( uint  streamID,
uint  streamDirection,
uint  pendingFlags 
) [protected, slot]

Represents the signal "StreamDirectionChanged" on the remote object.

References signalStreamDirectionChanged().

Referenced by connectSignals().

void StreamedMediaChannel::slotStreamError ( uint  streamID,
uint  errorCode,
const QString &  message 
) [protected, slot]

Represents the signal "StreamError" on the remote object.

References signalStreamError().

Referenced by connectSignals().

void StreamedMediaChannel::slotStreamRemoved ( uint  streamID  )  [protected, slot]

Represents the signal "StreamRemoved" on the remote object.

References signalStreamRemoved().

Referenced by connectSignals().

void StreamedMediaChannel::slotStreamStateChanged ( uint  streamID,
uint  streamState 
) [protected, slot]

Represents the signal "StreamStateChanged" on the remote object.

References signalStreamStateChanged().

Referenced by connectSignals().


Friends And Related Function Documentation

friend class Contact [friend]

friend class ContactManager [friend]


Generated on Thu Mar 5 18:52:15 2009 for TelepathyQt4-0.1.1 by  doxygen 1.5.8