EggDBusInterface

EggDBusInterface — Encapsulates a D-Bus interface

Synopsis

                    EggDBusInterface;
                    EggDBusInterfaceIface;
enum                EggDBusInterfacePropertyInfoFlags;
                    EggDBusInterfaceAnnotationInfo;
                    EggDBusInterfaceArgInfo;
                    EggDBusInterfaceMethodInfo;
                    EggDBusInterfaceSignalInfo;
                    EggDBusInterfacePropertyInfo;
                    EggDBusInterfaceInfo;
                    EggDBusInterfaceNodeInfo;
const gchar *       egg_dbus_interface_annotation_info_lookup
                                                        (const EggDBusInterfaceAnnotationInfo *annotations,
                                                         const gchar *annotation_name);
const EggDBusInterfaceSignalInfo * egg_dbus_interface_info_lookup_signal_for_g_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *g_name);
const EggDBusInterfacePropertyInfo * egg_dbus_interface_info_lookup_property_for_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *name);
const EggDBusInterfacePropertyInfo * egg_dbus_interface_info_lookup_property_for_g_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *g_name);
EggDBusInterfaceNodeInfo * egg_dbus_interface_new_node_info_from_xml
                                                        (const gchar *xml_data,
                                                         GError **error);
void                egg_dbus_interface_node_info_free   (EggDBusInterfaceNodeInfo *node_info);
void                egg_dbus_interface_info_to_xml      (const EggDBusInterfaceInfo *info,
                                                         guint indent,
                                                         GString *string_builder);
void                egg_dbus_interface_node_info_to_xml (const EggDBusInterfaceNodeInfo *node_info,
                                                         guint indent,
                                                         GString *string_builder);
GType *             egg_dbus_bindings_get_error_domain_types
                                                        (void);

Object Hierarchy

  GInterface
   +----EggDBusInterface

Description

The EggDBusInterface interface is used for describing remote D-Bus interfaces and dispatching messages.

Details

EggDBusInterface

typedef struct _EggDBusInterface EggDBusInterface;

EggDBusInterfaceIface

typedef struct {
  GTypeInterface g_iface;

  const EggDBusInterfaceInfo * (*get_interface_info)  (void);

  void                         (*handle_message)      (EggDBusInterface    *interface,
                                                       EggDBusMessage      *message);

  EggDBusInterfaceProxy *      (*get_interface_proxy) (EggDBusObjectProxy  *object_proxy);
} EggDBusInterfaceIface;

VTable for EggDBusInterface. This GInterface is used for both interface proxies (on the client side) and when exporting D-Bus interfaces (on the server side).

When exporting a D-Bus interface (using egg_dbus_connection_register_interface()), simply provide GObject derived instance that implement this interface.

You need to implement the get_interface_info vfunc to describe what the D-Bus interface looks like (this is designed to be stored in read-only data) as well as how D-Bus signal and property names (typically CamelCase) are mapped to GObject signal and property names (typically lowercase using hyphens).

Incoming method calls are dispatched through the handle_message vfunc, D-Bus properties are get/set through the get_property() / set_property() vfuncs on the GObject class and emitted GObject signals (that matches D-Bus signals) are broadcast on the EggDBusConnection instance(s) that the exported D-Bus interface have been registered with.

Implementing the get_interface_proxy vfunc is optional. Typically language bindings for static languages (such as C or C++) wants to implement this vfunc to provide a type-safe client-side API for accessing the D-Bus interface. If implemented, then D-Bus signals received on the client-side will be propagated from EggDBusConnection through EggDBusObjectProxy to the handle_message vfunc. Typically, implementations will want to turn the EggDBusMessage into a GObject signal.

GTypeInterface `g_iface`;	Parent interface.
`get_interface_info` ()	Gets introspection information about the interface.
`handle_message` ()	Handle an incoming message for an interface. This is used for both dispatching signals for proxies and for handling method calls invocations originating from remote processes.
`get_interface_proxy` ()	Gets an interface proxy that can be used to access the D-Bus interface for the remote object represented by the given EggDBusObjectProxy object. The returned instance must be derived from EggDBusInterfaceProxy and must implement the given interface.

enum EggDBusInterfacePropertyInfoFlags

typedef enum
{
  EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_NONE = 0,
  EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_READABLE = (1<<0),
  EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_WRITABLE = (1<<1),
} EggDBusInterfacePropertyInfoFlags;

Flags describing the access control of a D-Bus property.

`EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_NONE`	No flags set.
`EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_READABLE`	Property is readable.
`EGG_DBUS_INTERFACE_PROPERTY_INFO_FLAGS_WRITABLE`	Property is writable.

EggDBusInterfaceAnnotationInfo

typedef struct {
  const gchar                           *key;
  const gchar                           *value;
  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceAnnotationInfo;

Information about an annotation.

By convention, an array of annotations is always terminated by an element where key is NULL.

const gchar *`key`;	The name of the annotation, e.g. `org.freedesktop.DBus.Deprecated`
const gchar *`value`;	The value of the annotation.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the annotation or `NULL` if there are no annotations.

EggDBusInterfaceArgInfo

typedef struct {
  const gchar                           *name;
  const gchar                           *signature;
  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceArgInfo;

Information about an argument for a method or a signal.

const gchar *`name`;	Name of the argument, e.g. `unix_user_id`.
const gchar *`signature`;	D-Bus signature of the argument (a single complete type).
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the argument or `NULL` if there are no annotations.

EggDBusInterfaceMethodInfo

typedef struct {
  const gchar                           *name;

  const gchar                           *in_signature;
  guint                                  in_num_args;
  const EggDBusInterfaceArgInfo         *in_args;

  const gchar                           *out_signature;
  guint                                  out_num_args;
  const EggDBusInterfaceArgInfo         *out_args;

  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceMethodInfo;

Information about a method on an D-Bus interface.

const gchar *`name`;	The name of the D-Bus method, e.g. `RequestName`.
const gchar *`in_signature`;	The combined D-Bus signature of all arguments passed to the method (`in_num_args` complete types).
guint `in_num_args`;	Number of arguments passed to the method.
const EggDBusInterfaceArgInfo *`in_args`;	A pointer to an array of `in_num_args` EggDBusInterfaceArgInfo structures or `NULL` if `in_num_args` is 0.
const gchar *`out_signature`;	The combined D-Bus signature of all arguments the method returns (`out_num_args` complete types).
guint `out_num_args`;	Number of arguments the method returns.
const EggDBusInterfaceArgInfo *`out_args`;	A pointer to an array of `out_num_args` EggDBusInterfaceArgInfo structures or `NULL` if `out_num_args` is 0.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the method or `NULL` if there are no annotations.

EggDBusInterfaceSignalInfo

typedef struct {
  const gchar                           *name;
  const gchar                           *g_name;

  const gchar                           *signature;
  guint                                  num_args;
  const EggDBusInterfaceArgInfo         *args;

  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceSignalInfo;

Information about a signal on a D-Bus interface.

const gchar *`name`;	The name of the D-Bus signal, e.g. `NameOwnerChanged`.
const gchar *`g_name`;	The GObject name of the D-Bus signal (in lower case with hyphens), e.g. name-owner-changed.
const gchar *`signature`;	The combined D-Bus signature of all arguments of the signal (`num_args` complete types).
guint `num_args`;	Number of arguments of the signal.
const EggDBusInterfaceArgInfo *`args`;	A pointer to an array of `num_args` EggDBusInterfaceArgInfo structures or `NULL` if `num_args` is 0.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the signal or `NULL` if there are no annotations.

EggDBusInterfacePropertyInfo

typedef struct {
  const gchar                           *name;
  const gchar                           *g_name;
  const gchar                           *signature;
  EggDBusInterfacePropertyInfoFlags      flags;
  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfacePropertyInfo;

Information about a D-Bus property on a D-Bus interface.

const gchar *`name`;	The name of the D-Bus property, e.g. `SupportedFilesystems`.
const gchar *`g_name`;	The GObject name of the D-Bus property (in lower case with hyphens), e.g. supported-filesystems.
const gchar *`signature`;	The D-Bus signature of the property (a single complete type).
EggDBusInterfacePropertyInfoFlags `flags`;	Access control flags for the property.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the property or `NULL` if there are no annotations.

EggDBusInterfaceInfo

typedef struct {
  const gchar                           *name;

  guint                                  num_methods;
  const EggDBusInterfaceMethodInfo      *methods;

  guint                                  num_signals;
  const EggDBusInterfaceSignalInfo      *signals;

  guint                                  num_properties;
  const EggDBusInterfacePropertyInfo    *properties;

  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceInfo;

Information about a D-Bus interface.

const gchar *`name`;	The name of the D-Bus interface, e.g. `org.freedesktop.DBus.Properties`.
guint `num_methods`;	Number of methods on the interface.
const EggDBusInterfaceMethodInfo *`methods`;	A pointer to an array of `num_methods` EggDBusInterfaceMethodInfo structures or `NULL` if `num_methods` is 0.
guint `num_signals`;	Number of signals on the interface.
const EggDBusInterfaceSignalInfo *`signals`;	A pointer to an array of `num_signals` EggDBusInterfaceSignalInfo structures or `NULL` if `num_signals` is 0.
guint `num_properties`;	Number of properties on the interface.
const EggDBusInterfacePropertyInfo *`properties`;	A pointer to an array of `num_properties` EggDBusInterfacePropertyInfo structures or `NULL` if `num_properties` is 0.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the interface or `NULL` if there are no annotations.

EggDBusInterfaceNodeInfo

typedef struct {
  const gchar                           *path;

  guint                                  num_interfaces;
  const EggDBusInterfaceInfo            *interfaces;

  guint                                  num_nodes;
  const EggDBusInterfaceNodeInfo        *nodes;

  const EggDBusInterfaceAnnotationInfo  *annotations;
} EggDBusInterfaceNodeInfo;

Information about nodes in a remote object hierarchy.

const gchar *`path`;	The path of the node or `NULL` if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
guint `num_interfaces`;	Number of interfaces of the node.
const EggDBusInterfaceInfo *`interfaces`;	A pointer to an array of `num_interfaces` EggDBusInterfaceInfo structures or `NULL` if `num_interfaces` is 0.
guint `num_nodes`;	Number of child nodes.
const EggDBusInterfaceNodeInfo *`nodes`;	A pointer to an array of `num_nodes` EggDBusInterfaceNodeInfo structures or `NULL` if `num_nodes` is 0.
const EggDBusInterfaceAnnotationInfo *`annotations`;	A pointer to an array of annotations for the node or `NULL` if there are no annotations.

egg_dbus_interface_annotation_info_lookup ()

const gchar *       egg_dbus_interface_annotation_info_lookup
                                                        (const EggDBusInterfaceAnnotationInfo *annotations,
                                                         const gchar *annotation_name);

Looks up the value of an annotation.

`annotations` :	An array of annotations.
`annotation_name` :	The name of the annotation to look up.
Returns :	A string. Do not free, it is owned by `annotations`.

egg_dbus_interface_info_lookup_signal_for_g_name ()

const EggDBusInterfaceSignalInfo * egg_dbus_interface_info_lookup_signal_for_g_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *g_name);

Looks up information about a signal.

`info` :	A EggDBusInterfaceInfo.
`g_name` :	A GObject signal name (lower case with hyphens)
Returns :	A EggDBusInterfaceSignalInfo. Do not free, it is owned by `info`.

egg_dbus_interface_info_lookup_property_for_name ()

const EggDBusInterfacePropertyInfo * egg_dbus_interface_info_lookup_property_for_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *name);

Looks up information about a property.

`info` :	A EggDBusInterfaceInfo.
`name` :	A D-Bus property name (typically in CamelCase).
Returns :	A EggDBusInterfacePropertyInfo. Do not free, it is owned by `info`.

egg_dbus_interface_info_lookup_property_for_g_name ()

const EggDBusInterfacePropertyInfo * egg_dbus_interface_info_lookup_property_for_g_name
                                                        (const EggDBusInterfaceInfo *info,
                                                         const gchar *g_name);

Looks up information about a property.

`info` :	A EggDBusInterfaceInfo.
`g_name` :	A GObject property name (e.g. lower case with hyphens).
Returns :	A EggDBusInterfacePropertyInfo. Do not free, it is owned by `info`.

egg_dbus_interface_new_node_info_from_xml ()

EggDBusInterfaceNodeInfo * egg_dbus_interface_new_node_info_from_xml
                                                        (const gchar *xml_data,
                                                         GError **error);

Parses xml_data and returns a EggDBusInterfaceNodeInfo representing the data.

`xml_data` :	Valid D-Bus introspection XML.
`error` :	Return location for error.
Returns :	A EggDBusInterfaceNodeInfo structure or `NULL` if `error` is set. Free with `egg_dbus_interface_node_info_free()`.

egg_dbus_interface_node_info_free ()

void                egg_dbus_interface_node_info_free   (EggDBusInterfaceNodeInfo *node_info);

Frees node_info. This is a deep free, all nodes of node_info and it's children will be freed as well.

node_info :

A EggDBusInterfaceNodeInfo.

egg_dbus_interface_info_to_xml ()

void                egg_dbus_interface_info_to_xml      (const EggDBusInterfaceInfo *info,
                                                         guint indent,
                                                         GString *string_builder);

Appends an XML representation of info (and it's children) to string_builder.

This function is typically used for generating introspection XML documents at run-time for handling the org.freedesktop.DBus.Introspectable.Introspect method.

`info` :	A EggDBusInterfaceInfo.
`indent` :	Indentation level.
`string_builder` :	A GString to to append XML data to.

egg_dbus_interface_node_info_to_xml ()

void                egg_dbus_interface_node_info_to_xml (const EggDBusInterfaceNodeInfo *node_info,
                                                         guint indent,
                                                         GString *string_builder);

Appends an XML representation of node_info (and it's children) to string_builder.

This function is typically used for generating introspection XML documents at run-time for handling the org.freedesktop.DBus.Introspectable.Introspect method.

`node_info` :	A EggDBusInterfaceNodeInfo.
`indent` :	Indentation level.
`string_builder` :	A GString to to append XML data to.

egg_dbus_bindings_get_error_domain_types ()

GType *             egg_dbus_bindings_get_error_domain_types
                                                        (void);

			EggDBus Reference Manual
Top \| Description \| Object Hierarchy