![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
#include <telepathy-glib/properties-mixin.h> TpPropertySignature; TpProperty; TpPropertiesContext; gboolean (*TpPropertiesSetFunc) (GObject *obj, TpPropertiesContext *ctx, GError **error); TpPropertiesMixin; 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
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
.
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'.
|
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 |
typedef struct _TpPropertiesContext TpPropertiesContext;
Opaque pointer representing an incomplete property-setting operation, used in the implementation of SetProperties.
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
|
typedef struct { TpProperty *properties; TpPropertiesMixinPrivate *priv; } TpPropertiesMixin;
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. |
typedef struct { const TpPropertySignature *signatures; guint num_props; TpPropertiesSetFunc set_properties; TpPropertiesMixinClassPrivate *priv; } TpPropertiesMixinClass;
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. |
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:
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 |
void tp_properties_mixin_init (GObject *obj, glong offset);
Initialize the mixin. Should be called from the implementation's instance init function like so:
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 |
void tp_properties_mixin_finalize (GObject *obj);
Free memory used by the TpPropertiesMixin.
obj : |
An object that has this mixin |
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
|
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
|
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 |
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
|
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.
|
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
|
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)
|
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
|
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 |
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
|
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.
|
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
|
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
|
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 |
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 |
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
|
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
|
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 |
#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.
#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.
#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.
#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.
#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.
#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.