Main Page   Modules   Data Structures   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_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. More...

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

DBusConnectiondbus_bus_get_with_g_main (DBusBusType type, GError **error)
 Calls dbus_bus_get() then calls dbus_connection_setup_with_g_main() on the result and returns the bus connection. More...

GQuark dbus_g_error_quark (void)
 The implementation of DBUS_GERROR error domain. More...

void dbus_set_g_error (GError **gerror, DBusError *derror)
 Set a GError return location from a DBusError. More...

GType dbus_connection_get_g_type (void) G_GNUC_CONST
 Get the GLib type ID for a DBusConnection boxed type. More...

GType dbus_message_get_g_type (void) G_GNUC_CONST
 Get the GLib type ID for a DBusMessage boxed type. More...

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

void dbus_connection_register_g_object (DBusConnection *connection, const char *at_path, GObject *object)
 Registers a GObject at the given path. More...

GType dbus_gproxy_get_type (void) G_GNUC_CONST
 Standard GObject get_type() function for DBusGProxy. More...

DBusGProxydbus_gproxy_new_for_service (DBusConnection *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. More...

DBusGProxydbus_gproxy_new_for_service_owner (DBusConnection *connection, const char *service_name, const char *path_name, const char *interface_name, GError **error)
 Similar to dbus_gproxy_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. More...

DBusGProxydbus_gproxy_new_for_peer (DBusConnection *connection, const char *path_name, const char *interface_name)
 Creates a proxy for an object in peer application (one we're directly connected to). More...

DBusPendingCalldbus_gproxy_begin_call (DBusGProxy *proxy, const char *method, int first_arg_type,...)
 Invokes a method on a remote interface. More...

gboolean dbus_gproxy_end_call (DBusGProxy *proxy, DBusPendingCall *pending, GError **error, int first_arg_type,...)
 Collects the results of a method call. More...

void dbus_gproxy_call_no_reply (DBusGProxy *proxy, const char *method, int first_arg_type,...)
 Sends a method call message as with dbus_gproxy_begin_call(), but does not ask for a reply or allow you to receive one. More...

void dbus_gproxy_send (DBusGProxy *proxy, DBusMessage *message, dbus_uint32_t *client_serial)
 Sends a message to the interface we're proxying for. More...

void dbus_gproxy_connect_signal (DBusGProxy *proxy, const char *signal_name, DBusGProxySignalHandler handler, void *data, GClosureNotify free_data_func)
 Connect a signal handler to a proxy for a remote interface. More...

void dbus_gproxy_disconnect_signal (DBusGProxy *proxy, const char *signal_name, DBusGProxySignalHandler handler, void *data)
 Disconnect all signal handlers from a proxy that match the given criteria. More...

void dbus_g_thread_init (void)
 Initializes the D-BUS thread system to use GLib threads. More...


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

DBusConnection* dbus_bus_get_with_g_main DBusBusType    type,
GError **    error
 

Calls dbus_bus_get() then calls dbus_connection_setup_with_g_main() on the result and returns the bus connection.

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

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

GType dbus_connection_get_g_type void   
 

Get the GLib type ID for a DBusConnection boxed type.

Returns:
GLib type

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

void dbus_connection_register_g_object DBusConnection   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 543 of file dbus-gobject.c.

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 461 of file dbus-gmain.c.

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 625 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_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 512 of file dbus-gobject.c.

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 168 of file dbus-gthread.c.

DBusPendingCall* dbus_gproxy_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_gproxy_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 1053 of file dbus-gproxy.c.

References DBusGProxyManager::connection, DBusGProxy::interface, DBusGProxy::manager, DBusGProxy::path, and DBusGProxy::service.

void dbus_gproxy_call_no_reply DBusGProxy   proxy,
const char *    method,
int    first_arg_type,
...   
 

Sends a method call message as with dbus_gproxy_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 1182 of file dbus-gproxy.c.

References DBusGProxyManager::connection, DBusGProxy::interface, DBusGProxy::manager, DBusGProxy::path, and DBusGProxy::service.

void dbus_gproxy_connect_signal DBusGProxy   proxy,
const char *    signal_name,
DBusGProxySignalHandler    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.

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 1275 of file dbus-gproxy.c.

References DBusGProxy::interface.

void dbus_gproxy_disconnect_signal DBusGProxy   proxy,
const char *    signal_name,
DBusGProxySignalHandler    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 1309 of file dbus-gproxy.c.

References DBusGProxy::interface.

gboolean dbus_gproxy_end_call DBusGProxy   proxy,
DBusPendingCall   pending,
GError **    error,
int    first_arg_type,
...   
 

Collects the results of a method call.

The method call was normally initiated with dbus_gproxy_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_gproxy_begin_call() still owns a reference.

Parameters:
proxy  a proxy for a remote interface
pending  the pending call from dbus_gproxy_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 1121 of file dbus-gproxy.c.

GType dbus_gproxy_get_type void   
 

Standard GObject get_type() function for DBusGProxy.

Returns:
type ID for DBusGProxy class

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

DBusGProxy* dbus_gproxy_new_for_peer DBusConnection   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 1017 of file dbus-gproxy.c.

DBusGProxy* dbus_gproxy_new_for_service DBusConnection   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_gproxy_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 891 of file dbus-gproxy.c.

DBusGProxy* dbus_gproxy_new_for_service_owner DBusConnection   connection,
const char *    service_name,
const char *    path_name,
const char *    interface_name,
GError **    error
 

Similar to dbus_gproxy_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_gproxy_new_for_service() and dbus_gproxy_new_for_service_owner(): if you pass the service name "org.freedesktop.Database" dbus_gproxy_new_for_service() remains bound to that name as it changes owner. dbus_gproxy_new_for_service_owner() will fail if the service has no owner. If the service has an owner, dbus_gproxy_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 933 of file dbus-gproxy.c.

void dbus_gproxy_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 1237 of file dbus-gproxy.c.

References DBusGProxyManager::connection, DBusGProxy::interface, DBusGProxy::manager, DBusGProxy::path, and DBusGProxy::service.

GType dbus_message_get_g_type void   
 

Get the GLib type ID for a DBusMessage boxed type.

Returns:
GLib type

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

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 534 of file dbus-gmain.c.

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 643 of file dbus-gmain.c.

References DBusError::message, and DBusError::name.


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15