Commit 58a0d275 authored by Havoc Pennington's avatar Havoc Pennington
Browse files

2006-10-21 Havoc Pennington <hp@redhat.com>

	* More documentation - all public API now documented according to
	Doxygen
parent fed8880c
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
......
......@@ -533,7 +533,10 @@ _dbus_connection_has_messages_to_send_unlocked (DBusConnection *connection)
/**
* 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.
*/
......
......@@ -59,11 +59,15 @@ typedef enum
{
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;
......
......@@ -41,9 +41,10 @@ extern "C" {
* @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
* @{
*/
......@@ -349,7 +350,11 @@ extern "C" {
#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"
......@@ -365,7 +370,10 @@ extern "C" {
#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"
......
......@@ -40,9 +40,12 @@ extern "C" {
* @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
* @{
*/
......
......@@ -520,18 +520,44 @@ init_locks (void)
/**
*
* 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
*/
......@@ -983,6 +1009,14 @@ static const DBusThreadFunctions internal_functions =
* 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
......
......@@ -37,29 +37,61 @@ DBUS_BEGIN_DECLS
* @{
*/
/** 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,
......@@ -80,17 +112,18 @@ typedef enum
} 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 */
......
......@@ -483,6 +483,9 @@ _dbus_watch_set_handler (DBusWatch *watch,
/**
* 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.
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment