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