*
* A DBusConnection represents a connection to another
* application. Messages can be sent and received via this connection.
- *
- * The connection maintains a queue of incoming messages and a queue
- * of outgoing messages. dbus_connection_pop_message() and friends
- * can be used to read incoming messages from the queue.
- * Outgoing messages are automatically discarded as they are
- * written to the network.
- *
+ * The other application may be a message bus; for convenience, the
+ * function dbus_bus_get() is provided to automatically open a
+ * connection to the well-known message buses.
+ *
* In brief a DBusConnection is a message queue associated with some
- * message transport mechanism such as a socket.
+ * message transport mechanism such as a socket. The connection
+ * maintains a queue of incoming messages and a queue of outgoing
+ * messages.
+ *
+ * Incoming messages are normally processed by calling
+ * dbus_connection_dispatch(). dbus_connection_dispatch() runs any
+ * handlers registered for the topmost message in the message queue,
+ * then discards the message, then returns.
*
+ * dbus_connection_get_dispatch_status() indicates whether
+ * messages are currently in the queue that need dispatching.
+ * dbus_connection_set_dispatch_status_function() allows
+ * you to set a function to be used to monitor the dispatch status.
+ *
+ * If you're using GLib or Qt add-on libraries for D-BUS, there are
+ * special convenience functions in those libraries that hide
+ * all the details of dispatch and watch/timeout monitoring.
+ * For example, dbus_connection_setup_with_g_main().
+ *
+ * If you aren't using these add-on libraries, you have to manually
+ * call dbus_connection_set_dispatch_status_function(),
+ * dbus_connection_set_watch_functions(),
+ * dbus_connection_set_timeout_functions() providing appropriate
+ * functions to integrate the connection with your application's main
+ * loop.
+ *
+ * When you use dbus_connection_send() or one of its variants to send
+ * a message, the message is added to the outgoing queue. It's
+ * actually written to the network later; either in
+ * dbus_watch_handle() invoked by your main loop, or in
+ * dbus_connection_flush() which blocks until it can write out the
+ * entire outgoing queue. The GLib/Qt add-on libraries again
+ * handle the details here for you by setting up watch functions.
+ *
+ * When a connection is disconnected, you are guaranteed to get a
+ * message with the name #DBUS_MESSAGE_LOCAL_DISCONNECT.
+ *
+ * You may not drop the last reference to a #DBusConnection
+ * until that connection has been disconnected.
+ *
+ * You may dispatch the unprocessed incoming message queue even if the
+ * connection is disconnected. However, #DBUS_MESSAGE_LOCAL_DISCONNECT
+ * will always be the last message in the queue (obviously no messages
+ * are received after disconnection).
+ *
+ * #DBusConnection has thread locks and drops them when invoking user
+ * callbacks, so in general is transparently threadsafe. However,
+ * #DBusMessage does NOT have thread locks; you must not send the same
+ * message to multiple #DBusConnection that will be used from
+ * different threads.
*/
/**
* Returns the first-received message from the incoming message queue,
* leaving it in the queue. If the queue is empty, returns #NULL.
*
- * The caller does not own a reference to the returned message, and must
- * either return it using dbus_connection_return_message or keep it after
- * calling dbus_connection_steal_borrowed_message. No one can get at the
- * message while its borrowed, so return it as quickly as possible and
- * don't keep a reference to it after returning it. If you need to keep
- * the message, make a copy of it.
+ * The caller does not own a reference to the returned message, and
+ * must either return it using dbus_connection_return_message() or
+ * keep it after calling dbus_connection_steal_borrowed_message(). No
+ * one can get at the message while its borrowed, so return it as
+ * quickly as possible and don't keep a reference to it after
+ * returning it. If you need to keep the message, make a copy of it.
*
* @param connection the connection.
* @returns next message in the incoming queue.
}
/**
- * @todo docs
+ * Used to return a message after peeking at it using
+ * dbus_connection_borrow_message().
+ *
+ * @param connection the connection
+ * @param message the message from dbus_connection_borrow_message()
*/
void
dbus_connection_return_message (DBusConnection *connection,
}
/**
- * @todo docs
+ * Used to keep a message after peeking at it using
+ * dbus_connection_borrow_message(). Before using this function, see
+ * the caveats/warnings in the documentation for
+ * dbus_connection_pop_message().
+ *
+ * @param connection the connection
+ * @param message the message from dbus_connection_borrow_message()
*/
void
dbus_connection_steal_borrowed_message (DBusConnection *connection,
* removing it from the queue. The caller owns a reference to the
* returned message. If the queue is empty, returns #NULL.
*
+ * This function bypasses any message handlers that are registered,
+ * and so using it is usually wrong. Instead, let the main loop invoke
+ * dbus_connection_dispatch(). Popping messages manually is only
+ * useful in very simple programs that don't share a #DBusConnection
+ * with any libraries or other modules.
+ *
* @param connection the connection.
* @returns next message in the incoming queue.
*/
* Filters added during a filter callback won't be run on the
* message being processed.
*
+ * The connection does NOT add a reference to the message handler;
+ * instead, if the message handler is finalized, the connection simply
+ * forgets about it. Thus the caller of this function must keep a
+ * reference to the message handler.
+ *
* @param connection the connection
* @param handler the handler
* @returns #TRUE on success, #FALSE if not enough memory.
* handler. If the function returns #FALSE, the handlers were not
* registered due to lack of memory.
*
+ * The connection does NOT add a reference to the message handler;
+ * instead, if the message handler is finalized, the connection simply
+ * forgets about it. Thus the caller of this function must keep a
+ * reference to the message handler.
+ *
* @todo the messages_to_handle arg may be more convenient if it's a
* single string instead of an array. Though right now MessageHandler
* is sort of designed to say be associated with an entire object with
* In essence D-BUS error reporting works as follows:
*
* @code
- * DBusResultCode result = DBUS_RESULT_SUCCESS;
- * dbus_some_function (arg1, arg2, &result);
- * if (result != DBUS_RESULT_SUCCESS)
- * printf ("an error occurred\n");
+ * DBusError error;
+ * _dbus_error_init (&error);
+ * dbus_some_function (arg1, arg2, &error);
+ * if (dbus_error_is_set (&error))
+ * {
+ * fprintf (stderr, "an error occurred: %s\n", error.message);
+ * dbus_error_free (&error);
+ * }
* @endcode
*
- * @todo add docs with DBusError
+ * There are some rules. An error passed to a D-BUS function must
+ * always be unset; you can't pass in an error that's already set. If
+ * a function has a return code indicating whether an error occurred,
+ * and also a #DBusError parameter, then the error will always be set
+ * if and only if the return code indicates an error occurred. i.e.
+ * the return code and the error are never going to disagree.
+ *
+ * An error only needs to be freed if it's been set, not if
+ * it's merely been initialized.
+ *
+ * You can check the specific error that occurred using
+ * dbus_error_has_name().
*
* @{
*/
}
/**
- * Assigns an error name and message to a DBusError.
- * Does nothing if error is #NULL. The message may
- * be NULL only if the error is DBUS_ERROR_NO_MEMORY.
+ * Assigns an error name and message to a DBusError. Does nothing if
+ * error is #NULL. The message may be NULL, which means a default
+ * message will be deduced from the name. If the error name is unknown
+ * to D-BUS the default message will be totally useless, though.
*
* @param error the error.
* @param name the error name (not copied!!!)
* Assigns an error name and message to a DBusError.
* Does nothing if error is #NULL.
*
- * The format may be NULL only if the error is DBUS_ERROR_NO_MEMORY.
+ * The format may be NULL, which means a default message will be
+ * deduced from the name. If the error name is unknown to D-BUS the
+ * default message will be totally useless, though.
*
* If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead.
projects / platform / upstream / dbus.git / commitdiff