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;
            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);

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).

The connection has an array of channel factories. In a trivial implementation there might be a single channel factory which handles all requests and all incoming events, but in general, there will be multiple channel factories handling different types of channel.

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

Details

TpChannelFactoryIfaceForeachImpl ()

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

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

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

TpChannelFactoryIfaceProc ()

void        (*TpChannelFactoryIfaceProc)    (TpChannelFactoryIface *self);

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

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);

Signature of an implementation of RequestChannel.

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 {
  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;

Indicates the result of a channel request.

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;

Opaque typedef representing any channel factory implementation.


TpChannelFactoryIfaceClass

typedef struct {
  GTypeInterface parent_class;

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

The class structure and vtable for a channel factory implementation.

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);

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().

self : An object implementing TpChannelFactoryIface

tp_channel_factory_iface_connecting ()

void        tp_channel_factory_iface_connecting
                                            (TpChannelFactoryIface *self);

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

self : An implementation of the channel factory interface

tp_channel_factory_iface_connected ()

void        tp_channel_factory_iface_connected
                                            (TpChannelFactoryIface *self);

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

self : An implementation of the channel factory interface

tp_channel_factory_iface_disconnected ()

void        tp_channel_factory_iface_disconnected
                                            (TpChannelFactoryIface *self);

Indicate that the connection has become disconnected.

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);

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

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);

Request a channel.

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);

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.

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);

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.

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

See Also

TpSvcConnection