## TpChannelFactoryIface

TpChannelFactoryIface — interface for channel allocation/tracking

## Synopsis

    #include <telepathy-glib/channel-factory-iface.h>

    void                (*TpChannelFactoryIfaceForeachImpl) (TpChannelFactoryIface *self,
                                                             TpChannelFunc func,
                                                             gpointer data);
    void                (*TpChannelFactoryIfaceProc)        (TpChannelFactoryIface *self);
    TpChannelFactoryRequestStatus (*TpChannelFactoryIfaceRequestImpl)
                                                            (TpChannelFactoryIface *self,
                                                             const gchar *chan_type,
                                                             TpHandleType handle_type,
                                                             guint handle,
                                                             gpointer request,
                                                             TpChannelIface **ret,
                                                             GError **error);
    enum                TpChannelFactoryRequestStatus;
                        TpChannelFactoryIface;
    struct              TpChannelFactoryIfaceClass;
    void                tp_channel_factory_iface_close_all  (TpChannelFactoryIface *self);
    void                tp_channel_factory_iface_connecting (TpChannelFactoryIface *self);
    void                tp_channel_factory_iface_connected  (TpChannelFactoryIface *self);
    void                tp_channel_factory_iface_disconnected
                                                            (TpChannelFactoryIface *self);
    void                tp_channel_factory_iface_foreach    (TpChannelFactoryIface *self,
                                                             TpChannelFunc func,
                                                             gpointer data);
    TpChannelFactoryRequestStatus tp_channel_factory_iface_request
                                                            (TpChannelFactoryIface *self,
                                                             const gchar *chan_type,
                                                             TpHandleType handle_type,
                                                             guint handle,
                                                             gpointer request,
                                                             TpChannelIface **ret,
                                                             GError **error);
    void                tp_channel_factory_iface_emit_new_channel
                                                            (gpointer instance,
                                                             TpChannelIface *channel,
                                                             gpointer request);
    void                tp_channel_factory_iface_emit_channel_error
                                                            (gpointer instance,
                                                             TpChannelIface *channel,
                                                             GError *error,
                                                             gpointer request);

## Object Hierarchy

      GInterface
       +----TpChannelFactoryIface

## Signals

      "channel-error"                                  : Has Details
      "new-channel"                                    : Has Details

## Description

A channel factory is attached to a connection. It carries out channel requests from the connection, and responds to channel-related events on the underlying network connection (e.g. incoming calls).

Deprecated since version 0.11.7. Use TpChannelManager, a newer interface which can be used to implement modern D-Bus APIs, instead.

## Details

### TpChannelFactoryIfaceForeachImpl ()

    void                (*TpChannelFactoryIfaceForeachImpl) (TpChannelFactoryIface *self,
                                                             TpChannelFunc func,
                                                             gpointer data);

### Warning

`TpChannelFactoryIfaceForeachImpl` is deprecated and should not be used in newly-written code. 0.11.7

Signature of an implementation of foreach, which must call func(channel, data) for each channel managed by this factory.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An object implementing TpChannelFactoryIface
`func` : | A function
`data` : | Arbitrary data to pass to `func` as the second argument

### TpChannelFactoryIfaceProc ()

    void                (*TpChannelFactoryIfaceProc)        (TpChannelFactoryIface *self);

### Warning

`TpChannelFactoryIfaceProc` is deprecated and should not be used in newly-written code. 0.11.7

A virtual method on a channel factory that takes no extra parameters and returns nothing.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An object implementing TpChannelFactoryIface

### TpChannelFactoryIfaceRequestImpl ()

    TpChannelFactoryRequestStatus (*TpChannelFactoryIfaceRequestImpl)
                                                            (TpChannelFactoryIface *self,
                                                             const gchar *chan_type,
                                                             TpHandleType handle_type,
                                                             guint handle,
                                                             gpointer request,
                                                             TpChannelIface **ret,
                                                             GError **error);

### Warning

`TpChannelFactoryIfaceRequestImpl` is deprecated and should not be used in newly-written code. 0.11.7

Signature of an implementation of RequestChannel.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An object implementing TpChannelFactoryIface
`chan_type` : | The channel type, e.g. `TP_IFACE_CHANNEL_TYPE_TEXT`
`handle_type` : | The handle type of the channel's associated handle, or 0 if the channel has no associated handle
`handle` : | The channel's associated handle, of type `handle_type`, or 0 if the channel has no associated handle
`request` : | An opaque data structure representing the channel request; if this request is satisfied by a newly created channel, this structure MUST be included in the new-channel signal if the newly created channel has handle 0, and MAY be included in the signal if the newly created channel has nonzero handle.
`ret` : | Set to the new channel if it is available immediately, as documented in the description of TpChannelFactoryRequestStatus
`error` : | Set to the error if the return is `TP_CHANNEL_FACTORY_REQUEST_STATUS_ERROR`, unset otherwise
Returns : | one of the values of TpChannelFactoryRequestStatus, and behaves as documented for that return value

### enum TpChannelFactoryRequestStatus

    typedef enum {
     /*< skip >*/
      TP_CHANNEL_FACTORY_REQUEST_STATUS_NOT_IMPLEMENTED = 0,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_NOT_AVAILABLE,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_INVALID_HANDLE,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_ERROR,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_CREATED,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_QUEUED,
      TP_CHANNEL_FACTORY_REQUEST_STATUS_EXISTING
    } TpChannelFactoryRequestStatus;

### Warning

`TpChannelFactoryRequestStatus` is deprecated and should not be used in newly-written code. 0.11.7

Indicates the result of a channel request.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`TP_CHANNEL_FACTORY_REQUEST_STATUS_NOT_IMPLEMENTED` | Same as the Telepathy error NotImplemented. The connection will try the next factory in its list; if all return this, the overall result of the request will be NotImplemented. *`ret` and *`error` are not set
`TP_CHANNEL_FACTORY_REQUEST_STATUS_NOT_AVAILABLE` | Same as the Telepathy error NotAvailable. *`ret` and *`error` are not set
`TP_CHANNEL_FACTORY_REQUEST_STATUS_INVALID_HANDLE` | Same as the Telepathy error InvalidHandle. *`ret` and *`error` are not set
`TP_CHANNEL_FACTORY_REQUEST_STATUS_ERROR` | An error other than the above. *`ret` is not set, *`error` is set
`TP_CHANNEL_FACTORY_REQUEST_STATUS_CREATED` | A new channel was created (possibly in response to more than one request). new-channel has already been emitted and *`ret` is set to the new channel.
`TP_CHANNEL_FACTORY_REQUEST_STATUS_QUEUED` | A new channel will be created, or was created but is not ready yet. Either new-channel or channel-error will be emitted later. *`ret` and *`error` are not set.
`TP_CHANNEL_FACTORY_REQUEST_STATUS_EXISTING` | An existing channel satisfies the request: new-channel was not emitted. *`ret` is set to the existing channel.

### TpChannelFactoryIface

    typedef struct _TpChannelFactoryIface TpChannelFactoryIface;

### Warning

`TpChannelFactoryIface` is deprecated and should not be used in newly-written code. 0.11.7

Opaque typedef representing any channel factory implementation.

Deprecated since version 0.11.7. Use TpChannelManager instead.

### struct TpChannelFactoryIfaceClass

    struct TpChannelFactoryIfaceClass {
      GTypeInterface parent_class;

      TpChannelFactoryIfaceProc close_all;
      TpChannelFactoryIfaceProc connecting;
      TpChannelFactoryIfaceProc connected;
      TpChannelFactoryIfaceProc disconnected;
      TpChannelFactoryIfaceForeachImpl foreach;
      TpChannelFactoryIfaceRequestImpl request;
    };

### Warning

`TpChannelFactoryIfaceClass` is deprecated and should not be used in newly-written code. 0.11.7

The class structure and vtable for a channel factory implementation.

Deprecated since version 0.11.7. Use TpChannelManager instead.

GTypeInterface `parent_class`; | Fields shared with GTypeInterface
TpChannelFactoryIfaceProc `close_all`; | Close all channels and shut down the channel factory. It is not expected to be usable afterwards. This is called when the connection goes to disconnected state, before emitting the StatusChanged signal or calling `disconnected()`. Must be filled in by implementations.
TpChannelFactoryIfaceProc `connecting`; | Called just after the connection goes from disconnected to connecting state. May be NULL if nothing special needs to happen.
TpChannelFactoryIfaceProc `connected`; | Called just after the connection goes from connecting to connected state. May be NULL if nothing special needs to happen.
TpChannelFactoryIfaceProc `disconnected`; | Called just after the connection goes to disconnected state. This is always called after `close_all`. May be NULL if nothing special needs to happen.
TpChannelFactoryIfaceForeachImpl `foreach`; | Call func(channel, data) for each channel managed by this factory. Must be filled in by implementations.
TpChannelFactoryIfaceRequestImpl `request`; | Respond to a request for a channel. Must be filled in by implementations. See TpChannelFactoryIfaceRequestImpl for details.

### tp_channel_factory_iface_close_all ()

    void                tp_channel_factory_iface_close_all  (TpChannelFactoryIface *self);

### Warning

`tp_channel_factory_iface_close_all` is deprecated and should not be used in newly-written code. 0.11.7

Close all channels and shut down the channel factory. It is not expected to be usable afterwards. This is called when the connection goes to disconnected state, before either emitting the StatusChanged signal or calling `disconnected()`.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An object implementing TpChannelFactoryIface

### tp_channel_factory_iface_connecting ()

    void                tp_channel_factory_iface_connecting (TpChannelFactoryIface *self);

### Warning

`tp_channel_factory_iface_connecting` is deprecated and should not be used in newly-written code. 0.11.7

Indicate that the connection has gone from disconnected to connecting state.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An implementation of the channel factory interface

### tp_channel_factory_iface_connected ()

    void                tp_channel_factory_iface_connected  (TpChannelFactoryIface *self);

### Warning

`tp_channel_factory_iface_connected` is deprecated and should not be used in newly-written code. 0.11.7

Indicate that the connection has gone from connecting to connected state.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An implementation of the channel factory interface

### tp_channel_factory_iface_disconnected ()

    void                tp_channel_factory_iface_disconnected
                                                            (TpChannelFactoryIface *self);

### Warning

`tp_channel_factory_iface_disconnected` is deprecated and should not be used in newly-written code. 0.11.7

Indicate that the connection has become disconnected.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An implementation of the channel factory interface

### tp_channel_factory_iface_foreach ()

    void                tp_channel_factory_iface_foreach    (TpChannelFactoryIface *self,
                                                             TpChannelFunc func,
                                                             gpointer data);

### Warning

`tp_channel_factory_iface_foreach` is deprecated and should not be used in newly-written code. 0.11.7

Call func(channel, data) for each channel managed by this factory.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An implementation of the channel factory interface
`func` : | A callback to be called once per channel
`data` : | Extra data to be passed to `func`

### tp_channel_factory_iface_request ()

    TpChannelFactoryRequestStatus tp_channel_factory_iface_request
                                                            (TpChannelFactoryIface *self,
                                                             const gchar *chan_type,
                                                             TpHandleType handle_type,
                                                             guint handle,
                                                             gpointer request,
                                                             TpChannelIface **ret,
                                                             GError **error);

### Warning

`tp_channel_factory_iface_request` is deprecated and should not be used in newly-written code. 0.11.7

Request a channel.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`self` : | An object implementing TpChannelFactoryIface
`chan_type` : | The channel type, e.g. `TP_IFACE_CHANNEL_TYPE_TEXT`
`handle_type` : | The handle type of the channel's associated handle, or 0 if the channel has no associated handle
`handle` : | The channel's associated handle, of type `handle_type`, or 0 if the channel has no associated handle
`request` : | An opaque data structure representing the channel request; if this request is satisfied by a newly created channel, this structure MUST be included in the new-channel signal if the newly created channel has handle 0, and MAY be included in the signal if the newly created channel has nonzero handle.
`ret` : | Set to the new channel if it is available immediately, as documented in the description of TpChannelFactoryRequestStatus
`error` : | Set to the error if the return is `TP_CHANNEL_FACTORY_REQUEST_STATUS_ERROR`, unset otherwise
Returns : | one of the values of TpChannelFactoryRequestStatus, and behaves as documented for that return value

### tp_channel_factory_iface_emit_new_channel ()

    void                tp_channel_factory_iface_emit_new_channel
                                                            (gpointer instance,
                                                             TpChannelIface *channel,
                                                             gpointer request);

### Warning

`tp_channel_factory_iface_emit_new_channel` is deprecated and should not be used in newly-written code. 0.11.7

Signal that a new channel has been created (new-channel signal).

If the channel was created in response to a channel request, the request was for a nonzero handle type, and the channel has zero handle type, request will be the request context passed to `tp_channel_factory_iface_request()`.

Otherwise, request may either be `NULL` or a request that led to the channel's creation; callers are expected to determine which channels satisfy which requests based on the handle and handle-type.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`instance` : | An object implementing TpChannelFactoryIface
`channel` : | The new channel
`request` : | A request context as passed to `tp_channel_factory_iface_request()`, or `NULL`

### tp_channel_factory_iface_emit_channel_error ()

    void                tp_channel_factory_iface_emit_channel_error
                                                            (gpointer instance,
                                                             TpChannelIface *channel,
                                                             GError *error,
                                                             gpointer request);

### Warning

`tp_channel_factory_iface_emit_channel_error` is deprecated and should not be used in newly-written code. 0.11.7

Signal that a new channel was created, but an error occurred before it could become useful.

request is as for `tp_channel_factory_iface_emit_new_channel()`.

Deprecated since version 0.11.7. Use TpChannelManager instead.

`instance` : | An object implementing TpChannelFactoryIface
`channel` : | The new channel
`error` : | The error that made the channel request fail
`request` : | A request context as passed to `tp_channel_factory_iface_request()`, or `NULL`

## Signal Details

### The `"channel-error"` signal

    void                user_function                      (TpChannelFactoryIface *self,
                                                            GObject               *channel,
                                                            gpointer               error,
                                                            gpointer               request_context,
                                                            gpointer               user_data)            : Has Details

Emitted when a new channel has been created, but an error occurred before it could become useful.

`request` is the same as for "new-channel".

`self` : | an object implementing TpChannelFactoryIface
`channel` : | an object implementing TpChannelIface
`error` : | the GError that made the channel request fail
`request_context` : | a request context as passed to `tp_channel_factory_iface_request()`, or `NULL`
`user_data` : | user data set when the signal handler was connected.

### The `"new-channel"` signal

    void                user_function                      (TpChannelFactoryIface *self,
                                                            GObject               *channel,
                                                            gpointer               request_context,
                                                            gpointer               user_data)            : Has Details

Emitted when a new channel has been created.

If the `channel` was created in response to a channel request, the request was for a nonzero handle type, and the channel has zero handle type, `request_context` will be the request context passed to `tp_channel_factory_iface_request()`.

Otherwise, request may either be `NULL` or a request that led to `channel`'s creation; callers are expected to determine which channels satisfy which requests based on the handle and handle-type.

`self` : | an object implementing TpChannelFactoryIface
`channel` : | a new channel (an object implementing TpChannelIface)
`request_context` : | a request context as passed to `tp_channel_factory_iface_request()`, or `NULL`
`user_data` : | user data set when the signal handler was connected.

## See Also

TpSvcConnection, TpChannelManager