EggDBusConnection

typedef struct _EggDBusConnection EggDBusConnection;

enum EggDBusCallFlags

typedef enum {
  EGG_DBUS_CALL_FLAGS_NONE = 0,
  EGG_DBUS_CALL_FLAGS_BLOCK_IN_MAINLOOP = (1<<0),
  EGG_DBUS_CALL_FLAGS_TIMEOUT_NONE = (1<<1),
} EggDBusCallFlags;

Flags used for sending messages.

enum EggDBusBusType

typedef enum {
  EGG_DBUS_BUS_TYPE_NONE,
  EGG_DBUS_BUS_TYPE_SESSION,
  EGG_DBUS_BUS_TYPE_SYSTEM,
  EGG_DBUS_BUS_TYPE_STARTER,
} EggDBusBusType;

egg_dbus_connection_get_for_bus ()

EggDBusConnection * egg_dbus_connection_get_for_bus     (EggDBusBusType bus_type);

Gets a connection to the bus specified by bus_type. Note that this connection is shared with other processes; use TODO() to get a private connection.

egg_dbus_connection_get_object_proxy ()

EggDBusObjectProxy * egg_dbus_connection_get_object_proxy
                                                        (EggDBusConnection *connection,
                                                         const gchar *name,
                                                         const gchar *object_path);

Gets a EggDBusObjectProxy that represents a remote object at object_path owned by name.

The returned object proxy can be used to obtain interface proxies for calling methods, listen to signals and read/write properties on the D-Bus interfaces supported by the remote object. See the EggDBusObjectProxy class for details.

This method never fails. If either name doesn't exist or it doesn't export an object at object_path, you won't find out until you start invoking messages on it. You can use egg_dbus_object_proxy_introspect() to find out if the remote object exists in addition to what D-Bus interfaces it supports.

Note that connection will track name and report changes via the "name-owner" property on the returned EggDBusObjectProxy object. To track changes to "name-owner", simply connect to the "notify" signal on the returned object.

egg_dbus_connection_get_bus ()

EggDBusBus *        egg_dbus_connection_get_bus         (EggDBusConnection *connection);

Gets the EggDBusBus interface proxy for the org.freedesktop.DBus interface of the message bus daemon for connection.

This interface proxy is typically used to claim a well-known name on the message bus or to listen for signals like "name-acquired" or "name-lost". For example, to claim the well-known name com.example.AwesomeProduct on the session message bus you would do this:

EggDBusConnection *connection;
EggDBusRequestNameReply request_name_reply;
GError *error;

connection = egg_dbus_connection_get_for_bus (EGG_DBUS_BUS_TYPE_SESSION);

error = NULL;
if (!egg_dbus_bus_request_name_sync (egg_dbus_connection_get_bus (connection),
                                     EGG_DBUS_CALL_FLAGS_NONE,
                                     "com.example.AwesomeProduct",
                                     EGG_DBUS_REQUEST_NAME_FLAGS_NONE,
                                     &request_name_reply,
                                     NULL,
                                     &error))
  {
    g_warning ("Error claiming com.example.AwesomeProduct on session bus: %s", error->message);
    g_error_free (error);
    goto error;
  }

if (request_name_reply != EGG_DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
  {
    g_warning ("Could not become primary owner of com.example.AwesomeProduct");
    goto error;
  }

/* We now own com.example.AwesomeProduct  */

egg_dbus_connection_get_unique_name ()

const gchar *       egg_dbus_connection_get_unique_name (EggDBusConnection *connection);

Gets the unique name (as assigned by the message bus daemon) of connection. This method can only be used when connection is a message bus connection.

egg_dbus_connection_register_interface ()

void                egg_dbus_connection_register_interface
                                                        (EggDBusConnection *connection,
                                                         const gchar *object_path,
                                                         GType interface_type,
                                                         ...);

Registers one or more D-Bus interfaces at object_path on connection. This function is only useful when exporting a D-Bus service.

This function may be called multiple times for the same object_path. If an existing GType for an interface is already registered, it will be replaced.

Only a weak reference to the given GObject instances will be taken; if a registered object is finalized it will automatically be unregistered. Use egg_dbus_connection_unregister_interface() to manually unregister the interface.

Note that the EggDBusProperties, EggDBusIntrospectable and EggDBusPeer interfaces will be automatically handled for object_path unless they specifically registered.

For objects with relatively simple D-Bus interfaces (where there are no name clashes on property and signal names), a single GObject derived class implementing multiple GInterfaces (each corresponding to a D-Bus interface) can be used. For more complex objects (with name clashes), separate GObject derived classes (typically one for each D-Bus interface) must be used for disambiguation.

egg_dbus_connection_register_interface_valist ()

void                egg_dbus_connection_register_interface_valist
                                                        (EggDBusConnection *connection,
                                                         const gchar *object_path,
                                                         GType interface_type,
                                                         va_list var_args);

Like egg_dbus_connection_register_interface() but intended for language bindings.

egg_dbus_connection_unregister_interface ()

void                egg_dbus_connection_unregister_interface
                                                        (EggDBusConnection *connection,
                                                         const gchar *object_path,
                                                         GType interface_type,
                                                         ...);

Unregisters one or more D-Bus interfaces at object_path on connection previously registered with egg_dbus_connection_register_interface(). This method is only useful when exporting a D-Bus service.

egg_dbus_connection_unregister_interface_valist ()

void                egg_dbus_connection_unregister_interface_valist
                                                        (EggDBusConnection *connection,
                                                         const gchar *object_path,
                                                         GType interface_type,
                                                         va_list var_args);

Like egg_dbus_connection_unregister_interface() but intended for language bindings.

egg_dbus_connection_lookup_interface ()

guint               egg_dbus_connection_lookup_interface
                                                        (EggDBusConnection *connection,
                                                         const gchar *object_path,
                                                         GType **out_interface_types,
                                                         GObject ***out_interface_stubs);

This method looks up the interfaces at object_path for connection registered using egg_dbus_connection_register_interface(). This method is only useful when exporting a D-Bus service.

egg_dbus_connection_new_message_for_signal ()

EggDBusMessage *    egg_dbus_connection_new_message_for_signal
                                                        (EggDBusConnection *connection,
                                                         const gchar *sender,
                                                         const gchar *destination,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         const gchar *signal_name);

Creates a new EggDBusMessage for sending a signal. This method is only useful for language bindings.

egg_dbus_connection_new_message_for_method_call ()

EggDBusMessage *    egg_dbus_connection_new_message_for_method_call
                                                        (EggDBusConnection *connection,
                                                         const gchar *sender,
                                                         const gchar *destination,
                                                         const gchar *object_path,
                                                         const gchar *interface_name,
                                                         const gchar *method_name);

Creates a new EggDBusMessage for invoking a method. This method is only useful for language bindings.

egg_dbus_connection_send_message ()

void                egg_dbus_connection_send_message    (EggDBusConnection *connection,
                                                         EggDBusMessage *message);

Sends message on connection without waiting for a reply. This method is only useful for language bindings.

egg_dbus_connection_send_message_with_reply ()

guint               egg_dbus_connection_send_message_with_reply
                                                        (EggDBusConnection *connection,
                                                         EggDBusCallFlags call_flags,
                                                         EggDBusMessage *message,
                                                         GType *error_types,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Queues message to be sent and invokes callback (on the main thread) when there is a reply. This method is only useful for language bindings.

In callback, egg_dbus_connection_send_message_with_reply_finish() should be used to extract the reply or error.

egg_dbus_connection_send_message_with_reply_finish ()

EggDBusMessage *    egg_dbus_connection_send_message_with_reply_finish
                                                        (EggDBusConnection *connection,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes sending a message where a reply is requested.

egg_dbus_connection_send_message_with_reply_sync ()

EggDBusMessage *    egg_dbus_connection_send_message_with_reply_sync
                                                        (EggDBusConnection *connection,
                                                         EggDBusCallFlags call_flags,
                                                         EggDBusMessage *message,
                                                         GType *error_types,
                                                         GCancellable *cancellable,
                                                         GError **error);

Queues message to be sent and waits until a reply arrives. This method is only useful for language bindings.

egg_dbus_connection_pending_call_cancel ()

void                egg_dbus_connection_pending_call_cancel
                                                        (EggDBusConnection *connection,
                                                         guint pending_call_id);

Cancels an asynchronous method invocation expecting a reply. The GAsyncReadyCallback callback given to egg_dbus_connection_send_message_with_reply() will be invoked before this function returns.

egg_dbus_connection_pending_call_block ()

void                egg_dbus_connection_pending_call_block
                                                        (EggDBusConnection *connection,
                                                         guint pending_call_id);

Blocks until the asynchronous method invocation with pending_call_id completes. The GAsyncReadyCallback callback given to egg_dbus_connection_send_message_with_reply() will be invoked before this function returns.

Depending on how the call was issued (e.g. what set of EggDBusCallFlags was passed), this function may use a recursive GMainLoop for blocking.

The "bus-type" property

  "bus-type"                 EggDBusBusType        : Read / Write / Construct Only

Type of the bus we are connected to, if any.

Default value: EGG_DBUS_BUS_TYPE_NONE

The "unique-name" property

  "unique-name"              gchar*                : Read

The unique name as assigned by the message bus.

Default value: NULL