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
Generated by GTK-Doc V1.19