## TfChannel

TfChannel — Handle the MediaSignalling interface on a Channel

## Synopsis

                        TfChannel;
                        TfChannelClass;
    TfChannel*          tf_channel_new                      (TpChannel *channel_proxy);
    void                tf_channel_error                    (TfChannel *chan,
                                                             TpMediaStreamError error,
                                                             const gchar *message);
    TfStream*           tf_channel_lookup_stream            (TfChannel *chan,
                                                             guint stream_id);
    void                (*TfChannelStreamFunc)              (TfChannel *chan,
                                                             guint stream_id,
                                                             TfStream *stream,
                                                             gpointer user_data);
    void                tf_channel_foreach_stream           (TfChannel *chan,
                                                             TfChannelStreamFunc func,
                                                             gpointer user_data);
    gboolean            tf_channel_bus_message              (TfChannel *channel,
                                                             GstMessage *message);

## Object Hierarchy

      GObject
       +----TfChannel

## Properties

      "channel"                  TpChannel*            : Read / Write / Construct Only
      "object-path"              gchar*                : Read

## Signals

      "closed"                                         : Run Last
      "handler-result"                                 : Run Last
      "session-created"                                : Run Last
      "session-invalidated"                            : Run Last
      "stream-created"                                 : Run Last
      "stream-get-codec-config"                        : Run Last / Has Details

## Description

This class handles the org.freedesktop.Telepathy.Channel.Interface.MediaSignalling on a channel using Farsight2.

## Details

### TfChannel

    typedef struct _TfChannel TfChannel;

All members of the object are private

### TfChannelClass

    typedef struct {
      GObjectClass parent_class;
    } TfChannelClass;

There are no overridable functions

GObjectClass `parent_class`; | the parent GObjecClass

### tf_channel_new ()

    TfChannel*          tf_channel_new                      (TpChannel *channel_proxy);

Creates a new TfChannel from an existing channel proxy

`channel_proxy` : | a TpChannel proxy
Returns : | a new TfChannel

### tf_channel_error ()

    void                tf_channel_error                    (TfChannel *chan,
                                                             TpMediaStreamError error,
                                                             const gchar *message);

Stops the channel and all stream related to it and sends an error to the connection manager.

`chan` : | a TfChannel
`error` : | the error number of type TpMediaStreamError
`message` : | the error message

### tf_channel_lookup_stream ()

    TfStream*           tf_channel_lookup_stream            (TfChannel *chan,
                                                             guint stream_id);

Finds the stream with the specified id if it exists.

`chan` : | a TfChannel
`stream_id` : | the stream id to look for
Returns : | a TfStream or `NULL`

### TfChannelStreamFunc ()

    void                (*TfChannelStreamFunc)              (TfChannel *chan,
                                                             guint stream_id,
                                                             TfStream *stream,
                                                             gpointer user_data);

Callback function called on every stream by `tf_channel_foreach_stream()`

`chan` : | The TpMediaChannel
`stream_id` : | the id of the stream
`stream` : | the TfStream
`user_data` : | the passed user data

### tf_channel_foreach_stream ()

    void                tf_channel_foreach_stream           (TfChannel *chan,
                                                             TfChannelStreamFunc func,
                                                             gpointer user_data);

Calls the function func on every stream inside this channel.

`chan` : | a TfChannel
`func` : | the function to call on every stream in this channel
`user_data` : | data that will be passed to the function

### tf_channel_bus_message ()

    gboolean            tf_channel_bus_message              (TfChannel *channel,
                                                             GstMessage *message);

You must call this function on call messages received on the async bus. GstMessages are not modified.

`channel` : | A TfChannel
`message` : | A GstMessage received from the bus
Returns : | `TRUE` if the message has been handled, `FALSE` otherwise

## Property Details

### The `"channel"` property

      "channel"                  TpChannel*            : Read / Write / Construct Only

Telepathy channel object which this media channel should operate on.

### The `"object-path"` property

      "object-path"              gchar*                : Read

D-Bus object path of the Telepathy channel which this channel operates on.

Default value: NULL

## Signal Details

### The `"closed"` signal

    void                user_function                      (TfChannel *arg0,
                                                            gpointer   user_data)      : Run Last

This function is called after a channel is closed, either because it has been closed by the connection manager or because we had a locally generated error.

`user_data` : | user data set when the signal handler was connected.

### The `"handler-result"` signal

    void                user_function                      (TfChannel *error,
                                                            gpointer   arg1,
                                                            gpointer   user_data)      : Run Last

This message is emitted when we are ready to handle the channel with `NULL` or with an GError if we can not handle the channel.

`error` : | a GError containing the error or `NULL` if there was no error
`user_data` : | user data set when the signal handler was connected.

### The `"session-created"` signal

    void                user_function                      (TfChannel     *tfchannel,
                                                            FsConference  *conference,
                                                            FsParticipant *participant,
                                                            gpointer       user_data)        : Run Last

This signal is emitted when a new session has been created in the connection manager. The user should add the new FsConference to a pipeline and set it to playing. The user should also set any property he wants to set.

`tfchannel` : | the TfChannel which has a new stream
`conference` : | the FsConference of the new session
`participant` : | the FsParticipant of the new session
`user_data` : | user data set when the signal handler was connected.

### The `"session-invalidated"` signal

    void                user_function                      (TfChannel     *tfchannel,
                                                            FsConference  *conference,
                                                            FsParticipant *participant,
                                                            gpointer       user_data)        : Run Last

This signal is emitted when a session has been invalidated. The FsConference and FsParticipant for this session are returned. The FsConference should be removed from the pipeline.

`tfchannel` : | the TfChannel which has a new stream
`conference` : | the FsConference of the new session
`participant` : | the FsParticipant of the new session
`user_data` : | user data set when the signal handler was connected.

### The `"stream-created"` signal

    void                user_function                      (TfChannel *tfchannel,
                                                            TfStream  *stream,
                                                            gpointer   user_data)      : Run Last

This signal is emitted when a new stream has been created in the connection manager and a local proxy has been generated.

`tfchannel` : | the TfChannel which has a new stream
`stream` : | The new TfStream
`user_data` : | user data set when the signal handler was connected.

### The `"stream-get-codec-config"` signal

    FsCodecGList*       user_function                      (TfChannel *tfchannel,
                                                            guint      stream_id,
                                                            guint      media_type,
                                                            guint      direction,
                                                            gpointer   user_data)       : Run Last / Has Details

This is emitted when a new stream is created and allows the caller to specify his codec preferences.

`tfchannel` : | the TfChannel
`stream_id` : | The ID of the stream which is requestiing new codec config
`media_type` : | The TpMediaStreamType of the stream
`direction` : | The TpMediaStreamDirection of the stream
`user_data` : | user data set when the signal handler was connected.
Returns : | a GList of FsCodec