Main Page | Modules | Data Structures | Directories | File List | Data Fields | Related Pages

GLib bindings
[D-BUS message system public API]

API for using D-BUS with GLib. More...

Functions

void dbus_g_connection_flush (DBusGConnection *connection)
 Blocks until outgoing calls and signal emissions have been sent.
void dbus_connection_setup_with_g_main (DBusConnection *connection, GMainContext *context)
 Sets the watch and timeout functions of a DBusConnection to integrate the connection with the GLib main loop.
void dbus_server_setup_with_g_main (DBusServer *server, GMainContext *context)
 Sets the watch and timeout functions of a DBusServer to integrate the server with the GLib main loop.
DBusGConnection * dbus_g_bus_get (DBusBusType type, GError **error)
 Returns a connection to the given bus.
GQuark dbus_g_error_quark (void)
 The implementation of DBUS_GERROR error domain.
void dbus_set_g_error (GError **gerror, DBusError *derror)
 Set a GError return location from a DBusError.
GType dbus_connection_get_g_type (void)
 Get the GLib type ID for a DBusConnection boxed type.
GType dbus_message_get_g_type (void)
 Get the GLib type ID for a DBusMessage boxed type.
GType dbus_g_connection_get_g_type (void)
 Get the GLib type ID for a DBusGConnection boxed type.
GType dbus_g_message_get_g_type (void)
 Get the GLib type ID for a DBusGMessage boxed type.
DBusConnectiondbus_g_connection_get_connection (DBusGConnection *gconnection)
 Get the DBusConnection corresponding to this DBusGConnection.
DBusMessagedbus_g_message_get_message (DBusGMessage *gmessage)
 Get the DBusMessage corresponding to this DBusGMessage.
void dbus_g_object_class_install_info (GObjectClass *object_class, const DBusGObjectInfo *info)
 Install introspection information about the given object class sufficient to allow methods on the object to be invoked by name.
void dbus_g_connection_register_g_object (DBusGConnection *connection, const char *at_path, GObject *object)
 Registers a GObject at the given path.
GType dbus_g_proxy_get_type (void)
 Standard GObject get_type() function for DBusGProxy.
DBusGProxydbus_g_proxy_new_for_service (DBusGConnection *connection, const char *service_name, const char *path_name, const char *interface_name)
 Creates a new proxy for a remote interface exported by a service on a message bus.
DBusGProxydbus_g_proxy_new_for_service_owner (DBusGConnection *connection, const char *service_name, const char *path_name, const char *interface_name, GError **error)
 Similar to dbus_g_proxy_new_for_service(), but makes a round-trip request to the message bus to get the current service owner, then binds the proxy specifically to the current owner.
DBusGProxydbus_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).
DBusGPendingCall * dbus_g_proxy_begin_call (DBusGProxy *proxy, const char *method, int first_arg_type,...)
 Invokes a method on a remote interface.
gboolean dbus_g_proxy_end_call (DBusGProxy *proxy, DBusGPendingCall *pending, GError **error, int first_arg_type,...)
 Collects the results of a method call.
void dbus_g_proxy_call_no_reply (DBusGProxy *proxy, const char *method, int 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.
void dbus_g_proxy_send (DBusGProxy *proxy, DBusMessage *message, dbus_uint32_t *client_serial)
 Sends a message to the interface we're proxying for.
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.
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.
void dbus_g_thread_init (void)
 Initializes the D-BUS thread system to use GLib threads.

Detailed Description

API for using D-BUS with GLib.

Convenience functions are provided for using D-BUS with the GLib library (see http://www.gtk.org for GLib information).


Function Documentation

GType dbus_connection_get_g_type void   ) 
 

Get the GLib type ID for a DBusConnection boxed type.

Returns:
GLib type

Definition at line 665 of file dbus-gmain.c.

References dbus_connection_ref(), and dbus_connection_unref().

void dbus_connection_setup_with_g_main DBusConnection connection,
GMainContext *  context
 

Sets the watch and timeout functions of a DBusConnection to integrate the connection with the GLib main loop.

Pass in NULL for the #GMainContext unless you're doing something specialized.

If called twice for the same context, does nothing the second time. If called once with context A and once with context B, context B replaces context A as the context monitoring the connection.

Parameters:
connection the connection
context the #GMainContext or NULL for default context

Definition at line 463 of file dbus-gmain.c.

References dbus_connection_allocate_data_slot(), dbus_connection_get_data(), dbus_connection_set_data(), dbus_connection_set_timeout_functions(), dbus_connection_set_wakeup_main_function(), dbus_connection_set_watch_functions(), and NULL.

Referenced by dbus_g_bus_get().

DBusGConnection* dbus_g_bus_get DBusBusType  type,
GError **  error
 

Returns a connection to the given bus.

The connection is a global variable shared with other callers of this function.

(Internally, calls dbus_bus_get() then calls dbus_connection_setup_with_g_main() on the result.)

Parameters:
type bus type
error address where an error can be returned.
Returns:
a DBusConnection

Definition at line 598 of file dbus-gmain.c.

References dbus_bus_get(), dbus_connection_setup_with_g_main(), dbus_error_free(), dbus_error_init(), dbus_set_g_error(), and NULL.

void dbus_g_connection_flush DBusGConnection *  connection  ) 
 

Blocks until outgoing calls and signal emissions have been sent.

Parameters:
connection the connection to flush

Definition at line 45 of file dbus-glib.c.

References dbus_connection_flush().

DBusConnection* dbus_g_connection_get_connection DBusGConnection *  gconnection  ) 
 

Get the DBusConnection corresponding to this DBusGConnection.

The return value does not have its refcount incremented.

Returns:
DBusConnection

Definition at line 777 of file dbus-gmain.c.

GType dbus_g_connection_get_g_type void   ) 
 

Get the GLib type ID for a DBusGConnection boxed type.

Returns:
GLib type

Definition at line 740 of file dbus-gmain.c.

void dbus_g_connection_register_g_object DBusGConnection *  connection,
const char *  at_path,
GObject *  object
 

Registers a GObject at the given path.

Properties, methods, and signals of the object can then be accessed remotely. Methods are only available if method introspection data has been added to the object's class with g_object_class_install_info().

The registration will be cancelled if either the DBusConnection or the GObject gets finalized.

Parameters:
connection the D-BUS connection
at_path the path where the object will live (the object's name)
object the object

Definition at line 544 of file dbus-gobject.c.

References dbus_connection_register_object_path(), and NULL.

GQuark dbus_g_error_quark void   ) 
 

The implementation of DBUS_GERROR error domain.

See documentation for GError in GLib reference manual.

Returns:
the error domain quark for use with GError

Definition at line 629 of file dbus-gmain.c.

GType dbus_g_message_get_g_type void   ) 
 

Get the GLib type ID for a DBusGMessage boxed type.

Returns:
GLib type

Definition at line 758 of file dbus-gmain.c.

DBusMessage* dbus_g_message_get_message DBusGMessage *  gmessage  ) 
 

Get the DBusMessage corresponding to this DBusGMessage.

The return value does not have its refcount incremented.

Returns:
DBusMessage

Definition at line 789 of file dbus-gmain.c.

void dbus_g_object_class_install_info GObjectClass *  object_class,
const DBusGObjectInfo info
 

Install introspection information about the given object class sufficient to allow methods on the object to be invoked by name.

The introspection information is normally generated by dbus-glib-tool, then this function is called in the class_init() for the object class.

Once introspection information has been installed, instances of the object registered with dbus_g_connection_register_g_object() can have their methods invoked remotely.

Parameters:
object_class class struct of the object
info introspection data generated by dbus-glib-tool

Definition at line 513 of file dbus-gobject.c.

References NULL.

DBusGPendingCall* dbus_g_proxy_begin_call DBusGProxy proxy,
const char *  method,
int  first_arg_type,
  ...
 

Invokes a method on a remote interface.

This function does not block; instead it returns an opaque DBusPendingCall object that tracks the pending call. 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. To 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.
Parameters:
proxy a proxy for a remote interface
method the name of the method to invoke
first_arg_type type of the first argument
Returns:
opaque pending call object

Definition at line 1056 of file dbus-gproxy.c.

References dbus_connection_send_with_reply(), dbus_message_append_args_valist(), dbus_message_new_method_call(), and NULL.

void dbus_g_proxy_call_no_reply DBusGProxy proxy,
const char *  method,
int  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.
Parameters:
proxy a proxy for a remote interface
method the name of the method to invoke
first_arg_type type of the first argument

Definition at line 1187 of file dbus-gproxy.c.

References dbus_connection_send(), dbus_message_append_args_valist(), dbus_message_new_method_call(), dbus_message_set_no_reply(), NULL, and TRUE.

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.

Todo:
Right now there's no way to specify the signature to use for invoking the GCallback. Need to either rely on introspection, or require signature here.
Parameters:
proxy a proxy for a remote interface
signal_name the DBus signal name to listen for
handler the handler to connect
data data to pass to handler
free_data_func callback function to destroy data

Definition at line 1284 of file dbus-gproxy.c.

References FALSE, and NULL.

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.

Parameters:
proxy a proxy for a remote interface
signal_name the DBus signal name to disconnect
handler the handler to disconnect
data the data that was registered with handler

Definition at line 1318 of file dbus-gproxy.c.

References NULL.

gboolean dbus_g_proxy_end_call DBusGProxy proxy,
DBusGPendingCall *  pending,
GError **  error,
int  first_arg_type,
  ...
 

Collects the results of a method call.

The method call was normally initiated with dbus_g_proxy_end_call(). This function will block if the results haven't yet been received; use dbus_pending_call_set_notify() to be notified asynchronously that a pending call has been completed. Use dbus_pending_call_get_completed() to check whether a call has been completed. If it's completed, it will not block.

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

This function doesn't affect the reference count of the DBusPendingCall, the caller of dbus_g_proxy_begin_call() still owns a reference.

Parameters:
proxy a proxy for a remote interface
pending the pending call from dbus_g_proxy_begin_call()
error return location for an error
first_arg_type type of first "out" argument
Returns:
FALSE if an error is set

Definition at line 1124 of file dbus-gproxy.c.

References dbus_error_free(), dbus_error_init(), dbus_message_get_args_valist(), dbus_message_get_type(), dbus_message_unref(), dbus_pending_call_block(), dbus_pending_call_steal_reply(), dbus_set_error(), dbus_set_error_from_message(), dbus_set_g_error(), FALSE, NULL, and TRUE.

GType dbus_g_proxy_get_type void   ) 
 

Standard GObject get_type() function for DBusGProxy.

Returns:
type ID for DBusGProxy class

Definition at line 816 of file dbus-gproxy.c.

References NULL.

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.

Parameters:
connection the connection to the peer
path_name name of the object inside the peer to call methods on
interface_name name of the interface to call methods on
Returns:
new proxy object

Definition at line 1020 of file dbus-gproxy.c.

References NULL.

DBusGProxy* dbus_g_proxy_new_for_service DBusGConnection *  connection,
const char *  service_name,
const char *  path_name,
const char *  interface_name
 

Creates a new proxy for a remote interface exported by a service on a message bus.

Method calls and signal connections over this proxy will go to the service owner; the service owner is expected to support the given interface name. THE SERVICE OWNER MAY CHANGE OVER TIME, for example between two different method calls. If you need a fixed owner, you need to request the current owner and bind a proxy to that rather than to the generic service name; see dbus_g_proxy_new_for_service_owner().

A service-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 or the proxy is has no remaining references.

Parameters:
connection the connection to the remote bus
service_name name of the service on the message bus
path_name name of the object inside the service to call methods on
interface_name name of the interface to call methods on
Returns:
new proxy object

Definition at line 893 of file dbus-gproxy.c.

References NULL.

DBusGProxy* dbus_g_proxy_new_for_service_owner DBusGConnection *  connection,
const char *  service_name,
const char *  path_name,
const char *  interface_name,
GError **  error
 

Similar to dbus_g_proxy_new_for_service(), but makes a round-trip request to the message bus to get the current service owner, then binds the proxy specifically to the current owner.

As a result, the service 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_service() and dbus_g_proxy_new_for_service_owner(): if you pass the service name "org.freedesktop.Database" dbus_g_proxy_new_for_service() remains bound to that name as it changes owner. dbus_g_proxy_new_for_service_owner() will fail if the service has no owner. If the service has an owner, dbus_g_proxy_new_for_service_owner() will bind to the unique name of that owner rather than the generic service name.

Parameters:
connection the connection to the remote bus
service_name name of the service on the message bus
path_name name of the object inside the service to call methods on
interface_name name of the interface to call methods on
error return location for an error
Returns:
new proxy object, or NULL on error

Definition at line 935 of file dbus-gproxy.c.

References dbus_connection_send_with_reply_and_block(), dbus_error_free(), dbus_error_init(), dbus_error_is_set(), dbus_free(), dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), dbus_set_error_from_message(), dbus_set_g_error(), and NULL.

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

Parameters:
proxy a proxy for a remote interface
message the message to address and send
client_serial return location for message's serial, or NULL

Definition at line 1242 of file dbus-gproxy.c.

References dbus_connection_send(), dbus_message_set_destination(), dbus_message_set_interface(), and dbus_message_set_path().

void dbus_g_thread_init void   ) 
 

Initializes the D-BUS thread system to use GLib threads.

This function may only be called once and must be called prior to calling any other function in the D-BUS API.

Definition at line 169 of file dbus-gthread.c.

References dbus_threads_init().

GType dbus_message_get_g_type void   ) 
 

Get the GLib type ID for a DBusMessage boxed type.

Returns:
GLib type

Definition at line 683 of file dbus-gmain.c.

References dbus_message_ref(), and dbus_message_unref().

void dbus_server_setup_with_g_main DBusServer server,
GMainContext *  context
 

Sets the watch and timeout functions of a DBusServer to integrate the server with the GLib main loop.

In most cases the context argument should be NULL.

If called twice for the same context, does nothing the second time. If called once with context A and once with context B, context B replaces context A as the context monitoring the connection.

Parameters:
server the server
context the #GMainContext or NULL for default

Definition at line 536 of file dbus-gmain.c.

References dbus_server_allocate_data_slot(), dbus_server_get_data(), dbus_server_set_data(), dbus_server_set_timeout_functions(), dbus_server_set_watch_functions(), and NULL.

void dbus_set_g_error GError **  gerror,
DBusError derror
 

Set a GError return location from a DBusError.

Todo:
expand the DBUS_GERROR enum and take advantage of it here
Parameters:
gerror location to store a GError, or NULL
derror the DBusError

Definition at line 647 of file dbus-gmain.c.

References dbus_error_is_set(), and NULL.

Referenced by dbus_g_bus_get(), dbus_g_proxy_end_call(), and dbus_g_proxy_new_for_service_owner().


Generated on Mon Apr 4 04:40:49 2005 for D-BUS by  doxygen 1.4.0