TpDBusPropertiesMixin

## TpDBusPropertiesMixin TpDBusPropertiesMixin — a mixin implementation of the DBus.Properties interface |

## Synopsis

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

    enum                TpDBusPropertiesMixinFlags;
    #define             TP_TYPE_DBUS_PROPERTIES_MIXIN_FLAGS
                        TpDBusPropertiesMixinIfaceInfo;
                        TpDBusPropertiesMixinPropInfo;
    void                tp_svc_interface_set_dbus_properties_info
                                                            (GType g_interface,
                                                             TpDBusPropertiesMixinIfaceInfo *info);
    TpDBusPropertiesMixinIfaceInfo * tp_svc_interface_get_dbus_properties_info
                                                            (GType g_interface);

                        TpDBusPropertiesMixinClass;
                        TpDBusPropertiesMixinIfaceImpl;
                        TpDBusPropertiesMixinPropImpl;
    void                (*TpDBusPropertiesMixinGetter)      (GObject *object,
                                                             GQuark iface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer getter_data);
    void                tp_dbus_properties_mixin_getter_gobject_properties
                                                            (GObject *object,
                                                             GQuark iface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer getter_data);
    gboolean            (*TpDBusPropertiesMixinSetter)      (GObject *object,
                                                             GQuark iface,
                                                             GQuark name,
                                                             const GValue *value,
                                                             gpointer setter_data,
                                                             GError **error);
    gboolean            tp_dbus_properties_mixin_setter_gobject_properties
                                                            (GObject *object,
                                                             GQuark iface,
                                                             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_dup_all    (GObject *self,
                                                             const gchar *interface_name);
    gboolean            tp_dbus_properties_mixin_set        (GObject *self,
                                                             const gchar *interface_name,
                                                             const gchar *property_name,
                                                             const GValue *value,
                                                             GError **error);
    void                tp_dbus_properties_mixin_fill_properties_hash
                                                            (GObject *object,
                                                             GHashTable *table,
                                                             const gchar *first_interface,
                                                             const gchar *first_property,
                                                             ...);
    GHashTable *        tp_dbus_properties_mixin_make_properties_hash
                                                            (GObject *object,
                                                             const gchar *first_interface,
                                                             const gchar *first_property,
                                                             ...);
    void                tp_dbus_properties_mixin_emit_properties_changed
                                                            (GObject *object,
                                                             const gchar *interface_name,
                                                             const gchar * const *properties);
    void                tp_dbus_properties_mixin_emit_properties_changed_varargs
                                                            (GObject *object,
                                                             const gchar *interface_name,
                                                             ...);

## Object Hierarchy

      GFlags
       +----TpDBusPropertiesMixinFlags

## Description

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

## Details

### enum TpDBusPropertiesMixinFlags

    typedef enum {
     /*< flags >*/
        TP_DBUS_PROPERTIES_MIXIN_FLAG_READ = 1,
        TP_DBUS_PROPERTIES_MIXIN_FLAG_WRITE = 2,
        TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_CHANGED = 4,
        TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_INVALIDATED = 8
    } TpDBusPropertiesMixinFlags;

Bitfield representing allowed access to a property. At most one of `TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_CHANGED` and `TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_INVALIDATED` may be specified for a property.

Since 0.11.5, there is a corresponding GFlagsClass type, `TP_TYPE_DBUS_PROPERTIES_MIXIN_FLAGS`.

`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
`TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_CHANGED` | The property's new value is included in emissions of PropertiesChanged
`TP_DBUS_PROPERTIES_MIXIN_FLAG_EMITS_INVALIDATED` | The property is announced as invalidated, without its value, in emissions of PropertiesChanged

Since 0.7.3

### TP_TYPE_DBUS_PROPERTIES_MIXIN_FLAGS

    #define TP_TYPE_DBUS_PROPERTIES_MIXIN_FLAGS (tp_dbus_properties_mixin_flags_get_type ())

The GFlagsClass type of TpDBusPropertiesMixinFlags.

Since 0.11.5

### TpDBusPropertiesMixinIfaceInfo

    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

### TpDBusPropertiesMixinPropInfo

    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

### tp_svc_interface_set_dbus_properties_info ()

    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.

This is typically only used within generated code; there is normally no reason to call it manually.

`g_interface` : | The GType of a service interface
`info` : | an interface description

Since 0.7.3

### tp_svc_interface_get_dbus_properties_info ()

    TpDBusPropertiesMixinIfaceInfo * tp_svc_interface_get_dbus_properties_info
                                                            (GType g_interface);

Retrieves the D-Bus property metadata for the given interface, if any. This function is typically not useful outside telepathy-glib itself, but may be useful for domain-specific variations on the theme of SetProperty. If in doubt, you probably don't need this function.

`g_interface` : | The GType of a service interface
Returns : | D-Bus property metadata for `g_interface`, or `NULL` if it has none.

Since 0.15.8

### TpDBusPropertiesMixinClass

    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

### TpDBusPropertiesMixinIfaceImpl

    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

### TpDBusPropertiesMixinPropImpl

    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

### TpDBusPropertiesMixinGetter ()

    void                (*TpDBusPropertiesMixinGetter)      (GObject *object,
                                                             GQuark iface,
                                                             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
`iface` : | 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

### tp_dbus_properties_mixin_getter_gobject_properties ()

    void                tp_dbus_properties_mixin_getter_gobject_properties
                                                            (GObject *object,
                                                             GQuark iface,
                                                             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
`iface` : | 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

### TpDBusPropertiesMixinSetter ()

    gboolean            (*TpDBusPropertiesMixinSetter)      (GObject *object,
                                                             GQuark iface,
                                                             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
`iface` : | 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

### tp_dbus_properties_mixin_setter_gobject_properties ()

    gboolean            tp_dbus_properties_mixin_setter_gobject_properties
                                                            (GObject *object,
                                                             GQuark iface,
                                                             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
`iface` : | 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`

### tp_dbus_properties_mixin_class_init ()

    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

### tp_dbus_properties_mixin_implement_interface ()

    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`

### tp_dbus_properties_mixin_iface_init ()

    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

### tp_dbus_properties_mixin_get ()

    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

### tp_dbus_properties_mixin_dup_all ()

    GHashTable *        tp_dbus_properties_mixin_dup_all    (GObject *self,
                                                             const gchar *interface_name);

Get all the properties of a particular interface. This implementation never returns an error: it will return an empty map if the interface is unknown.

`self` : | an object with this mixin
`interface_name` : | a D-Bus interface name
Returns : | a map from property name (without the interface name) to value. [transfer container][element-type utf8 GObject.Value]

Since 0.21.2

### tp_dbus_properties_mixin_set ()

    gboolean            tp_dbus_properties_mixin_set        (GObject *self,
                                                             const gchar *interface_name,
                                                             const gchar *property_name,
                                                             const GValue *value,
                                                             GError **error);

Sets a property to the value specified by `value`, as if by calling the D-Bus method org.freedesktop.DBus.Properties.Set.

If Set would return a D-Bus error, sets `error` and returns `FALSE`

`self` : | an object with this mixin
`interface_name` : | a D-Bus interface name
`property_name` : | a D-Bus property name
`value` : | a GValue containing the new value for this property.
`error` : | used to return an error on failure
Returns : | `TRUE` on success; `FALSE` (setting `error`) on failure

Since 0.15.8

### tp_dbus_properties_mixin_fill_properties_hash ()

    void                tp_dbus_properties_mixin_fill_properties_hash
                                                            (GObject *object,
                                                             GHashTable *table,
                                                             const gchar *first_interface,
                                                             const gchar *first_property,
                                                             ...);

Retrieves the values of several D-Bus properties from an object, and adds them to 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 adding it to the table yourself, with the proviso that this function will `g_assert()` if retrieving a property fails (for instance, because it does not exist).

Note that in particular, `table` does not have the same memory-allocation model as the hash tables required by `tp_asv_set_string()` and similar functions.

`object` : | an object which uses the D-Bus properties mixin
`table` : | a hash table where the keys are strings copied with `g_strdup()` and the values are slice-allocated GValues. [element-type utf8 GObject.Value]
`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`.

Since 0.11.11

### tp_dbus_properties_mixin_make_properties_hash ()

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

### tp_dbus_properties_mixin_emit_properties_changed ()

    void                tp_dbus_properties_mixin_emit_properties_changed
                                                            (GObject *object,
                                                             const gchar *interface_name,
                                                             const gchar * const *properties);

Emits the PropertiesChanged signal for the provided properties. Depending on the EmitsChangedSignal annotations in the introspection XML, either the new value of the property will be included in the signal, or merely the fact that the property has changed.

For example, the MPRIS specification defines a TrackList interface with two properties, one of which is annotated with EmitsChangedSignal=true and one annotated with EmitsChangedSignal=invalidates. The following call would include the new value of CanEditTracks and list Tracks as invalidated:

    1
    2
    3
    4
    const gchar *properties[] = { "CanEditTracks", "Tracks", NULL };

    tp_dbus_properties_mixin_emit_properties_changed (G_OBJECT (self),
        "org.mpris.MediaPlayer2.TrackList", properties);

It is an error to pass a property to this function if the property is annotated with EmitsChangedSignal=false, or is unannotated.

`object` : | an object which uses the D-Bus properties mixin
`interface_name` : | the interface on which properties have changed
`properties` : | a `NULL`-terminated array of (unqualified) property names whose values have changed. [allow-none]

Since 0.15.6

### tp_dbus_properties_mixin_emit_properties_changed_varargs ()

    void                tp_dbus_properties_mixin_emit_properties_changed_varargs
                                                            (GObject *object,
                                                             const gchar *interface_name,
                                                             ...);

A shortcut for calling `tp_dbus_properties_mixin_emit_properties_changed()`.

`object` : | an object which uses the D-Bus properties mixin
`interface_name` : | the interface on which properties have changed
`...` : | property names (unqualified) whose values have changed, terminated by `NULL`.

Since 0.15.6

## See Also

TpSvcDBusProperties