TpPropertiesMixin: telepathy-glib API Reference Manual

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

## Functions

gboolean | (*TpPropertiesSetFunc) ()
void | tp_properties_mixin_class_init ()
void | tp_properties_mixin_init ()
void | tp_properties_mixin_finalize ()
gboolean | tp_properties_mixin_list_properties ()
gboolean | tp_properties_mixin_get_properties ()
void | tp_properties_mixin_set_properties ()
gboolean | tp_properties_mixin_has_property ()
gboolean | tp_properties_context_has ()
gboolean | tp_properties_context_has_other_than ()
const GValue * | tp_properties_context_get ()
guint | tp_properties_context_get_value_count ()
void | tp_properties_context_remove ()
void | tp_properties_context_return ()
gboolean | tp_properties_context_return_if_done ()
void | tp_properties_mixin_change_value ()
void | tp_properties_mixin_change_flags ()
void | tp_properties_mixin_emit_changed ()
void | tp_properties_mixin_emit_flags ()
gboolean | tp_properties_mixin_is_readable ()
gboolean | tp_properties_mixin_is_writable ()
void | tp_properties_mixin_iface_init ()

## Types and Values

| TpPropertySignature
| TpProperty
| TpPropertiesContext
struct | TpPropertiesMixin
struct | TpPropertiesMixinClass
#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

## Includes

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

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

## Functions

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

#### Parameters

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

### 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));

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

## Types and Values

### TpPropertySignature

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

Signature of a property in the Telepathy properties interface.

#### Members

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.

#### Members

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.

### 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()`.

#### Members

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.

#### Members

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