manpagez: man pages & more
html files: eggdbus
Home | html | info | man

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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.