telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description |
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 of the property as seen in the Telepathy D-Bus protocol |
GType |
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 * |
The value of the property |
guint |
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
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 * |
Array of property values, of length klass->num_props. Should be considered read-only. |
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 * |
Array of property signatures, as provided via
tp_properties_mixin_class_init() , of length num_props . |
guint |
Number of properties supported. |
TpPropertiesSetFunc |
Properties setting function, as supplied to
tp_properties_mixin_class_init() . |
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)); |
|
The class of an object that has this mixin |
|
The offset of the TpPropertiesMixinClass structure in the class structure |
|
An array of property signatures |
|
The number of entries in signatures
|
|
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); |
|
An object that has this mixin |
|
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.
|
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.
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.
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.
|
An object with this mixin |
|
An array of D-Bus structures containing property ID and value |
|
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
);
tp_properties_context_has ()
gboolean tp_properties_context_has (TpPropertiesContext *ctx
,guint property
);
|
the properties context representing a SetProperties call |
|
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
);
|
the properties context representing a SetProperties call |
|
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
);
|
the properties context representing a SetProperties call |
|
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
);
|
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.
|
the properties context representing a SetProperties call |
|
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.
|
the properties context representing a SetProperties call |
|
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.
|
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.
|
An object with the properties mixin |
|
A property ID on which to act |
|
Property value |
|
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.
|
An object with the properties mixin |
|
A property ID on which to act |
|
Property flags to be added via bitwise OR |
|
Property flags to be removed via bitwise AND |
|
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.
|
an object with the properties mixin |
|
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.
|
an object with the properties mixin |
|
a set of property IDs |
tp_properties_mixin_is_readable ()
gboolean tp_properties_mixin_is_readable (GObject *obj
,guint prop_id
);
|
an object with this mixin |
|
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
);
|
an object with this mixin |
|
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.
|
A pointer to the TpSvcPropertiesInterfaceClass in an object class |
|
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.