## EggDBusConnection EggDBusConnection — Connection |

## Synopsis

                        EggDBusConnection;
    enum                EggDBusCallFlags;
    enum                EggDBusBusType;
    EggDBusConnection * egg_dbus_connection_get_for_bus     (EggDBusBusType bus_type);
    EggDBusObjectProxy * egg_dbus_connection_get_object_proxy
                                                            (EggDBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *object_path);
    EggDBusBus *        egg_dbus_connection_get_bus         (EggDBusConnection *connection);
    const gchar *       egg_dbus_connection_get_unique_name (EggDBusConnection *connection);
    void                egg_dbus_connection_register_interface
                                                            (EggDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GType interface_type,
                                                             ...);
    void                egg_dbus_connection_register_interface_valist
                                                            (EggDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GType interface_type,
                                                             va_list var_args);
    void                egg_dbus_connection_unregister_interface
                                                            (EggDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GType interface_type,
                                                             ...);
    void                egg_dbus_connection_unregister_interface_valist
                                                            (EggDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GType interface_type,
                                                             va_list var_args);
    guint               egg_dbus_connection_lookup_interface
                                                            (EggDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GType **out_interface_types,
                                                             GObject ***out_interface_stubs);
    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);
    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);
    void                egg_dbus_connection_send_message    (EggDBusConnection *connection,
                                                             EggDBusMessage *message);
    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);
    EggDBusMessage *    egg_dbus_connection_send_message_with_reply_finish
                                                            (EggDBusConnection *connection,
                                                             GAsyncResult *res,
                                                             GError **error);
    EggDBusMessage *    egg_dbus_connection_send_message_with_reply_sync
                                                            (EggDBusConnection *connection,
                                                             EggDBusCallFlags call_flags,
                                                             EggDBusMessage *message,
                                                             GType *error_types,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                egg_dbus_connection_pending_call_cancel
                                                            (EggDBusConnection *connection,
                                                             guint pending_call_id);
    void                egg_dbus_connection_pending_call_block
                                                            (EggDBusConnection *connection,
                                                             guint pending_call_id);

## Object Hierarchy

      GObject
       +----EggDBusConnection

## Properties

      "bus-type"                 EggDBusBusType        : Read / Write / Construct Only
      "unique-name"              gchar*                : Read

## Description

The EggDBusConnection class is used to connect to other processes or message buses.

## Details

### 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.

`EGG_DBUS_CALL_FLAGS_NONE` | No flags set.
`EGG_DBUS_CALL_FLAGS_BLOCK_IN_MAINLOOP` | When doing a synchronous call, block in a main loop instead of waiting for the reply to arrive (which reorders and queues up other messages for delivery after the reply have been processed). Be careful using this option, it may mean that your call site will have to handle reentrancy.
`EGG_DBUS_CALL_FLAGS_TIMEOUT_NONE` | Wait indefinitely instead of using the default timeout.

### 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.

`bus_type` : | The type of bus to get a connection for.
Returns : | A EggDBusConnection. Free with `g_object_unref()`.

### 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.

`connection` : | A EggDBusConnection.
`name` : | A message bus name such as `:1.6` or `org.freedesktop.DeviceKit`.
`object_path` : | An object path such as `/org/freedesktop/DeviceKit`.
Returns : | A EggDBusObjectProxy object. Free with `g_object_unref()`.

### 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  */

`connection` : | A EggDBusConnection.
Returns : | A EggDBusBus. Do not free this object, it is owned by `connection`.

### 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.

`connection` : | A EggDBusConnection.
Returns : | A unique bus name such as `:1.42`. Do not free this string, it is owned by `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.

`connection` : | A EggDBusConnection.
`object_path` : | The object path to register the interface on.
`interface_type` : | A GType for the type of GInterface that represents the D-Bus interface to be registered.
`...` : | A GObject derived instance implementing `interface_type`, followed by more `(type, instance pairs)`, terminated by G_TYPE_INVALID.

### 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.

`connection` : | A EggDBusConnection.
`object_path` : | The object path to register the interface on.
`interface_type` : | A GType for the type of GInterface that represents the D-Bus interface to be registered.
`var_args` : | A va_list containing a GObject derived instance implementing `interface_type`, followed by more `(type, instance pairs)`, terminated by G_TYPE_INVALID.

### 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.

`connection` : | A EggDBusConnection.
`object_path` : | The object path to unregister the interface from.
`interface_type` : | A GType for the type of GInterface that represents the D-Bus interface to be unregistered.
`...` : | Zero or more GTypes (like `interface_type`), terminated by G_TYPE_INVALID.

### 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.

`connection` : | A EggDBusConnection.
`object_path` : | The object path to unregister the interface from.
`interface_type` : | A GType for the type of GInterface that represents the D-Bus interface to be unregistered.
`var_args` : | A va_list with zero or more GTypes (like `interface_type`), terminated by G_TYPE_INVALID.

### 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.

`connection` : | A EggDBusConnection.
`object_path` : | The object path to lookup registered interfaces for.
`out_interface_types` : | Return location for the GInterface types registered at `object_path` or `NULL`.
`out_interface_stubs` : | Return location for the GObject derived instances implementing the corresponding GInterface or `NULL`.
Returns : | Number of interfaces registered at `object_path`. If zero is returned `out_interface_types` and `out_interface_stubs` will be set to `NULL`. Otherwise caller must free both of these arrays using `g_free()`.

### 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.

`connection` : | A EggDBusConnection.
`sender` : | Sender of the signal or `NULL` to use unique name for `connection`.
`destination` : | Destination of signal or `NULL` to multi-cast to all recipients on the bus.
`object_path` : | The object path to broadcast the signal on.
`interface_name` : | The interface name to which `signal_name` belongs.
`signal_name` : | Name of the signal to broadcast.
Returns : | A new EggDBusMessage. Free with `g_object_unref()`.

### 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.

`connection` : | A EggDBusConnection.
`sender` : | Sender of the message or `NULL` to use unique name for `connection`.
`destination` : | Destination of name to invoke method on.
`object_path` : | The object to invoke the method on.
`interface_name` : | The interface name to which `method_name` belongs.
`method_name` : | The name of the method to invoke.
Returns : | A new EggDBusMessage. Free with `g_object_unref()`.

### 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.

`connection` : | A EggDBusConnection.
`message` : | A EggDBusMessage.

### 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.

`connection` : | A EggDBusConnection.
`call_flags` : | Flags from EggDBusCallFlags detailing how the message should be sent.
`message` : | The message to send.
`error_types` : | Either `NULL` or a G_TYPE_INVALID terminated list of GTypes for GError error domains to use when processing an error reply.
`cancellable` : | A GCancellable or `NULL`.
`callback` : | Callback when the asynchronous operation finishes.
`user_data` : | User data to pass to `callback`.
Returns : | A pending call id (never zero) that can be used with `egg_dbus_connection_pending_call_cancel()` or `egg_dbus_connection_pending_call_block()`.

### 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.

`connection` : | A EggDBusConnection.
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback function passed to `egg_dbus_connection_send_message_with_reply()`.
`error` : | Return location for error.
Returns : | A EggDBusMessage or `NULL` if `error` is set.

### 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.

`connection` : | A EggDBusConnection.
`call_flags` : | Flags from EggDBusCallFlags detailing how the message should be sent.
`message` : | The message to send.
`error_types` : | Either `NULL` or a G_TYPE_INVALID terminated list of GTypes for GError error domains to use when processing an error reply.
`cancellable` : | A GCancellable or `NULL`.
`error` : | Return location for error.
Returns : | The reply or `NULL` if `error` is set.

### 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.

`connection` : | A EggDBusConnection.
`pending_call_id` : | A valid pending call id obtained from `egg_dbus_connection_send_message_with_reply()` or similar wrapper functions (such as `egg_dbus_bus_request_name()`).

### 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.

`connection` : | A EggDBusConnection.
`pending_call_id` : | A valid pending call id obtained from `egg_dbus_connection_send_message_with_reply()` or similar wrapper functions (such as `egg_dbus_bus_request_name()`).

## Property Details

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