![]() |
![]() |
![]() |
EggDBus Reference Manual | ![]() |
---|---|---|---|---|
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);
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.
typedef enum { EGG_DBUS_BUS_TYPE_NONE, EGG_DBUS_BUS_TYPE_SESSION, EGG_DBUS_BUS_TYPE_SYSTEM, EGG_DBUS_BUS_TYPE_STARTER, } EggDBusBusType;
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() .
|
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() .
|
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 .
|
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 .
|
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.
|
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.
|
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.
|
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.
|
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() .
|
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() .
|
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() .
|
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. |
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() .
|
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.
|
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.
|
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() ).
|
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() ).
|
"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