![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
TpDBusPropertiesMixinTpDBusPropertiesMixin — a mixin implementation of the DBus.Properties interface |
#include <telepathy-glib/dbus-properties-mixin.h> enum TpDBusPropertiesMixinFlags; TpDBusPropertiesMixinIfaceInfo; TpDBusPropertiesMixinPropInfo; void tp_svc_interface_set_dbus_properties_info (GType g_interface, TpDBusPropertiesMixinIfaceInfo *info); TpDBusPropertiesMixinClass; TpDBusPropertiesMixinIfaceImpl; TpDBusPropertiesMixinPropImpl; void (*TpDBusPropertiesMixinGetter) (GObject *object, GQuark interface, GQuark name, GValue *value, gpointer getter_data); void tp_dbus_properties_mixin_getter_gobject_properties (GObject *object, GQuark interface, GQuark name, GValue *value, gpointer getter_data); gboolean (*TpDBusPropertiesMixinSetter) (GObject *object, GQuark interface, GQuark name, const GValue *value, gpointer setter_data, GError **error); gboolean tp_dbus_properties_mixin_setter_gobject_properties (GObject *object, GQuark interface, GQuark name, const GValue *value, gpointer setter_data, GError **error); void tp_dbus_properties_mixin_class_init (GObjectClass *cls, gsize offset); void tp_dbus_properties_mixin_implement_interface (GObjectClass *cls, GQuark iface, TpDBusPropertiesMixinGetter getter, TpDBusPropertiesMixinSetter setter, TpDBusPropertiesMixinPropImpl *props); void tp_dbus_properties_mixin_iface_init (gpointer g_iface, gpointer iface_data); gboolean tp_dbus_properties_mixin_get (GObject *self, const gchar *interface_name, const gchar *property_name, GValue *value, GError **error); GHashTable* tp_dbus_properties_mixin_make_properties_hash (GObject *object, const gchar *first_interface, const gchar *first_property, ...);
This mixin provides an implementation of the org.freedesktop.DBus.Properties interface. It relies on the auto-generated service-side GInterfaces from telepathy-glib >= 0.7.3, or something similar, to register the abstract properties and their GTypes; classes with the mixin can then register an implementation of the properties.
To register D-Bus properties in a GInterface to be implementable with this
mixin, either use the code-generation tools from telepathy-glib >= 0.7.3,
or call tp_svc_interface_set_properties_info()
from a section of the
base_init function that only runs once.
To use this mixin, include a TpDBusPropertiesMixinClass somewhere
in your class structure, populate it with pointers to statically allocated
(or duplicated and never freed) data, and call
tp_dbus_properties_mixin_class_init()
from your class_init implementation.
To use this mixin as the implementation of TpSvcDBusProperties,
call G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_DBUS_PROPERTIES,
tp_dbus_properties_mixin_iface_init)
in the fourth argument to
G_DEFINE_TYPE_WITH_CODE
.
typedef enum { TP_DBUS_PROPERTIES_MIXIN_FLAG_READ = 1, TP_DBUS_PROPERTIES_MIXIN_FLAG_WRITE = 2 } TpDBusPropertiesMixinFlags;
Bitfield representing allowed access to a property.
TP_DBUS_PROPERTIES_MIXIN_FLAG_READ
|
The property can be read using Get and GetAll |
TP_DBUS_PROPERTIES_MIXIN_FLAG_WRITE
|
The property can be written using Set |
Since 0.7.3
typedef struct { GQuark dbus_interface; TpDBusPropertiesMixinPropInfo *props; } TpDBusPropertiesMixinIfaceInfo;
Semi-abstract description of an interface. Each service GInterface that
has properties must have one of these attached to it via
tp_svc_interface_set_dbus_properties_info()
in its base_init function;
service GInterfaces that do not have properties may have one of these
with no properties.
This structure must either be statically allocated, or duplicated and never freed, so it always remains valid.
In addition to the documented members, there are two private pointers
for future expansion, which must always be initialized to NULL
.
GQuark dbus_interface ; |
Quark representing the interface's name |
TpDBusPropertiesMixinPropInfo *props ; |
Array of property descriptions, terminated by one with
name == NULL
|
Since 0.7.3
typedef struct { GQuark name; TpDBusPropertiesMixinFlags flags; gchar *dbus_signature; GType type; } TpDBusPropertiesMixinPropInfo;
Semi-abstract description of a property, as attached to a service GInterface. This structure must either be statically allocated, or duplicated and never freed, so it always remains valid.
In addition to the documented members, there are two private pointers
for future expansion, which must always be initialized to NULL
.
GQuark name ; |
Quark representing the property's name |
TpDBusPropertiesMixinFlags flags ; |
Flags representing read/write access to the property |
gchar *dbus_signature ; |
The D-Bus signature of the property |
GType type ; |
The GType used in a GValue to implement the property |
Since 0.7.3
void tp_svc_interface_set_dbus_properties_info (GType g_interface, TpDBusPropertiesMixinIfaceInfo *info);
Declare that g_interface
implements the given D-Bus interface, with the
given properties. This may only be called once per GInterface, usually from
a section of its base_init function that only runs once.
g_interface : |
The GType of a service interface |
info : |
an interface description |
Since 0.7.3
typedef struct { TpDBusPropertiesMixinIfaceImpl *interfaces; } TpDBusPropertiesMixinClass;
Structure representing all of a class's property implementations. One of these structures may be placed in the layout of an object class structure.
In addition to the documented fields, there are 7 pointers reserved for
future use, which must be initialized to NULL
.
TpDBusPropertiesMixinIfaceImpl *interfaces ; |
An array of interface implementations, terminated by one with
name equal to NULL
|
Since 0.7.3
typedef struct { const gchar *name; TpDBusPropertiesMixinGetter getter; TpDBusPropertiesMixinSetter setter; TpDBusPropertiesMixinPropImpl *props; } TpDBusPropertiesMixinIfaceImpl;
Structure representing an implementation of an interface's properties.
In addition to the documented fields, there are four pointers which must
be initialized to NULL
.
This structure must either be statically allocated, or duplicated and never freed, so it always remains valid.
const gchar *name ; |
The name of the interface |
TpDBusPropertiesMixinGetter getter ; |
A callback to get the current value of the property, to which
the getter_data from each property implementation will be passed
|
TpDBusPropertiesMixinSetter setter ; |
A callback to set a new value for the property, to which
the setter_data from each property implementation will be passed
|
TpDBusPropertiesMixinPropImpl *props ; |
An array of property implementations, terminated by one with
name equal to NULL
|
Since 0.7.3
typedef struct { const gchar *name; gpointer getter_data; gpointer setter_data; } TpDBusPropertiesMixinPropImpl;
Structure representing an implementation of a property.
In addition to the documented fields, there are three pointers which must
be initialized to NULL
.
This structure must either be statically allocated, or duplicated and never freed, so it always remains valid.
const gchar *name ; |
The name of the property as it appears on D-Bus |
gpointer getter_data ; |
Arbitrary user-supplied data for the getter function |
gpointer setter_data ; |
Arbitrary user-supplied data for the setter function |
Since 0.7.3
void (*TpDBusPropertiesMixinGetter) (GObject *object, GQuark interface, GQuark name, GValue *value, gpointer getter_data);
Signature of a callback used to get the value of a property.
For simplicity, in this mixin we don't allow getting a property to fail; implementations must always be prepared to return *something*.
object : |
The exported object with the properties |
interface : |
A quark representing the D-Bus interface name |
name : |
A quark representing the D-Bus property name |
value : |
A GValue pre-initialized to the right type, into which to put the value |
getter_data : |
The getter_data from the TpDBusPropertiesMixinPropImpl |
void tp_dbus_properties_mixin_getter_gobject_properties (GObject *object, GQuark interface, GQuark name, GValue *value, gpointer getter_data);
An implementation of TpDBusPropertiesMixinGetter which assumes that
the getter_data
is the name of a readable GObject property of an
appropriate type, and uses it for the value of the D-Bus property.
object : |
The exported object with the properties |
interface : |
A quark representing the D-Bus interface name |
name : |
A quark representing the D-Bus property name |
value : |
A GValue pre-initialized to the right type, into which to put the value |
getter_data : |
The getter_data from the TpDBusPropertiesMixinPropImpl, which must be a string containing the GObject property's name |
gboolean (*TpDBusPropertiesMixinSetter) (GObject *object, GQuark interface, GQuark name, const GValue *value, gpointer setter_data, GError **error);
Signature of a callback used to get the value of a property.
object : |
The exported object with the properties |
interface : |
A quark representing the D-Bus interface name |
name : |
A quark representing the D-Bus property name |
value : |
The new value for the property |
setter_data : |
The setter_data from the TpDBusPropertiesMixinPropImpl |
error : |
Used to return an error on failure |
Returns : | TRUE on success, FALSE (setting error ) on failure
|
gboolean tp_dbus_properties_mixin_setter_gobject_properties (GObject *object, GQuark interface, GQuark name, const GValue *value, gpointer setter_data, GError **error);
An implementation of TpDBusPropertiesMixinSetter which assumes that the
setter_data
is the name of a writable GObject property of an appropriate
type, and sets that property to the given value.
object : |
The exported object with the properties |
interface : |
A quark representing the D-Bus interface name |
name : |
A quark representing the D-Bus property name |
value : |
The new value for the property |
setter_data : |
The setter_data from the TpDBusPropertiesMixinPropImpl, which must be a string containing the GObject property's name |
error : |
Not used |
Returns : | TRUE
|
void tp_dbus_properties_mixin_class_init (GObjectClass *cls, gsize offset);
Initialize the class cls
to use the D-Bus Properties mixin.
The given struct member, of size sizeof(TpDBusPropertiesMixinClass),
will be used to store property implementation information.
Each property and each interface must have been declared as a member of
a GInterface implemented by cls
, using
tp_svc_interface_set_dbus_properties_info()
.
Before calling this function, the array interfaces
must have been
placed in the TpDBusPropertiesMixinClass structure; if it would be empty,
it may instead be NULL
.
This function should be called from the class_init callback in such a way that it will only be called once, even if the class is subclassed.
Changed in 0.7.9: TpDBusPropertiesMixinClass::interfaces may now be NULL
,
which means that only interfaces whose properties are set up using
tp_dbus_properties_mixin_implement_interface()
will be used.
Changed in 0.7.15: offset
may now be 0, in which case the
TpDBusPropertiesMixinClass can be omitted from cls
. It is treated as if
it were present, but with all fields (including
TpDBusPropertiesMixinClass::interfaces) being NULL
, so only interfaces
whose properties are set using
tp_dbus_properties_mixin_implement_interface()
will be used.
cls : |
a subclass of GObjectClass |
offset : |
the offset within cls of a TpDBusPropertiesMixinClass structure
|
Since 0.7.3
void tp_dbus_properties_mixin_implement_interface (GObjectClass *cls, GQuark iface, TpDBusPropertiesMixinGetter getter, TpDBusPropertiesMixinSetter setter, TpDBusPropertiesMixinPropImpl *props);
Declare that, in addition to any interfaces set in
tp_dbus_properties_mixin_class_init()
, the given class (and its subclasses)
will implement the properties of the interface iface
using the callbacks
getter
and setter
and the properties given by props
.
This function should be called from the class_init callback in such a way that it will only be called once, even if the class is subclassed.
Typically, the static array interfaces
in the TpDBusPropertiesMixinClass
should be used for interfaces whose properties are implemented directly by
the class cls
, and this function should be used for interfaces whose
properties are implemented by mixins.
It is an error for the same interface to appear in the array interfaces
in the TpDBusPropertiesMixinClass, and also be set up by this function.
If a class C and a subclass S both implement the properties of the same
interface, only the implementations from the subclass S will be used,
regardless of whether the implementations in C and/or S were set up by
this function or via the array interfaces
in the
TpDBusPropertiesMixinClass.
cls : |
a subclass of GObjectClass |
iface : |
a quark representing the the name of the interface to implement |
getter : |
a callback to get properties on this interface, or NULL if they
are all write-only
|
setter : |
a callback to set properties on this interface, or NULL if they
are all read-only
|
props : |
an array of TpDBusPropertiesMixinPropImpl representing individual
properties, terminated by one with name == NULL
|
void tp_dbus_properties_mixin_iface_init (gpointer g_iface, gpointer iface_data);
Declare that the DBus.Properties interface represented by g_iface
is implemented using this mixin.
g_iface : |
a pointer to a TpSvcDBusPropertiesClass structure |
iface_data : |
ignored |
gboolean tp_dbus_properties_mixin_get (GObject *self, const gchar *interface_name, const gchar *property_name, GValue *value, GError **error);
Initialize value
with the type of the property property_name
on
interface_name
, and write the value of that property into it as if
by calling the D-Bus method org.freedesktop.DBus.Properties.Get.
If Get would return a D-Bus error, value
remains unset and error
is filled in instead.
self : |
an object with this mixin |
interface_name : |
a D-Bus interface name |
property_name : |
a D-Bus property name |
value : |
an unset GValue (initialized to all zeroes) |
error : |
used to return an error on failure |
Returns : | TRUE (filling value ) on success, FALSE (setting error )
on failure
|
Since 0.7.13
GHashTable* tp_dbus_properties_mixin_make_properties_hash (GObject *object, const gchar *first_interface, const gchar *first_property, ...);
Retrieves the values of several D-Bus properties from an object, and builds
a hash mapping the fully-qualified name of the property to its value. This
is equivalent to calling tp_dbus_properties_mixin_get()
for each property
and building the table yourself, with the proviso that this function will
g_assert()
if retrieving a property fails (for instance, because it does not
exist).
Additional keys and values can be inserted into the returned hash table;
if this is done, the inserted keys and values will be freed when the
hash table is destroyed. The keys must be allocated with g_strdup()
or
equivalent, and the values must be slice-allocated (for instance with
tp_g_value_slice_new_string()
or a similar function).
Note that in particular, tp_asv_set_string()
and similar functions should
not be used with this hash table.
object : |
an object which uses the D-Bus properties mixin |
first_interface : |
the interface of the first property to be retrieved |
first_property : |
the name of the first property to be retrieved |
... : |
more (interface name, property name) pairs, terminated by NULL .
|
Returns : | a hash table mapping (gchar *) fully-qualified property names to GValues, which must be freed by the caller (at which point its contents will also be freed). |