2006-10-21 Havoc Pennington <hp@redhat.com>
+ * More documentation - all public API now documented according to
+ Doxygen
+
+2006-10-21 Havoc Pennington <hp@redhat.com>
+
* Document a bunch of undocumented stuff
2006-10-21 Havoc Pennington <hp@redhat.com>
/**
* Checks whether there are messages in the outgoing message queue.
- *
+ * Use dbus_connection_flush() to block until all outgoing
+ * messages have been written to the underlying transport
+ * (such as a socket).
+ *
* @param connection the connection.
* @returns #TRUE if the outgoing queue is non-empty.
*/
{
DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
DBUS_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */
- DBUS_WATCH_ERROR = 1 << 2, /**< As in POLLERR (can't watch for this, but
- * the flag can be passed to dbus_watch_handle()).
+ DBUS_WATCH_ERROR = 1 << 2, /**< As in POLLERR (can't watch for
+ * this, but can be present in
+ * current state passed to
+ * dbus_watch_handle()).
*/
- DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for it, but
- * can be present in current state).
+ DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for
+ * it, but can be present in current
+ * state passed to
+ * dbus_watch_handle()).
*/
} DBusWatchFlags;
* @defgroup DBusProtocol Protocol constants
* @ingroup DBus
*
- * D-Bus protocol constants
+ * @brief Defines constants which are part of the D-Bus protocol
+ *
+ * This header is intended for use by any library, not only libdbus.
*
- * @brief Defines constants which are part of the D-Bus protocol
* @{
*/
#define DBUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed"
/** Unable to connect to server (probably caused by ECONNREFUSED on a socket). */
#define DBUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer"
-/** Certain timeout errors, possibly ETIMEDOUT on a socket. Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts. */
+/** Certain timeout errors, possibly ETIMEDOUT on a socket.
+ * Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts.
+ * @warning this is confusingly-named given that #DBUS_ERROR_TIMED_OUT also exists. We can't fix
+ * it for compatibility reasons so just be careful.
+ */
#define DBUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout"
/** No network access (probably ENETUNREACH on a socket). */
#define DBUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork"
#define DBUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists"
/** Method name you invoked isn't known by the object you invoked it on. */
#define DBUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod"
-/** Certain other timeout errors, e.g. while starting a service. @todo redundant with #DBUS_ERROR_TIMEOUT */
+/** Certain timeout errors, e.g. while starting a service.
+ * @warning this is confusingly-named given that #DBUS_ERROR_TIMEOUT also exists. We can't fix
+ * it for compatibility reasons so just be careful.
+ */
#define DBUS_ERROR_TIMED_OUT "org.freedesktop.DBus.Error.TimedOut"
/** Tried to remove or modify a match rule that didn't exist. */
#define DBUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound"
* @defgroup DBusShared Shared constants
* @ingroup DBus
*
- * Shared constants.
+ * @brief Shared header included by both libdbus and C/C++ bindings such as the GLib bindings.
+ *
+ * Usually a C/C++ binding such as the GLib or Qt binding won't want to include dbus.h in its
+ * public headers. However, a few constants and macros may be useful to include; those are
+ * found here and in dbus-protocol.h
*
- * @brief Stuff used by both dbus/dbus.h low-level and C/C++ binding APIs
* @{
*/
/**
*
- * Initializes threads. If this function is not called,
- * the D-Bus library will not lock any data structures.
- * If it is called, D-Bus will do locking, at some cost
- * in efficiency. Note that this function must be called
- * BEFORE the second thread is started.
+ * Initializes threads. If this function is not called, the D-Bus
+ * library will not lock any data structures. If it is called, D-Bus
+ * will do locking, at some cost in efficiency. Note that this
+ * function must be called BEFORE the second thread is started.
*
- * Use dbus_threads_init_default() if you don't need a
- * particular thread implementation.
+ * Almost always, you should use dbus_threads_init_default() instead.
+ * The raw dbus_threads_init() is only useful if you require a
+ * particular thread implementation for some reason.
*
- * This function may be called more than once. The first
- * one wins.
+ * A possible reason to use dbus_threads_init() rather than
+ * dbus_threads_init_default() is to insert debugging checks or print
+ * statements.
*
+ * dbus_threads_init() may be called more than once. The first one
+ * wins and subsequent calls are ignored. (Unless you use
+ * dbus_shutdown() to reset libdbus, which will let you re-init
+ * threads.)
+ *
+ * Either recursive or nonrecursive mutex functions must be specified,
+ * but not both. New code should provide only the recursive functions
+ * - specifying the nonrecursive ones is deprecated.
+ *
+ * Because this function effectively sets global state, all code
+ * running in a given application must agree on the thread
+ * implementation. Most code won't care which thread implementation is
+ * used, so there's no problem. However, usually libraries should not
+ * call dbus_threads_init() or dbus_threads_init_default(), instead
+ * leaving this policy choice to applications.
+ *
+ * The exception is for application frameworks (GLib, Qt, etc.) and
+ * D-Bus bindings based on application frameworks. These frameworks
+ * define a cross-platform thread abstraction and can assume
+ * applications using the framework are OK with using that thread
+ * abstraction.
+ *
+ * However, even these app frameworks may find it easier to simply call
+ * dbus_threads_init_default(), and there's no reason they shouldn't.
+ *
* @param functions functions for using threads
* @returns #TRUE on success, #FALSE if no memory
*/
* Calls dbus_threads_init() with a default set of
* #DBusThreadFunctions appropriate for the platform.
*
+ * Most applications should use this rather than dbus_threads_init().
+ *
+ * It's safe to call dbus_threads_init_default() as many times as you
+ * want, but only the first time will have an effect.
+ *
+ * dbus_shutdown() reverses the effects of this function when it
+ * resets all global state in libdbus.
+ *
* @returns #TRUE on success, #FALSE if not enough memory
*/
dbus_bool_t
* @{
*/
+/** An opaque mutex type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
typedef struct DBusMutex DBusMutex;
+/** An opaque condition variable type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
typedef struct DBusCondVar DBusCondVar;
+/** Deprecated, provide DBusRecursiveMutexNewFunction instead. */
typedef DBusMutex* (* DBusMutexNewFunction) (void);
+/** Deprecated, provide DBusRecursiveMutexFreeFunction instead. */
typedef void (* DBusMutexFreeFunction) (DBusMutex *mutex);
+/** Deprecated, provide DBusRecursiveMutexLockFunction instead. */
typedef dbus_bool_t (* DBusMutexLockFunction) (DBusMutex *mutex);
+/** Deprecated, provide DBusRecursiveMutexUnlockFunction instead. */
typedef dbus_bool_t (* DBusMutexUnlockFunction) (DBusMutex *mutex);
+/** Creates a new recursively-lockable mutex, or returns #NULL if not enough memory.
+ * Found in #DBusThreadFunctions
+ */
typedef DBusMutex* (* DBusRecursiveMutexNewFunction) (void);
+/** Frees a recursively-lockable mutex. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusRecursiveMutexFreeFunction) (DBusMutex *mutex);
+/** Locks a recursively-lockable mutex. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusRecursiveMutexLockFunction) (DBusMutex *mutex);
+/** Unlocks a recursively-lockable mutex. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusRecursiveMutexUnlockFunction) (DBusMutex *mutex);
+/** Creates a new condition variable. Found in #DBusThreadFunctions.
+ */
typedef DBusCondVar* (* DBusCondVarNewFunction) (void);
+/** Frees a condition variable. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusCondVarFreeFunction) (DBusCondVar *cond);
+/** Waits on a condition variable. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusCondVarWaitFunction) (DBusCondVar *cond,
DBusMutex *mutex);
+/** Waits on a condition variable with a timeout. Found in #DBusThreadFunctions.
+ */
typedef dbus_bool_t (* DBusCondVarWaitTimeoutFunction) (DBusCondVar *cond,
DBusMutex *mutex,
int timeout_milliseconds);
+/** Wakes one waiting thread on a condition variable. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusCondVarWakeOneFunction) (DBusCondVar *cond);
+/** Wakes all waiting threads on a condition variable. Found in #DBusThreadFunctions.
+ */
typedef void (* DBusCondVarWakeAllFunction) (DBusCondVar *cond);
+/**
+ * Flags indicating which functions are present in #DBusThreadFunctions. Used to allow
+ * the library to detect older callers of dbus_threads_init() if new possible functions
+ * are added to #DBusThreadFunctions.
+ */
typedef enum
{
DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK = 1 << 0,
} DBusThreadFunctionsMask;
/**
- * Functions that must be implemented to make the D-Bus
- * library thread-aware.
+ * Functions that must be implemented to make the D-Bus library
+ * thread-aware. The recursive mutex functions should be specified
+ * rather than the old, deprecated nonrecursive ones.
*/
typedef struct
{
unsigned int mask; /**< Mask indicating which functions are present. */
- DBusMutexNewFunction mutex_new; /**< Function to create a mutex */
- DBusMutexFreeFunction mutex_free; /**< Function to free a mutex */
- DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex */
- DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex */
+ DBusMutexNewFunction mutex_new; /**< Function to create a mutex; optional and deprecated. */
+ DBusMutexFreeFunction mutex_free; /**< Function to free a mutex; optional and deprecated. */
+ DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex; optional and deprecated. */
+ DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex; optional and deprecated. */
DBusCondVarNewFunction condvar_new; /**< Function to create a condition variable */
DBusCondVarFreeFunction condvar_free; /**< Function to free a condition variable */
/**
* Gets the file descriptor that should be watched.
*
+ * On Windows, this will be a socket. On UNIX right now it will be a
+ * socket but in principle it could be something else.
+ *
* @param watch the DBusWatch object.
* @returns the file descriptor to watch.
*/
projects / platform / upstream / dbus.git / commitdiff