![]() |
![]() |
![]() |
D-Bus GLib bindings - Reference Manual | ![]() |
---|---|---|---|---|
DBusGProxy; DBusGProxy* dbus_g_proxy_new_for_name (DBusGConnection *connection, const char *name, const char *path, const char *interface); DBusGProxy* dbus_g_proxy_new_for_name_owner (DBusGConnection *connection, const char *name, const char *path, const char *interface, GError **error); DBusGProxy* dbus_g_proxy_new_from_proxy (DBusGProxy *proxy, const char *interface, const char *path_name); DBusGProxy* dbus_g_proxy_new_for_peer (DBusGConnection *connection, const char *path_name, const char *interface_name); void dbus_g_proxy_set_interface (DBusGProxy *proxy, const char *interface_name); const char* dbus_g_proxy_get_path (DBusGProxy *proxy); const char* dbus_g_proxy_get_bus_name (DBusGProxy *proxy); const char* dbus_g_proxy_get_interface (DBusGProxy *proxy); void dbus_g_proxy_add_signal (DBusGProxy *proxy, const char *signal_name, GType first_type, ...); void dbus_g_proxy_connect_signal (DBusGProxy *proxy, const char *signal_name, GCallback handler, void *data, GClosureNotify free_data_func); void dbus_g_proxy_disconnect_signal (DBusGProxy *proxy, const char *signal_name, GCallback handler, void *data); void dbus_g_proxy_send (DBusGProxy *proxy, DBusMessage *message, dbus_uint32_t *client_serial); gboolean dbus_g_proxy_call (DBusGProxy *proxy, const char *method, GError **error, GType first_arg_type, ...); gboolean dbus_g_proxy_call_with_timeout (DBusGProxy *proxy, const char *method, int timeout, GError **error, GType first_arg_type, ...); void dbus_g_proxy_call_no_reply (DBusGProxy *proxy, const char *method, GType first_arg_type, ...); DBusGProxyCall* dbus_g_proxy_begin_call (DBusGProxy *proxy, const char *method, DBusGProxyCallNotify notify, gpointer data, GDestroyNotify destroy, GType first_arg_type, ...); DBusGProxyCall* dbus_g_proxy_begin_call_with_timeout (DBusGProxy *proxy, const char *method, DBusGProxyCallNotify notify, gpointer user_data, GDestroyNotify destroy, int timeout, GType first_arg_type, ...); gboolean dbus_g_proxy_end_call (DBusGProxy *proxy, DBusGProxyCall *call, GError **error, GType first_arg_type, ...); void dbus_g_proxy_cancel_call (DBusGProxy *proxy, DBusGProxyCall *call); void dbus_g_proxy_set_default_timeout (DBusGProxy *proxy, int timeout);
DBusGProxy* dbus_g_proxy_new_for_name (DBusGConnection *connection, const char *name, const char *path, const char *interface);
Creates a new proxy for a remote interface exported by a connection
on a message bus. Method calls and signal connections over this
proxy will go to the name owner; the name's owner is expected to
support the given interface name. THE NAME OWNER MAY CHANGE OVER
TIME, for example between two different method calls, unless the
name is a unique name. If you need a fixed owner, you need to
request the current owner and bind a proxy to its unique name
rather than to the generic name; see
dbus_g_proxy_new_for_name_owner()
.
A name-associated proxy only makes sense with a message bus, not for app-to-app direct dbus connections.
This proxy will only emit the "destroy" signal if the DBusConnection is disconnected, the proxy has no remaining references, or the name is a unique name and its owner disappears. If a well-known name changes owner, the proxy will still be alive.
|
the connection to the remote bus |
|
any name on the message bus |
|
|
|
|
Returns : |
new proxy object |
DBusGProxy* dbus_g_proxy_new_for_name_owner (DBusGConnection *connection, const char *name, const char *path, const char *interface, GError **error);
Similar to dbus_g_proxy_new_for_name()
, but makes a round-trip
request to the message bus to get the current name owner, then
binds the proxy to the unique name of the current owner, rather
than to the well-known name. As a result, the name owner will
not change over time, and the proxy will emit the "destroy" signal
when the owner disappears from the message bus.
An example of the difference between dbus_g_proxy_new_for_name()
and dbus_g_proxy_new_for_name_owner()
: if you provide the well-known name
"org.freedesktop.Database" dbus_g_proxy_new_for_name()
remains bound
to that name as it changes owner. dbus_g_proxy_new_for_name_owner()
will fail if the name has no owner. If the name has an owner,
dbus_g_proxy_new_for_name_owner()
will bind to the unique name
of that owner rather than the generic name.
|
the connection to the remote bus |
|
any name on the message bus |
|
|
|
|
|
return location for an error |
Returns : |
new proxy object, or NULL on error |
DBusGProxy* dbus_g_proxy_new_from_proxy (DBusGProxy *proxy, const char *interface, const char *path_name);
Creates a proxy using an existing proxy as a template, substituting the specified interface and path. Either or both may be NULL.
|
the proxy to use as a template |
|
name of the interface to call methods on |
|
|
Returns : |
new proxy object |
DBusGProxy* dbus_g_proxy_new_for_peer (DBusGConnection *connection, const char *path_name, const char *interface_name);
Creates a proxy for an object in peer application (one we're directly connected to). That is, this function is intended for use when there's no message bus involved, we're doing a simple 1-to-1 communication between two applications.
|
the connection to the peer |
|
name of the object inside the peer to call methods on |
|
name of the interface to call methods on |
Returns : |
new proxy object |
void dbus_g_proxy_set_interface (DBusGProxy *proxy, const char *interface_name);
Sets the object interface proxy is bound to
|
the proxy |
|
an object interface |
const char* dbus_g_proxy_get_path (DBusGProxy *proxy);
|
the proxy |
Returns : |
an object path |
const char* dbus_g_proxy_get_bus_name (DBusGProxy *proxy);
Gets the bus name a proxy is bound to (may be NULL in some cases).
If you created the proxy with dbus_g_proxy_new_for_name()
, then
the name you passed to that will be returned.
If you created it with dbus_g_proxy_new_for_name_owner()
, then the
unique connection name will be returned. If you created it
with dbus_g_proxy_new_for_peer()
then NULL will be returned.
|
the proxy |
Returns : |
the bus name the proxy sends messages to |
const char* dbus_g_proxy_get_interface (DBusGProxy *proxy);
Gets the object interface proxy is bound to (may be NULL in some cases).
|
the proxy |
Returns : |
an object interface |
void dbus_g_proxy_add_signal (DBusGProxy *proxy, const char *signal_name, GType first_type, ...);
Specifies the argument signature of a signal;.only necessary if the remote object does not support introspection. The arguments specified are the GLib types expected.
|
the proxy for a remote interface |
|
the name of the signal |
|
the first argument type, or G_TYPE_INVALID if none |
|
void dbus_g_proxy_connect_signal (DBusGProxy *proxy, const char *signal_name, GCallback handler, void *data, GClosureNotify free_data_func);
Connect a signal handler to a proxy for a remote interface. When the remote interface emits the specified signal, the proxy will emit a corresponding GLib signal.
|
a proxy for a remote interface |
|
the DBus signal name to listen for |
|
the handler to connect |
|
data to pass to handler |
|
callback function to destroy data |
void dbus_g_proxy_disconnect_signal (DBusGProxy *proxy, const char *signal_name, GCallback handler, void *data);
Disconnect all signal handlers from a proxy that match the given criteria.
|
a proxy for a remote interface |
|
the DBus signal name to disconnect |
|
the handler to disconnect |
|
the data that was registered with handler |
void dbus_g_proxy_send (DBusGProxy *proxy, DBusMessage *message, dbus_uint32_t *client_serial);
Sends a message to the interface we're proxying for. Does not
block or wait for a reply. The message is only actually written out
when you return to the main loop or block in
dbus_connection_flush()
.
The message is modified to be addressed to the target interface.
That is, a destination name field or whatever is needed will be
added to the message. The basic point of this function is to add
the necessary header fields, otherwise it's equivalent to
dbus_connection_send()
.
This function adds a reference to the message, so the caller still owns its original reference.
|
a proxy for a remote interface |
|
the message to address and send |
|
return location for message's serial, or NULL |
gboolean dbus_g_proxy_call (DBusGProxy *proxy, const char *method, GError **error, GType first_arg_type, ...);
Function for synchronously invoking a method and receiving reply values. This function is equivalent to dbus_g_proxy_begin_call followed by dbus_g_proxy_end_call. All of the input arguments are specified first, followed by G_TYPE_INVALID, followed by all of the output values, followed by a second G_TYPE_INVALID. Note that this means you must always specify G_TYPE_INVALID twice.
gboolean dbus_g_proxy_call_with_timeout (DBusGProxy *proxy, const char *method, int timeout, GError **error, GType first_arg_type, ...);
Function for synchronously invoking a method and receiving reply values. This function is equivalent to dbus_g_proxy_begin_call followed by dbus_g_proxy_end_call. All of the input arguments are specified first, followed by G_TYPE_INVALID, followed by all of the output values, followed by a second G_TYPE_INVALID. Note that this means you must always specify G_TYPE_INVALID twice.
void dbus_g_proxy_call_no_reply (DBusGProxy *proxy, const char *method, GType first_arg_type, ...);
Sends a method call message as with dbus_g_proxy_begin_call()
, but
does not ask for a reply or allow you to receive one.
TODO: this particular function shouldn't die on out of memory, since you should be able to do a call with large arguments.
|
a proxy for a remote interface |
|
the name of the method to invoke |
|
type of the first argument |
|
DBusGProxyCall* dbus_g_proxy_begin_call (DBusGProxy *proxy, const char *method, DBusGProxyCallNotify notify, gpointer data, GDestroyNotify destroy, GType first_arg_type, ...);
Asynchronously invokes a method on a remote interface. The method
call will not be sent over the wire until the application returns
to the main loop, or blocks in dbus_connection_flush()
to write out
pending data. The call will be completed after a timeout, or when
a reply is received. When the call returns, the callback specified
will be invoked; you can then collect the results of the call
(which may be an error, or a reply), use dbus_g_proxy_end_call()
.
TODO this particular function shouldn't die on out of memory, since you should be able to do a call with large arguments.
|
a proxy for a remote interface |
|
the name of the method to invoke |
|
callback to be invoked when method returns |
|
|
|
function called to destroy user_data |
|
type of the first argument |
|
|
Returns : |
call identifier. |
DBusGProxyCall* dbus_g_proxy_begin_call_with_timeout (DBusGProxy *proxy, const char *method, DBusGProxyCallNotify notify, gpointer user_data, GDestroyNotify destroy, int timeout, GType first_arg_type, ...);
Asynchronously invokes a method on a remote interface. The method
call will not be sent over the wire until the application returns
to the main loop, or blocks in dbus_connection_flush()
to write out
pending data. The call will be completed after a timeout, or when
a reply is received. When the call returns, the callback specified
will be invoked; you can then collect the results of the call
(which may be an error, or a reply), use dbus_g_proxy_end_call()
.
TODO this particular function shouldn't die on out of memory, since you should be able to do a call with large arguments.
|
a proxy for a remote interface |
|
the name of the method to invoke |
|
callback to be invoked when method returns |
|
user data passed to callback |
|
function called to destroy user_data |
|
specify the timeout in milliseconds |
|
type of the first argument |
|
|
Returns : |
call identifier. |
gboolean dbus_g_proxy_end_call (DBusGProxy *proxy, DBusGProxyCall *call, GError **error, GType first_arg_type, ...);
Collects the results of a method call. The method call was normally
initiated with dbus_g_proxy_end_call()
. You may use this function
outside of the callback given to dbus_g_proxy_begin_call; in that
case this function will block if the results haven't yet been
received.
If the call results in an error, the error is set as normal for GError and the function returns FALSE.
Otherwise, the "out" parameters and return value of the method are stored in the provided varargs list. The list should be terminated with G_TYPE_INVALID.
|
a proxy for a remote interface |
|
the pending call ID from dbus_g_proxy_begin_call()
|
|
return location for an error |
|
type of first "out" argument |
|
|
Returns : |
FALSE if an error is set. |
void dbus_g_proxy_cancel_call (DBusGProxy *proxy, DBusGProxyCall *call);
Cancels a pending method call. The method call was normally
initiated with dbus_g_proxy_begin_call()
. This function
may not be used on pending calls that have already been
ended with dbus_g_proxy_end_call.
|
a proxy for a remote interface |
|
the pending call ID from dbus_g_proxy_begin_call()
|
void dbus_g_proxy_set_default_timeout (DBusGProxy *proxy, int timeout);
Sets the default timeout to use for a proxy. This timeout will be used in calls where the timeout is not specified.
This is useful for long-running operations that takes longer than the default timeout (which is a on the order of magnitude of tens of seconds). For some applications, consider using a pattern where the method returns once the operation is underway (e.g. immediately) and emits a signal when the operation terminates (though beware of leaking information with/in the signal return value).
|
a proxy for a remote interface |
|
specify the timeout in milliseconds |
Since 0.75