TpBaseConnectionManager

## TpBaseConnectionManager TpBaseConnectionManager — base class for TpSvcConnectionManager implementations |

## Synopsis

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

    gboolean            (*TpCMParamFilter)                  (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);
    gboolean            tp_cm_param_filter_string_nonempty  (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);
    gboolean            tp_cm_param_filter_uint_nonzero     (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);
    void                (*TpCMParamSetter)                  (const TpCMParamSpec *paramspec,
                                                             const GValue *value,
                                                             gpointer params);
    void                tp_cm_param_setter_offset           (const TpCMParamSpec *paramspec,
                                                             const GValue *value,
                                                             gpointer params);
                        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);

## Object Hierarchy

      GObject
       +----TpBaseConnectionManager

## Implemented Interfaces

TpBaseConnectionManager implements TpSvcConnectionManager.

## Signals

      "no-more-connections"                            : 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

### TpCMParamFilter ()

    gboolean            (*TpCMParamFilter)                  (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);

Signature of a callback used to validate and/or normalize user-provided CM parameter values.

`paramspec` : | The parameter specification. The filter is likely to use name (for the error message if the value is invalid) and filter_data.
`value` : | The value for that parameter provided by the user. May be changed to contain a different value of the same type, if some sort of normalization is required
`error` : | Used to raise `TP_ERROR_INVALID_ARGUMENT` if the given value is rejected
Returns : | `TRUE` to accept, `FALSE` (with `error` set) to reject

### tp_cm_param_filter_string_nonempty ()

    gboolean            tp_cm_param_filter_string_nonempty  (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);

A TpCMParamFilter which rejects empty strings.

`paramspec` : | The parameter specification for a string parameter
`value` : | A GValue containing a string, which will not be altered
`error` : | Used to return an error if the string is empty
Returns : | `TRUE` to accept, `FALSE` (with `error` set) to reject

### tp_cm_param_filter_uint_nonzero ()

    gboolean            tp_cm_param_filter_uint_nonzero     (const TpCMParamSpec *paramspec,
                                                             GValue *value,
                                                             GError **error);

A TpCMParamFilter which rejects zero, useful for server port numbers.

`paramspec` : | The parameter specification for a guint parameter
`value` : | A GValue containing a guint, which will not be altered
`error` : | Used to return an error if the guint is 0
Returns : | `TRUE` to accept, `FALSE` (with `error` set) to reject

### TpCMParamSetter ()

    void                (*TpCMParamSetter)                  (const TpCMParamSpec *paramspec,
                                                             const GValue *value,
                                                             gpointer params);

The signature of a callback used to set a parameter within the opaque data structure used for a protocol.

`paramspec` : | The parameter specification. The setter is likely to use some combination of the name, offset and setter_data fields.
`value` : | The value for that parameter provided by the user.
`params` : | An opaque data structure, created by TpCMProtocolSpec.params_new.

Since 0.7.0

### tp_cm_param_setter_offset ()

    void                tp_cm_param_setter_offset           (const TpCMParamSpec *paramspec,
                                                             const GValue *value,
                                                             gpointer params);

A TpCMParamSetter which sets parameters by dereferencing an offset from `params`. If `paramspec->offset` is G_MAXSIZE, the parameter is deemed obsolete, and is accepted but ignored.

`paramspec` : | A parameter specification with offset set to some meaningful value.
`value` : | The value for that parameter, either provided by the user or constructed from the parameter's default.
`params` : | An opaque data structure such that the address at (`params` + `paramspec->offset`) is a valid pointer to a variable of the appropriate type.

Since 0.7.0

### TpCMParamSpec

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

        TpCMParamFilter filter;
        gconstpointer filter_data;

        gconstpointer setter_data;
    } TpCMParamSpec;

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

In addition to the fields documented here, there is one gpointer field which must currently be `NULL`. A meaning may be defined for it in a future version of telepathy-glib.

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).
GType `gtype`; | GLib type, derived from `dtype` as above
guint `flags`; | Some combination of TP_CONN_MGR_PARAM_FLAG_foo
gconstpointer `def`; | Default value, as a (const gchar *) for string parameters, or using GINT_TO_POINTER or GUINT_TO_POINTER for integer parameters
gsize `offset`; | Offset of the parameter in the opaque data structure, if appropriate. The member at that offset is expected to be a gint, guint, (gchar *) or gboolean, depending on `gtype`. The default parameter setter, tp_cm_param_setter_offset, uses this field.
TpCMParamFilter `filter`; | A callback which is used to validate or normalize the user-provided value before it is written into the opaque data structure
gconstpointer `filter_data`; | Arbitrary opaque data intended for use by the filter function
gconstpointer `setter_data`; | Arbitrary opaque data intended for use by the setter function instead of or in addition to `offset`.

### TpCMProtocolSpec

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

Structure representing a connection manager protocol.

In addition to the fields documented here, there are three gpointer fields which must currently be `NULL`. A meaning may be defined for these in a future version of telepathy-glib.

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.
TpCMParamSetter `set_param`; | A function which sets a parameter within the opaque data structure provided by params_new. If `NULL`, `tp_cm_param_setter_offset()` will be used. (New in 0.7.0 - previously, code equivalent to `tp_cm_param_setter_offset()` was always used.)

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

The class structure for TpBaseConnectionManager.

In addition to the fields documented here, there are four gpointer fields which must currently be `NULL` (a meaning may be defined for these in a future version of telepathy-glib), and a pointer to opaque private data.

Changed in 0.7.1: it is a fatal error for `cm_dbus_name` not to conform to the specification.

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.

### 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

## 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