EggDBusInterface

EggDBusInterface — Encapsulates a D-Bus interface

Functions

Types and Values

Object Hierarchy

    GFlags
    ╰── EggDBusInterfacePropertyInfoFlags
    GInterface
    ╰── EggDBusInterface

Description

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

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Types and Values

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.

Members

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

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

Members

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.

Members

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.

Members

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.

Members

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.

Members

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.

Members

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.

Members

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.

Members

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.