TpPropertiesMixin

## TpPropertiesMixin TpPropertiesMixin — a mixin implementation of the Telepathy.Properties interface |

## Synopsis

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

                        TpPropertySignature;
                        TpProperty;
                        TpPropertiesContext;
    gboolean            (*TpPropertiesSetFunc)              (GObject *obj,
                                                             TpPropertiesContext *ctx,
                                                             GError **error);
    struct              TpPropertiesMixin;
    struct              TpPropertiesMixinClass;
    void                tp_properties_mixin_class_init      (GObjectClass *obj_cls,
                                                             glong offset,
                                                             const TpPropertySignature *signatures,
                                                             guint num_properties,
                                                             TpPropertiesSetFunc set_func);
    void                tp_properties_mixin_init            (GObject *obj,
                                                             glong offset);
    void                tp_properties_mixin_finalize        (GObject *obj);
    gboolean            tp_properties_mixin_list_properties (GObject *obj,
                                                             GPtrArray **ret,
                                                             GError **error);
    gboolean            tp_properties_mixin_get_properties  (GObject *obj,
                                                             const GArray *properties,
                                                             GPtrArray **ret,
                                                             GError **error);
    void                tp_properties_mixin_set_properties  (GObject *obj,
                                                             const GPtrArray *properties,
                                                             DBusGMethodInvocation *context);
    gboolean            tp_properties_mixin_has_property    (GObject *obj,
                                                             const gchar *name,
                                                             guint *property);
    gboolean            tp_properties_context_has           (TpPropertiesContext *ctx,
                                                             guint property);
    gboolean            tp_properties_context_has_other_than
                                                            (TpPropertiesContext *ctx,
                                                             guint property);
    const GValue *      tp_properties_context_get           (TpPropertiesContext *ctx,
                                                             guint property);
    guint               tp_properties_context_get_value_count
                                                            (TpPropertiesContext *ctx);
    void                tp_properties_context_remove        (TpPropertiesContext *ctx,
                                                             guint property);
    void                tp_properties_context_return        (TpPropertiesContext *ctx,
                                                             GError *error);
    gboolean            tp_properties_context_return_if_done
                                                            (TpPropertiesContext *ctx);
    void                tp_properties_mixin_change_value    (GObject *obj,
                                                             guint prop_id,
                                                             const GValue *new_value,
                                                             TpIntset *props);
    void                tp_properties_mixin_change_flags    (GObject *obj,
                                                             guint prop_id,
                                                             TpPropertyFlags add,
                                                             TpPropertyFlags del,
                                                             TpIntset *props);
    void                tp_properties_mixin_emit_changed    (GObject *obj,
                                                             const TpIntset *props);
    void                tp_properties_mixin_emit_flags      (GObject *obj,
                                                             const TpIntset *props);
    gboolean            tp_properties_mixin_is_readable     (GObject *obj,
                                                             guint prop_id);
    gboolean            tp_properties_mixin_is_writable     (GObject *obj,
                                                             guint prop_id);
    void                tp_properties_mixin_iface_init      (gpointer g_iface,
                                                             gpointer iface_data);
    #define             TP_TYPE_PROPERTY_INFO_STRUCT
    #define             TP_TYPE_PROPERTY_INFO_LIST
    #define             TP_TYPE_PROPERTY_VALUE_STRUCT
    #define             TP_TYPE_PROPERTY_VALUE_LIST
    #define             TP_TYPE_PROPERTY_FLAGS_STRUCT
    #define             TP_TYPE_PROPERTY_FLAGS_LIST

## Description

This mixin can be added to any GObject class to implement the properties interface in a general way.

To use the properties mixin, include a TpPropertiesMixinClass somewhere in your class structure and a TpPropertiesMixin somewhere in your instance structure, and call `tp_properties_mixin_class_init()` from your class_init function, `tp_properties_mixin_init()` from your init function or constructor, and `tp_properties_mixin_finalize()` from your dispose or finalize function.

To use the properties mixin as the implementation of TpSvcPropertiesInterface, call `G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_PROPERTIES_INTERFACE, tp_properties_mixin_iface_init)` in the fourth argument to `G_DEFINE_TYPE_WITH_CODE`.

## Details

### TpPropertySignature

    typedef struct {
        gchar *name;
        GType type;
    } TpPropertySignature;

Signature of a property in the Telepathy properties interface.

gchar *`name`; | Name of the property as seen in the Telepathy D-Bus protocol
GType `type`; | GType which the variant value must have. We currently support only `G_TYPE_UINT`, `G_TYPE_INT`, `G_TYPE_STRING`, `G_TYPE_BOOLEAN`, corresponding to D-Bus signatures 'u', 'i', 's', 'b'.

### TpProperty

    typedef struct {
        /* FIXME: if we ever break ABI, make this a (GValue) rather than a
         * (GValue *) */
        GValue *value;
        guint flags;
    } TpProperty;

Structure representing the current state of a property.

GValue *`value`; | The value of the property
guint `flags`; | TpPropertyFlags indicating the property's permissions

### TpPropertiesContext

    typedef struct _TpPropertiesContext TpPropertiesContext;

Opaque pointer representing an incomplete property-setting operation, used in the implementation of SetProperties.

### TpPropertiesSetFunc ()

    gboolean            (*TpPropertiesSetFunc)              (GObject *obj,
                                                             TpPropertiesContext *ctx,
                                                             GError **error);

A callback used to implement the SetProperties D-Bus method by setting properties in the underlying IM protocol.

The callback must either:

* return `FALSE` to indicate immediate failure * call `tp_properties_context_return()` with an error to indicate failure * call `tp_properties_context_remove()` to remove each property from the set of pending properties, then call `tp_properties_context_return_if_done()` or `tp_properties_context_return()` when all were set

`obj` : | An object with the properties mixin
`ctx` : | A properties context
`error` : | Set to the error if `FALSE` is returned
Returns : | `FALSE` on immediate failure, `TRUE` otherwise

### struct TpPropertiesMixin

    struct TpPropertiesMixin {
        TpProperty *properties;

        TpPropertiesMixinPrivate *priv;
    };

Structure to be placed in a GObject-derived structure containing instance data for the properties mixin (i.e. the properties). Initialize it using `tp_properties_mixin_init()`.

TpProperty *`properties`; | Array of property values, of length klass->num_props. Should be considered read-only.
TpPropertiesMixinPrivate *`priv`; | Pointer to opaque private data.

### struct TpPropertiesMixinClass

    struct TpPropertiesMixinClass {
      const TpPropertySignature *signatures;
      guint num_props;

      TpPropertiesSetFunc set_properties;

      TpPropertiesMixinClassPrivate *priv;
    };

Structure to be placed in a GObjectClass-derived structure containing settings for the properties mixin. Initialize it using `tp_properties_mixin_class_init()`.

All fields should be considered read-only.

const TpPropertySignature *`signatures`; | Array of property signatures, as provided via `tp_properties_mixin_class_init()`, of length `num_props`.
guint `num_props`; | Number of properties supported.
TpPropertiesSetFunc `set_properties`; | Properties setting function, as supplied to `tp_properties_mixin_class_init()`.
TpPropertiesMixinClassPrivate *`priv`; | Pointer to opaque private data.

### tp_properties_mixin_class_init ()

    void                tp_properties_mixin_class_init      (GObjectClass *obj_cls,
                                                             glong offset,
                                                             const TpPropertySignature *signatures,
                                                             guint num_properties,
                                                             TpPropertiesSetFunc set_func);

Initialize the mixin. Should be called from the implementation's class_init function like so:

    1
    2
    3
    tp_properties_mixin_class_init ((GObjectClass *) klass,
                                    G_STRUCT_OFFSET (SomeObjectClass,
                                     properties_mixin));

`obj_cls` : | The class of an object that has this mixin
`offset` : | The offset of the TpPropertiesMixinClass structure in the class structure
`signatures` : | An array of property signatures
`num_properties` : | The number of entries in `signatures`
`set_func` : | Callback used to set the properties

### tp_properties_mixin_init ()

    void                tp_properties_mixin_init            (GObject *obj,
                                                             glong offset);

Initialize the mixin. Should be called from the implementation's instance init function like so:

    1
    2
    3
    tp_properties_mixin_init ((GObject *) self,
                              G_STRUCT_OFFSET (SomeObject, properties_mixin),
                              self->contact_repo);

`obj` : | An object that has this mixin
`offset` : | The offset of the TpPropertiesMixin structure in the object structure

### tp_properties_mixin_finalize ()

    void                tp_properties_mixin_finalize        (GObject *obj);

Free memory used by the TpPropertiesMixin.

`obj` : | An object that has this mixin

### tp_properties_mixin_list_properties ()

    gboolean            tp_properties_mixin_list_properties (GObject *obj,
                                                             GPtrArray **ret,
                                                             GError **error);

List all available properties and their flags, as in the ListProperties D-Bus method.

`obj` : | An object with this mixin
`ret` : | Output parameter which will be set to a GPtrArray of D-Bus structures if `TRUE` is returned
`error` : | Set to the error if `FALSE` is returned
Returns : | `TRUE` on success

### tp_properties_mixin_get_properties ()

    gboolean            tp_properties_mixin_get_properties  (GObject *obj,
                                                             const GArray *properties,
                                                             GPtrArray **ret,
                                                             GError **error);

Retrieve the values of the given properties, as in the GetProperties D-Bus method.

`obj` : | An object with this mixin
`properties` : | an array of integer property IDs
`ret` : | set to an array of D-Bus structures if `TRUE` is returned
`error` : | Set to the error if `FALSE` is returned
Returns : | `TRUE` on success

### tp_properties_mixin_set_properties ()

    void                tp_properties_mixin_set_properties  (GObject *obj,
                                                             const GPtrArray *properties,
                                                             DBusGMethodInvocation *context);

Start to change properties in response to user request via D-Bus.

`obj` : | An object with this mixin
`properties` : | An array of D-Bus structures containing property ID and value
`context` : | A D-Bus method invocation context for the SetProperties method

### tp_properties_mixin_has_property ()

    gboolean            tp_properties_mixin_has_property    (GObject *obj,
                                                             const gchar *name,
                                                             guint *property);

`obj` : | an object with a properties mixin
`name` : | the string name of the property
`property` : | either `NULL`, or a pointer to a location to receive the property index
Returns : | `TRUE`, setting `property`, if `obj` has a property of that name

### tp_properties_context_has ()

    gboolean            tp_properties_context_has           (TpPropertiesContext *ctx,
                                                             guint property);

`ctx` : | the properties context representing a SetProperties call
`property` : | the property ID
Returns : | `TRUE` if `ctx` indicates that `property` still needs to be set on the server.

### tp_properties_context_has_other_than ()

    gboolean            tp_properties_context_has_other_than
                                                            (TpPropertiesContext *ctx,
                                                             guint property);

`ctx` : | the properties context representing a SetProperties call
`property` : | the property ID
Returns : | `TRUE` if `ctx` has properties other than `property` that still need to be set on the server

### tp_properties_context_get ()

    const GValue *      tp_properties_context_get           (TpPropertiesContext *ctx,
                                                             guint property);

`ctx` : | the properties context representing a SetProperties call
`property` : | a property ID
Returns : | the value to be set on the server for the property `property` in `ctx` (whether it has been set already or not)

### tp_properties_context_get_value_count ()

    guint               tp_properties_context_get_value_count
                                                            (TpPropertiesContext *ctx);

`ctx` : | the properties context representing a SetProperties call
Returns : | the number of properties in `ctx` which still need to be set on the server, or have already been set

### tp_properties_context_remove ()

    void                tp_properties_context_remove        (TpPropertiesContext *ctx,
                                                             guint property);

Mark the given property as having been set successfully.

`ctx` : | the properties context representing a SetProperties call
`property` : | a property ID

### tp_properties_context_return ()

    void                tp_properties_context_return        (TpPropertiesContext *ctx,
                                                             GError *error);

Commit the property changes and return from the pending D-Bus call.

`ctx` : | the properties context representing a SetProperties call
`error` : | If `NULL`, return successfully; otherwise return this error

### tp_properties_context_return_if_done ()

    gboolean            tp_properties_context_return_if_done
                                                            (TpPropertiesContext *ctx);

Return from the pending D-Bus call if there are no more properties to be dealt with.

`ctx` : | the properties context representing a SetProperties call
Returns : | `TRUE` if we returned from the D-Bus call.

### tp_properties_mixin_change_value ()

    void                tp_properties_mixin_change_value    (GObject *obj,
                                                             guint prop_id,
                                                             const GValue *new_value,
                                                             TpIntset *props);

Change the value of the given property ID in response to a server state change.

If the old and new values match, nothing happens; no signal is emitted and `props` is ignored. Otherwise, the following applies:

If `props` is `NULL` the PropertiesChanged signal is emitted for this one property.

Otherwise, the property ID is added to the set; the caller is responsible for passing the set to `tp_properties_mixin_emit_changed()` once a batch of properties have been changed.

`obj` : | An object with the properties mixin
`prop_id` : | A property ID on which to act
`new_value` : | Property value
`props` : | either `NULL`, or a pointer to a TpIntset

### tp_properties_mixin_change_flags ()

    void                tp_properties_mixin_change_flags    (GObject *obj,
                                                             guint prop_id,
                                                             TpPropertyFlags add,
                                                             TpPropertyFlags del,
                                                             TpIntset *props);

Change the flags for the given property ID in response to a server state change.

Flags removed by `del` override flags added by `add`. This should not be relied upon.

If `props` is `NULL` the PropertyFlagsChanged signal is emitted for this single property.

Otherwise, the property ID is added to the set; the caller is responsible for passing the set to `tp_properties_mixin_emit_flags()` once a batch of properties have been changed.

`obj` : | An object with the properties mixin
`prop_id` : | A property ID on which to act
`add` : | Property flags to be added via bitwise OR
`del` : | Property flags to be removed via bitwise AND
`props` : | either `NULL`, or a pointer to a TpIntset

### tp_properties_mixin_emit_changed ()

    void                tp_properties_mixin_emit_changed    (GObject *obj,
                                                             const TpIntset *props);

Emit the PropertiesChanged signal to indicate that the values of the given property IDs have changed; the actual values are automatically added using their stored values.

`obj` : | an object with the properties mixin
`props` : | a set of property IDs

### tp_properties_mixin_emit_flags ()

    void                tp_properties_mixin_emit_flags      (GObject *obj,
                                                             const TpIntset *props);

Emit the PropertyFlagsChanged signal to indicate that the flags of the given property IDs have changed; the actual flags are automatically added using their stored values.

`obj` : | an object with the properties mixin
`props` : | a set of property IDs

### tp_properties_mixin_is_readable ()

    gboolean            tp_properties_mixin_is_readable     (GObject *obj,
                                                             guint prop_id);

`obj` : | an object with this mixin
`prop_id` : | an integer property ID
Returns : | `TRUE` if the given property has the READ flag

### tp_properties_mixin_is_writable ()

    gboolean            tp_properties_mixin_is_writable     (GObject *obj,
                                                             guint prop_id);

`obj` : | an object with this mixin
`prop_id` : | an integer property ID
Returns : | `TRUE` if the given property has the WRITE flag

### tp_properties_mixin_iface_init ()

    void                tp_properties_mixin_iface_init      (gpointer g_iface,
                                                             gpointer iface_data);

Fill in this mixin's method implementations in the given interface vtable. This function should usually be called via G_IMPLEMENT_INTERFACE inside the G_DEFINE_TYPE_WITH_CODE macro.

`g_iface` : | A pointer to the TpSvcPropertiesInterfaceClass in an object class
`iface_data` : | Ignored

### TP_TYPE_PROPERTY_INFO_STRUCT

    #define TP_TYPE_PROPERTY_INFO_STRUCT TP_STRUCT_TYPE_PROPERTY_SPEC

The GType of the structures with D-Bus signature '(ussu)' returned by ListProperties.

`Deprecated`: Since 0.7.0. Use TP_STRUCT_TYPE_PROPERTY_SPEC instead.

### TP_TYPE_PROPERTY_INFO_LIST

    #define TP_TYPE_PROPERTY_INFO_LIST TP_ARRAY_TYPE_PROPERTY_SPEC_LIST

The GType of the return from ListProperties (i.e. a GPtrArray of structures of type TP_TYPE_PROPERTY_INFO_STRUCT), corresponding to D-Bus signature 'a(ussu)'.

`Deprecated`: Since 0.7.0. Use TP_ARRAY_TYPE_PROPERTY_SPEC_LIST instead.

### TP_TYPE_PROPERTY_VALUE_STRUCT

    #define TP_TYPE_PROPERTY_VALUE_STRUCT TP_STRUCT_TYPE_PROPERTY_VALUE

The GType of the structures with signature '(uv)' returned by GetProperties and emitted in PropertiesChanged.

`Deprecated`: Since 0.7.0. Use TP_STRUCT_TYPE_PROPERTY_VALUE instead.

### TP_TYPE_PROPERTY_VALUE_LIST

    #define TP_TYPE_PROPERTY_VALUE_LIST TP_ARRAY_TYPE_PROPERTY_VALUE_LIST

The GType of the return from GetProperties and the parameter to PropertiesChanged (i.e. a GPtrArray of structures of type TP_TYPE_PROPERTY_VALUE_STRUCT), corresponding to D-Bus signature 'a(uv)'.

`Deprecated`: Since 0.7.0. Use TP_ARRAY_TYPE_PROPERTY_VALUE_LIST instead.

### TP_TYPE_PROPERTY_FLAGS_STRUCT

    #define TP_TYPE_PROPERTY_FLAGS_STRUCT TP_STRUCT_TYPE_PROPERTY_FLAGS_CHANGE

The GType of the structures with D-Bus signature '(uu)' emitted in PropertyFlagsChanged.

`Deprecated`: Since 0.7.0. Use TP_STRUCT_TYPE_PROPERTY_FLAGS_CHANGE instead.

### TP_TYPE_PROPERTY_FLAGS_LIST

    #define TP_TYPE_PROPERTY_FLAGS_LIST TP_ARRAY_TYPE_PROPERTY_FLAGS_CHANGE_LIST

The GType of the parameter to PropertyFlagsChanged (i.e. a GPtrArray of structures of type TP_TYPE_PROPERTY_FLAGS_STRUCT), corresponding to D-Bus signature 'a(uu)'.

`Deprecated`: Since 0.7.0. Use TP_ARRAY_TYPE_PROPERTY_FLAGS_CHANGE_LIST instead.

## See Also

TpSvcPropertiesInterface