## TpChannelManager

TpChannelManager — interface for creating and tracking channels

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

    void                (*TpChannelManagerChannelClassFunc) (TpChannelManager *manager,
                                                             GHashTable *fixed_properties,
                                                             const gchar * const *allowed_properties,
                                                             gpointer user_data);
    void                (*TpChannelManagerForeachChannelClassFunc)
                                                            (TpChannelManager *manager,
                                                             TpChannelManagerChannelClassFunc func,
                                                             gpointer user_data);
    void                (*TpChannelManagerTypeChannelClassFunc)
                                                            (GType type,
                                                             GHashTable *fixed_properties,
                                                             const gchar * const *allowed_properties,
                                                             gpointer user_data);
    void                (*TpChannelManagerTypeForeachChannelClassFunc)
                                                            (GType type,
                                                             TpChannelManagerTypeChannelClassFunc func,
                                                             gpointer user_data);
    void                (*TpChannelManagerForeachChannelFunc)
                                                            (TpChannelManager *manager,
                                                             TpExportableChannelFunc func,
                                                             gpointer user_data);
    gboolean            (*TpChannelManagerRequestFunc)      (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);
                        TpChannelManager;
    struct              TpChannelManagerIface;
    gboolean            tp_channel_manager_asv_has_unknown_properties
                                                            (GHashTable *properties,
                                                             const gchar * const *fixed,
                                                             const gchar * const *allowed,
                                                             GError **error);
    gboolean            tp_channel_manager_create_channel   (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);
    void                tp_channel_manager_emit_channel_closed
                                                            (gpointer instance,
                                                             const gchar *path);
    void                tp_channel_manager_emit_channel_closed_for_object
                                                            (gpointer instance,
                                                             TpExportableChannel *channel);
    void                tp_channel_manager_emit_new_channel (gpointer instance,
                                                             TpExportableChannel *channel,
                                                             GSList *request_tokens);
    void                tp_channel_manager_emit_new_channels
                                                            (gpointer instance,
                                                             GHashTable *channels);
    void                tp_channel_manager_emit_request_already_satisfied
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             TpExportableChannel *channel);
    void                tp_channel_manager_emit_request_failed
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *message);
    void                tp_channel_manager_emit_request_failed_printf
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             ...);
    gboolean            tp_channel_manager_ensure_channel   (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);
    void                tp_channel_manager_foreach_channel  (TpChannelManager *manager,
                                                             TpExportableChannelFunc func,
                                                             gpointer user_data);
    void                tp_channel_manager_foreach_channel_class
                                                            (TpChannelManager *manager,
                                                             TpChannelManagerChannelClassFunc func,
                                                             gpointer user_data);
    void                tp_channel_manager_type_foreach_channel_class
                                                            (GType type,
                                                             TpChannelManagerTypeChannelClassFunc func,
                                                             gpointer user_data);
    gboolean            tp_channel_manager_request_channel  (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);

## Object Hierarchy

      GInterface
       +----TpChannelManager

## Known Implementations

TpChannelManager is implemented by TpBaseContactList and TpSimplePasswordManager.

## Signals

      "channel-closed"                                 : Has Details
      "new-channels"                                   : Has Details
      "request-already-satisfied"                      : Has Details
      "request-failed"                                 : Has Details

## Description

A channel manager is attached to a connection. It carries out channel requests from the connection, and responds to channel-related events on the underlying network connection, for particular classes of channel (for example, incoming and outgoing calls, respectively). It also tracks currently-open channels of the relevant kinds.

The connection has an array of channel managers. In response to a call to CreateChannel or RequestChannel, the channel request is offered to each channel manager in turn, until one accepts the request. In a trivial implementation there might be a single channel manager which handles all requests and all incoming events, but in general, there will be multiple channel managers handling different types of channel.

For example, at the time of writing, Gabble has a roster channel manager which handles contact lists and groups, an IM channel manager which handles one-to-one messaging, a MUC channel manager which handles multi-user chat rooms, the index of chat rooms and MUC tubes, a media channel manager which handles VoIP calls, and a 1-1 tubes channel manager.

## Details

### TpChannelManagerChannelClassFunc ()

    void                (*TpChannelManagerChannelClassFunc) (TpChannelManager *manager,
                                                             GHashTable *fixed_properties,
                                                             const gchar * const *allowed_properties,
                                                             gpointer user_data);

Signature of callbacks which act on each channel class supported by `manager`.

`manager` : | An object implementing TpChannelManager
`fixed_properties` : | A table mapping (const gchar *) property names to GValues, representing the values those properties must take to request channels of a particular class.
`allowed_properties` : | A `NULL`-terminated array of property names which may appear in requests for a particular channel class.
`user_data` : | Arbitrary user-supplied data.

### TpChannelManagerForeachChannelClassFunc ()

    void                (*TpChannelManagerForeachChannelClassFunc)
                                                            (TpChannelManager *manager,
                                                             TpChannelManagerChannelClassFunc func,
                                                             gpointer user_data);

Signature of an implementation of foreach_channel_class, which must call func(manager, fixed, allowed, user_data) for each channel class understood by `manager`.

`manager` : | An object implementing TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the final argument of `func`

### TpChannelManagerTypeChannelClassFunc ()

    void                (*TpChannelManagerTypeChannelClassFunc)
                                                            (GType type,
                                                             GHashTable *fixed_properties,
                                                             const gchar * const *allowed_properties,
                                                             gpointer user_data);

Signature of callbacks which act on each channel class potentially supported by instances of `type`.

`type` : | A type whose instances implement TpChannelManager
`fixed_properties` : | A table mapping (const gchar *) property names to GValues, representing the values those properties must take to request channels of a particular class.
`allowed_properties` : | A `NULL`-terminated array of property names which may appear in requests for a particular channel class.
`user_data` : | Arbitrary user-supplied data.

### TpChannelManagerTypeForeachChannelClassFunc ()

    void                (*TpChannelManagerTypeForeachChannelClassFunc)
                                                            (GType type,
                                                             TpChannelManagerTypeChannelClassFunc func,
                                                             gpointer user_data);

Signature of an implementation of type_foreach_channel_class, which must call func(type, fixed, allowed, user_data) for each channel class potentially understood by instances of `type`.

`type` : | A type whose instances implement TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the final argument of `func`

### TpChannelManagerForeachChannelFunc ()

    void                (*TpChannelManagerForeachChannelFunc)
                                                            (TpChannelManager *manager,
                                                             TpExportableChannelFunc func,
                                                             gpointer user_data);

Signature of an implementation of foreach_channel, which must call func(channel, user_data) for each channel managed by this channel manager.

`manager` : | an object implementing TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the second argument of `func`

### TpChannelManagerRequestFunc ()

    gboolean            (*TpChannelManagerRequestFunc)      (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);

Signature of an implementation of TpChannelManagerIface.create_channel and TpChannelManagerIface.request_channel.

Implementations should inspect the contents of `request_properties` to see if it matches a channel class handled by this manager. If so, they should return `TRUE` to accept responsibility for the request, and ultimately emit exactly one of the "new-channels", "request-already-satisfied" and "request-failed" signals (including `request_token` in the appropriate argument).

If the implementation does not want to handle the request, it should return `FALSE` to allow the request to be offered to another channel manager.

Implementations may assume the following of `request_properties`:

- the ChannelType property is present, and is a (const gchar *)
- the TargetHandleType property is a valid TpHandleType, if present
- if TargetHandleType is None, TargetHandle is omitted
- if TargetHandleType is not None, TargetHandle is a valid TpHandle of that TpHandleType

Changed in version 0.15.5: Previously the TargetID property was guaranteed to be missing from `request_properties`. Now it is always present, whether it was in the original channel request or not.

`manager` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing this pending request.
`request_properties` : | A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client. The hash table will be freed after the function returns; if the channel manager wants to keep it around, it must copy it.
Returns : | `TRUE` if `manager` will handle this request, else `FALSE`.

### TpChannelManager

    typedef struct _TpChannelManager TpChannelManager;

Opaque typedef representing any channel manager implementation.

### struct TpChannelManagerIface

    struct TpChannelManagerIface {
        GTypeInterface parent;

        TpChannelManagerForeachChannelFunc foreach_channel;

        TpChannelManagerForeachChannelClassFunc foreach_channel_class;

        TpChannelManagerRequestFunc create_channel;
        TpChannelManagerRequestFunc request_channel;
        TpChannelManagerRequestFunc ensure_channel;

        TpChannelManagerTypeForeachChannelClassFunc type_foreach_channel_class;
    };

The vtable for a channel manager implementation.

In addition to the fields documented here there are several GCallback fields which must currently be `NULL`.

GTypeInterface `parent`; | Fields shared with GTypeInterface.
TpChannelManagerForeachChannelFunc `foreach_channel`; | Call func(channel, user_data) for each channel managed by this manager. If not implemented, the manager is assumed to manage no channels.
TpChannelManagerForeachChannelClassFunc `foreach_channel_class`; | Call func(manager, fixed, allowed, user_data) for each class of channel that this instance can create (a subset of the channel classes produced by `type_foreach_channel_class`). If not implemented, `type_foreach_channel_class` is used.
TpChannelManagerRequestFunc `create_channel`; | Respond to a request for a new channel made with the Connection.Interface.Requests.CreateChannel method. See TpChannelManagerRequestFunc for details.
TpChannelManagerRequestFunc `request_channel`; | Respond to a request for a (new or existing) channel made with the Connection.RequestChannel method. See TpChannelManagerRequestFunc for details.
TpChannelManagerRequestFunc `ensure_channel`; | Respond to a request for a (new or existing) channel made with the Connection.Interface.Requests.EnsureChannel method. See TpChannelManagerRequestFunc for details. Since: 0.7.16
TpChannelManagerTypeForeachChannelClassFunc `type_foreach_channel_class`; | Call func(cls, fixed, allowed, user_data) for each class of channel that instances of this class might be able to create. Since: 0.11.11

Since 0.7.15

### tp_channel_manager_asv_has_unknown_properties ()

    gboolean            tp_channel_manager_asv_has_unknown_properties
                                                            (GHashTable *properties,
                                                             const gchar * const *fixed,
                                                             const gchar * const *allowed,
                                                             GError **error);

Checks whether the keys of `properties` are elements of one of `fixed` and `allowed`. This is intended to be used by implementations of TpChannelManagerIface.create_channel which have decided to accept a request, to conform with the specification's requirement that unknown requested properties must cause a request to fail, not be silently ignored.

On encountering unknown properties, this function will return `TRUE`, and set `error` to a GError that could be used as a D-Bus method error.

`properties` : | a table mapping (const gchar *) property names to GValues, as passed to methods of TpChannelManager
`fixed` : | a `NULL`-terminated array of property names
`allowed` : | a `NULL`-terminated array of property names
`error` : | an address at which to store an error suitable for returning from the D-Bus method when `properties` contains unknown properties
Returns : | `TRUE` if `properties` contains keys not in either `fixed` or `allowed`; else `FALSE`.

Since 0.7.15

### tp_channel_manager_create_channel ()

    gboolean            tp_channel_manager_create_channel   (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);

Offers an incoming CreateChannel call to `manager`.

`manager` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing this pending request.
`request_properties` : | A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client.
Returns : | `TRUE` if this request will be handled by `manager`; else `FALSE`.

Since 0.7.15

### tp_channel_manager_emit_channel_closed ()

    void                tp_channel_manager_emit_channel_closed
                                                            (gpointer instance,
                                                             const gchar *path);

Emit the "channel-closed" signal indicating that the channel at the given object path has been closed.

`instance` : | An object implementing TpChannelManager
`path` : | A channel's object-path

Since 0.7.15

### tp_channel_manager_emit_channel_closed_for_object ()

    void                tp_channel_manager_emit_channel_closed_for_object
                                                            (gpointer instance,
                                                             TpExportableChannel *channel);

Emit the "channel-closed" signal indicating that the given channel has been closed. (This is a convenient shortcut for calling `tp_channel_manager_emit_channel_closed()` with the "object-path" property of `channel`.)

`instance` : | An object implementing TpChannelManager
`channel` : | A TpExportableChannel

Since 0.7.15

### tp_channel_manager_emit_new_channel ()

    void                tp_channel_manager_emit_new_channel (gpointer instance,
                                                             TpExportableChannel *channel,
                                                             GSList *request_tokens);

Emit the "new-channels" signal indicating that the channel has been created.

`instance` : | An object implementing TpChannelManager
`channel` : | A TpExportableChannel
`request_tokens` : | the request tokens (opaque pointers) satisfied by this channel

Since 0.7.15

### tp_channel_manager_emit_new_channels ()

    void                tp_channel_manager_emit_new_channels
                                                            (gpointer instance,
                                                             GHashTable *channels);

### Warning

`tp_channel_manager_emit_new_channels` is deprecated and should not be used in newly-written code. in 0.19.1 this function should not be used. Signalling the creation of multiple channels together in a single signal is strongly recommended against as it's very complicated, hard to get right in clients, and not nearly as useful as it originally sounded. Use `tp_channel_manager_emit_new_channel()` instead.

If `channels` is non-empty, emit the "new-channels" signal indicating that those channels have been created.

`instance` : | An object implementing TpChannelManager
`channels` : | a GHashTable where the keys are TpExportableChannel instances (hashed and compared by `g_direct_hash()` and `g_direct_equal()`) and the values are linked lists (GSList) of request tokens (opaque pointers) satisfied by these channels

Since 0.7.15

### tp_channel_manager_emit_request_already_satisfied ()

    void                tp_channel_manager_emit_request_already_satisfied
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             TpExportableChannel *channel);

Emit the "request-already-satisfied" signal indicating that the pre-existing channel `channel` satisfies `request_token`.

`instance` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing the request that succeeded
`channel` : | The channel that satisfies the request

Since 0.7.15

### tp_channel_manager_emit_request_failed ()

    void                tp_channel_manager_emit_request_failed
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *message);

Emit the "request-failed" signal indicating that the request `request_token` failed for the given reason.

`instance` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing the request that failed
`domain` : | a GError domain
`code` : | a GError code appropriate for `domain`
`message` : | the error message

Since 0.7.15

### tp_channel_manager_emit_request_failed_printf ()

    void                tp_channel_manager_emit_request_failed_printf
                                                            (gpointer instance,
                                                             gpointer request_token,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             ...);

Emit the "request-failed" signal indicating that the request `request_token` failed for the given reason.

`instance` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing the request that failed
`domain` : | a GError domain
`code` : | a GError code appropriate for `domain`
`format` : | a printf-style format string for the error message
`...` : | arguments for the format string

Since 0.7.15

### tp_channel_manager_ensure_channel ()

    gboolean            tp_channel_manager_ensure_channel   (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);

Offers an incoming EnsureChannel call to `manager`.

`manager` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing this pending request.
`request_properties` : | A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client.
Returns : | `TRUE` if this request will be handled by `manager`; else `FALSE`.

Since 0.7.16

### tp_channel_manager_foreach_channel ()

    void                tp_channel_manager_foreach_channel  (TpChannelManager *manager,
                                                             TpExportableChannelFunc func,
                                                             gpointer user_data);

Calls func(channel, user_data) for each channel managed by `manager`.

`manager` : | an object implementing TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the second argument of `func`

Since 0.7.15

### tp_channel_manager_foreach_channel_class ()

    void                tp_channel_manager_foreach_channel_class
                                                            (TpChannelManager *manager,
                                                             TpChannelManagerChannelClassFunc func,
                                                             gpointer user_data);

Calls func(manager, fixed, allowed, user_data) for each channel class understood by `manager`.

`manager` : | An object implementing TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the final argument of `func`

Since 0.7.15

### tp_channel_manager_type_foreach_channel_class ()

    void                tp_channel_manager_type_foreach_channel_class
                                                            (GType type,
                                                             TpChannelManagerTypeChannelClassFunc func,
                                                             gpointer user_data);

Calls func(type, fixed, allowed, user_data) for each channel class potentially understood by instances of `type`.

`type` : | A type whose instances implement TpChannelManager
`func` : | A function
`user_data` : | Arbitrary data to be passed as the final argument of `func`

Since 0.11.11

### tp_channel_manager_request_channel ()

    gboolean            tp_channel_manager_request_channel  (TpChannelManager *manager,
                                                             gpointer request_token,
                                                             GHashTable *request_properties);

Offers an incoming RequestChannel call to `manager`.

`manager` : | An object implementing TpChannelManager
`request_token` : | An opaque pointer representing this pending request.
`request_properties` : | A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client.
Returns : | `TRUE` if this request will be handled by `manager`; else `FALSE`.

Since 0.7.15

## Signal Details

### The `"channel-closed"` signal

    void                user_function                      (TpChannelManager *self,
                                                            gchar            *path,
                                                            gpointer          user_data)      : Has Details

Emitted when a channel has been closed. The Connection should generally respond to this signal by emitting ChannelClosed.

`self` : | the channel manager
`path` : | the channel's object-path
`user_data` : | user data set when the signal handler was connected.

### The `"new-channels"` signal

    void                user_function                      (TpChannelManager *self,
                                                            gpointer          channels,
                                                            gpointer          user_data)      : Has Details

Emitted when new channels have been created. The Connection should generally emit NewChannels (and NewChannel) in response to this signal, and then return from pending CreateChannel, EnsureChannel and/or RequestChannel calls if appropriate.

Since 0.19.1, clients should not emit more than one channel in this signal at one time as the creation of multiple channels together in a single signal is strongly recommended against: it's very complicated, hard to get right in clients, and not nearly as useful as it originally sounded.

`self` : | the channel manager
`channels` : | a GHashTable where the keys are TpExportableChannel instances (hashed and compared by `g_direct_hash()` and `g_direct_equal()`) and the values are linked lists (GSList) of request tokens (opaque pointers) satisfied by these channels
`user_data` : | user data set when the signal handler was connected.

### The `"request-already-satisfied"` signal

    void                user_function                      (TpChannelManager *self,
                                                            gpointer          request_token,
                                                            GObject          *channel,
                                                            gpointer          user_data)          : Has Details

Emitted when a channel request is satisfied by an existing channel. The Connection should generally respond to this signal by returning success from EnsureChannel or RequestChannel.

`self` : | the channel manager
`request_token` : | opaque pointer supplied by the requester, representing a request
`channel` : | the existing TpExportableChannel that satisfies the request
`user_data` : | user data set when the signal handler was connected.

### The `"request-failed"` signal

    void                user_function                      (TpChannelManager *self,
                                                            gpointer          request_token,
                                                            guint             domain,
                                                            gint              code,
                                                            gchar            *message,
                                                            gpointer          user_data)          : Has Details

Emitted when a channel request has failed. The Connection should generally respond to this signal by returning failure from CreateChannel, EnsureChannel or RequestChannel.

`self` : | the channel manager
`request_token` : | opaque pointer supplied by the requester, representing a request
`domain` : | the domain of a GError indicating why the request failed
`code` : | the error code of a GError indicating why the request failed
`message` : | the string part of a GError indicating why the request failed
`user_data` : | user data set when the signal handler was connected.

## See Also

TpSvcConnection