TpBaseConnectionManager

TpBaseConnectionManager — base class for TpSvcConnectionManager implementations

Synopsis


#include <telepathy-glib/base-connection-manager.h>


            TpCMParamSpec;
            TpCMProtocolSpec;
            TpBaseConnectionManager;
            TpBaseConnectionManagerClass;
TpBaseConnection* (*TpBaseConnectionManagerNewConnFunc)
                                            (TpBaseConnectionManager *self,
                                             const gchar *proto,
                                             TpIntSet *params_present,
                                             void *parsed_params,
                                             GError **error);
gboolean    tp_base_connection_manager_register
                                            (TpBaseConnectionManager *self);
#define     TP_CM_BUS_NAME_BASE
#define     TP_CM_OBJECT_PATH_BASE

Object Hierarchy


  GObject
   +----TpBaseConnectionManager

Implemented Interfaces

TpBaseConnectionManager implements TpSvcConnectionManager.

Signals


"no-more-connections"
            void        user_function      (TpBaseConnectionManager *arg0,
                                            gpointer                 user_data)      : Run last / Has details

Description

This base class makes it easier to write TpSvcConnectionManager implementations by managing the D-Bus object path and bus name, and maintaining a table of active connections. Subclasses should usually only need to override the members of the class data structure.

Details

TpCMParamSpec

typedef struct {
    const gchar *name;
    const gchar *dtype;
    const GType gtype;
    guint flags;
    const gpointer def;
    const gsize offset;
} TpCMParamSpec;

Structure representing a connection manager parameter, as accepted by RequestConnection.

const gchar *name; Name as passed over D-Bus
const gchar *dtype; D-Bus type signature. We currently support 16- and 32-bit integers (gtype is INT), 16- and 32-bit unsigned integers (gtype is UINT), strings (gtype is STRING) and booleans (gtype is BOOLEAN).
const GType gtype; GLib type, derived from dtype as above
guint flags; Some combination of TP_CONN_MGR_PARAM_FLAG_foo
const gpointer def; Default value, as a (const gchar *) for string parameters, or using GINT_TO_POINTER or GUINT_TO_POINTER for integer parameters
const gsize offset; Offset of the parameter in the opaque data structure. The member at that offset is expected to be a gint, guint, (gchar *) or gboolean, depending on gtype. Alternatively, this may be G_MAXSIZE, which means the parameter is obsolete, and is accepted but ignored.

TpCMProtocolSpec

typedef struct {
    const gchar *name;
    const TpCMParamSpec *parameters;
    void *(*params_new) (void);
    void (*params_free) (void *);
} TpCMProtocolSpec;

Structure representing a connection manager protocol.

const gchar *name; The name which should be passed to RequestConnection for this protocol.
const TpCMParamSpec *parameters; An array of TpCMParamSpec representing the valid parameters for this protocol, terminated by a TpCMParamSpec whose name entry is NULL.
params_new () A function which allocates an opaque data structure to store the parsed parameters for this protocol. The offset fields in the members of the parameters array refer to offsets within this opaque structure.
params_free () A function which deallocates the opaque data structure provided by params_new, including deallocating its data members (currently, only strings) if necessary.

TpBaseConnectionManager

typedef struct _TpBaseConnectionManager TpBaseConnectionManager;

A base class for connection managers. There are no interesting public fields in the instance structure.


TpBaseConnectionManagerClass

typedef struct {
    GObjectClass parent_class;

    const char *cm_dbus_name;
    const TpCMProtocolSpec *protocol_params;
    TpBaseConnectionManagerNewConnFunc new_connection;

    /* FIXME: add some ABI padding here? */

    gpointer priv;
} TpBaseConnectionManagerClass;

The class structure for TpBaseConnectionManager.

GObjectClass parent_class; The parent class
const char *cm_dbus_name; The name of this connection manager, as used to construct D-Bus object paths and bus names. Must contain only letters, digits and underscores, and may not start with a digit. Must be filled in by subclasses in their class_init function.
const TpCMProtocolSpec *protocol_params; An array of TpCMProtocolSpec structures representing the protocols this connection manager supports, terminated by a structure whose name member is NULL.
TpBaseConnectionManagerNewConnFunc new_connection; A TpBaseConnectionManagerNewConnFunc used to construct new connections. Must be filled in by subclasses in their class_init function.
gpointer priv; Pointer to opaque private data.

TpBaseConnectionManagerNewConnFunc ()

TpBaseConnection* (*TpBaseConnectionManagerNewConnFunc)
                                            (TpBaseConnectionManager *self,
                                             const gchar *proto,
                                             TpIntSet *params_present,
                                             void *parsed_params,
                                             GError **error);

A function that will return a new connection according to the parsed parameters; used to implement RequestConnection.

The connection manager base class will register the bus name for the new connection, and place a reference to it in its table of connections until the connection's shutdown process finishes.

self : The connection manager implementation
proto : The protocol name from the D-Bus request
params_present : A set of integers representing the indexes into the array of TpCMParamSpec of those parameters that were present in the request
parsed_params : An opaque data structure as returned by the protocol's params_new function, populated according to the parameter specifications
error : if not NULL, used to indicate the error if NULL is returned
Returns : the new connection object, or NULL on error.

tp_base_connection_manager_register ()

gboolean    tp_base_connection_manager_register
                                            (TpBaseConnectionManager *self);

Register the connection manager with an appropriate object path as determined from its cm_dbus_name, and register the appropriate well-known bus name.

self : The connection manager implementation
Returns : TRUE on success, FALSE (having emitted a warning to stderr) on failure

TP_CM_BUS_NAME_BASE

#define TP_CM_BUS_NAME_BASE    "org.freedesktop.Telepathy.ConnectionManager."

The prefix for a connection manager's bus name, to which the CM's name (e.g. "gabble") should be appended.


TP_CM_OBJECT_PATH_BASE

#define TP_CM_OBJECT_PATH_BASE "/org/freedesktop/Telepathy/ConnectionManager/"

The prefix for a connection manager's object path, to which the CM's name (e.g. "gabble") should be appended.

Signal Details

The "no-more-connections" signal

void        user_function                  (TpBaseConnectionManager *arg0,
                                            gpointer                 user_data)      : Run last / Has details

Emitted when the table of active connections becomes empty. tp_run_connection_manager() uses this to detect when to shut down the connection manager.

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

See Also

TpBaseConnection, TpSvcConnectionManager, run