![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
TpBaseConnectionManagerTpBaseConnectionManager — base class for TpSvcConnectionManager implementations |
#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);
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.
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
|
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
|
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
|
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
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
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 .
|
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.)
|
typedef struct _TpBaseConnectionManager TpBaseConnectionManager;
A base class for connection managers. There are no interesting public fields in the instance structure.
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. |
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.
|
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
|
"no-more-connections"
signalvoid 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. |