## TpBaseConnectionManager

TpBaseConnectionManager — base class for TpSvcConnectionManager implementations

## Functions

gboolean | (*TpCMParamFilter) ()
gboolean | tp_cm_param_filter_string_nonempty ()
gboolean | tp_cm_param_filter_uint_nonzero ()
void | (*TpCMParamSetter) ()
void | tp_cm_param_setter_offset ()
TpBaseConnection * | (*TpBaseConnectionManagerNewConnFunc) ()
GPtrArray * | (*TpBaseConnectionManagerGetInterfacesFunc) ()
TpDBusDaemon * | tp_base_connection_manager_get_dbus_daemon ()
gboolean | tp_base_connection_manager_register ()
void | tp_base_connection_manager_add_protocol ()

## Properties

TpDBusDaemon * | dbus-daemon | Read / Write / Construct Only
GStrv | interfaces | Read
GHashTable_gchararray+GHashTable_gchararray+GValue__* | protocols | Read

## Signals

void | no-more-connections | Has Details

## Types and Values

struct | TpCMParamSpec
| TpCMProtocolSpec
struct | TpBaseConnectionManager
struct | TpBaseConnectionManagerClass

## Object Hierarchy

        GObject
        ╰── TpBaseConnectionManager

## Implemented Interfaces

TpBaseConnectionManager implements TpSvcDBusProperties and TpSvcConnectionManager.

## Includes

    #include <telepathy-glib/telepathy-glib.h>

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

### TpBaseConnectionManagerGetInterfacesFunc ()

    GPtrArray *
    (*TpBaseConnectionManagerGetInterfacesFunc)
                                   (TpBaseConnectionManager *self);

Signature of an implementation of TpBaseConnectionManagerClass.get_interfaces virtual function.

Implementation must first chainup on parent class implementation and then add extra interfaces into the GPtrArray.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

    static GPtrArray *
    my_connection_manager_get_interfaces (TpBaseConnectionManager *self)
    {
      GPtrArray *interfaces;

      interfaces = TP_BASE_CONNECTION_MANAGER_CLASS (
          my_connection_manager_parent_class)->get_interfaces (self);

      g_ptr_array_add (interfaces, TP_IFACE_BADGERS);

      return interfaces;
    }

#### Parameters

self | a TpBaseConnectionManager |

#### Returns

a GPtrArray of static strings for D-Bus interfaces implemented by this client.

[transfer container]

Since: 0.19.4

### tp_base_connection_manager_get_dbus_daemon ()

    TpDBusDaemon *
    tp_base_connection_manager_get_dbus_daemon
                                   (TpBaseConnectionManager *self);

#### Parameters

self | the connection manager |

#### Returns

the value of the “dbus-daemon” property. The caller must reference the returned object with `g_object_ref()` if it will be kept.

[transfer none]

Since: 0.11.3

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

#### Parameters

self | The connection manager implementation |

#### Returns

`TRUE` on success, `FALSE` (having emitted a warning to stderr) on failure

### tp_base_connection_manager_add_protocol ()

    void
    tp_base_connection_manager_add_protocol
                                   (TpBaseConnectionManager *self,
                                    TpBaseProtocol *protocol);

Add a protocol object to the set of supported protocols.

#### Parameters

self | a connection manager object which has not yet registered on D-Bus (i.e. `tp_base_connection_manager_register()` must not have been called) |
protocol | a protocol object, which must not have the same protocol name as any that has already been added |

## Types and Values

### struct TpCMParamSpec

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

        TpCMParamFilter filter;
        gconstpointer filter_data;

        gconstpointer setter_data;
    };

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.

#### Members

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

#### Members

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

### struct TpBaseConnectionManager

    struct TpBaseConnectionManager;

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

### struct TpBaseConnectionManagerClass

    struct TpBaseConnectionManagerClass {
        GObjectClass parent_class;

        const char *cm_dbus_name;

        TpBaseConnectionManagerGetInterfacesFunc get_interfaces;
    };

The class structure for TpBaseConnectionManager.

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

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

Changed in 0.11.11: protocol_params and new_connection may both be `NULL`. If so, this connection manager is assumed to use Protocol objects instead. Since 0.19.2 those fields are deprecated and should not be used anymore.

#### Members

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

TpBaseConnectionManagerGetInterfacesFunc `get_interfaces`;

Returns a GPtrArray of static strings of extra D-Bus interfaces implemented by instances of this class, which may be filled in by subclasses. The default is to list no additional interfaces. Implementations must first chainup on parent class implementation and then add extra interfaces to the GPtrArray. Replaces `interfaces` . Since: 0.19.4

## Property Details

### The `“dbus-daemon”` property

      “dbus-daemon”              TpDBusDaemon *

TpDBusDaemon object encapsulating this object's connection to D-Bus. Read-only except during construction.

If this property is `NULL` or omitted during construction, the object will automatically attempt to connect to the starter or session bus with `tp_dbus_daemon_dup()` just after it is constructed; if this fails, a warning will be logged with `g_warning()`, and this property will remain `NULL`.

Owner: TpBaseConnectionManager

Flags: Read / Write / Construct Only

Since: 0.11.3

### The `“interfaces”` property

      “interfaces”               GStrv

The set of D-Bus interfaces available on this ConnectionManager, other than ConnectionManager itself.

Owner: TpBaseConnectionManager

Flags: Read

Since: 0.11.11

### The `“protocols”` property

      “protocols”                GHashTable_gchararray+GHashTable_gchararray+GValue__*

The Protocol objects available on this ConnectionManager.

Owner: TpBaseConnectionManager

Flags: Read

Since: 0.11.11

## Signal Details

### The `“no-more-connections”` signal

    void
    user_function (TpBaseConnectionManager *tpbaseconnectionmanager,
                   gpointer                 user_data)

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

#### Parameters

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

Flags: Has Details

## See Also

TpBaseConnection, TpSvcConnectionManager, run