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);