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