TpChannelFactoryIface

TpChannelFactoryIface — interface for channel allocation/tracking

Functions

Signals

void channel-error Has Details
void new-channel Has Details

Types and Values

Object Hierarchy

    GInterface
    ╰── TpChannelFactoryIface

Includes

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

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.

Functions

TpChannelFactoryIfaceForeachImpl ()

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

TpChannelFactoryIfaceForeachImpl has been deprecated since version 0.11.7 and should not be used in newly-written code.

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.

Parameters

self

An object implementing TpChannelFactoryIface

 

func

A function

 

data

Arbitrary data to pass to func as the second argument

 

TpChannelFactoryIfaceProc ()

void
(*TpChannelFactoryIfaceProc) (TpChannelFactoryIface *self);

TpChannelFactoryIfaceProc has been deprecated since version 0.11.7 and should not be used in newly-written code.

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

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

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

TpChannelFactoryIfaceRequestImpl has been deprecated since version 0.11.7 and should not be used in newly-written code.

Signature of an implementation of RequestChannel.

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

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

void
tp_channel_factory_iface_close_all (TpChannelFactoryIface *self);

tp_channel_factory_iface_close_all has been deprecated since version 0.11.7 and should not be used in newly-written code.

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.

Parameters

self

An object implementing TpChannelFactoryIface

 

tp_channel_factory_iface_connecting ()

void
tp_channel_factory_iface_connecting (TpChannelFactoryIface *self);

tp_channel_factory_iface_connecting has been deprecated since version 0.11.7 and should not be used in newly-written code.

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

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

self

An implementation of the channel factory interface

 

tp_channel_factory_iface_connected ()

void
tp_channel_factory_iface_connected (TpChannelFactoryIface *self);

tp_channel_factory_iface_connected has been deprecated since version 0.11.7 and should not be used in newly-written code.

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

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

self

An implementation of the channel factory interface

 

tp_channel_factory_iface_disconnected ()

void
tp_channel_factory_iface_disconnected (TpChannelFactoryIface *self);

tp_channel_factory_iface_disconnected has been deprecated since version 0.11.7 and should not be used in newly-written code.

Indicate that the connection has become disconnected.

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

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

tp_channel_factory_iface_foreach has been deprecated since version 0.11.7 and should not be used in newly-written code.

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

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

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

tp_channel_factory_iface_request has been deprecated since version 0.11.7 and should not be used in newly-written code.

Request a channel.

Deprecated since version 0.11.7. Use TpChannelManager instead.

Parameters

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

tp_channel_factory_iface_emit_new_channel has been deprecated since version 0.11.7 and should not be used in newly-written code.

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.

Parameters

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

tp_channel_factory_iface_emit_channel_error has been deprecated since version 0.11.7 and should not be used in newly-written code.

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.

Parameters

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

 

Types and Values

enum TpChannelFactoryRequestStatus

TpChannelFactoryRequestStatus has been deprecated since version 0.11.7 and should not be used in newly-written code.

Indicates the result of a channel request.

Deprecated since version 0.11.7. Use TpChannelManager instead.

Members

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;

TpChannelFactoryIface has been deprecated since version 0.11.7 and should not be used in newly-written code.

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

TpChannelFactoryIfaceClass has been deprecated since version 0.11.7 and should not be used in newly-written code.

The class structure and vtable for a channel factory implementation.

Deprecated since version 0.11.7. Use TpChannelManager instead.

Members

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.

 

Signal Details

The “channel-error” signal

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

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

Parameters

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.

 

Flags: Has Details


The “new-channel” signal

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

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.

Parameters

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.

 

Flags: Has Details

See Also

TpSvcConnection, TpChannelManager