diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | dbus/dbus-connection.c | 80 | ||||
| -rw-r--r-- | dbus/dbus-hash.h | 2 | ||||
| -rw-r--r-- | dbus/dbus-marshal-recursive.c | 2 | ||||
| -rw-r--r-- | dbus/dbus-marshal-validate.h | 6 | ||||
| -rw-r--r-- | dbus/dbus-pending-call.c | 10 | ||||
| -rw-r--r-- | dbus/dbus-protocol.h | 6 | ||||
| -rw-r--r-- | dbus/dbus-server.c | 41 | ||||
| -rw-r--r-- | dbus/dbus-shared.h | 4 | ||||
| -rw-r--r-- | dbus/dbus-signature.c | 90 | ||||
| -rw-r--r-- | dbus/dbus-sysdeps.h | 67 | ||||
| -rw-r--r-- | dbus/dbus-timeout.h | 1 | ||||
| -rw-r--r-- | dbus/dbus-watch.h | 1 |
13 files changed, 207 insertions, 108 deletions
@@ -1,5 +1,10 @@ 2006-10-21 Havoc Pennington <hp@redhat.com> + * Documentation! Whee! Doxygen now 100% silent. If you make it + angry again, you will be punished. + +2006-10-21 Havoc Pennington <hp@redhat.com> + * More documentation - all public API now documented according to Doxygen diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index acba9ba9..80032bd1 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -2992,23 +2992,19 @@ reply_handler_timeout (void *data) } /** - * Queues a message to send, as with dbus_connection_send_message(), + * Queues a message to send, as with dbus_connection_send(), * but also returns a #DBusPendingCall used to receive a reply to the * message. If no reply is received in the given timeout_milliseconds, * this function expires the pending reply and generates a synthetic * error reply (generated in-process, not by the remote application) * indicating that a timeout occurred. * - * A #DBusPendingCall will see a reply message after any filters, but - * before any object instances or other handlers. A #DBusPendingCall - * will always see exactly one reply message, unless it's cancelled - * with dbus_pending_call_cancel(). - * - * If a filter filters out the reply before the handler sees it, the - * reply is immediately timed out and a timeout error reply is - * generated. If a filter removes the timeout error reply then the - * #DBusPendingCall will get confused. Filtering the timeout error - * is thus considered a bug and will print a warning. + * A #DBusPendingCall will see a reply message before any filters or + * registered object path handlers. See dbus_connection_dispatch() for + * details on when handlers are run. + * + * A #DBusPendingCall will always see exactly one reply message, + * unless it's cancelled with dbus_pending_call_cancel(). * * If #NULL is passed for the pending_return, the #DBusPendingCall * will still be generated internally, and used to track @@ -3019,7 +3015,11 @@ reply_handler_timeout (void *data) * is typically the best value for the timeout for this reason, unless * you want a very short or very long timeout. There is no way to * avoid a timeout entirely, other than passing INT_MAX for the - * timeout to postpone it indefinitely. + * timeout to mean "very long timeout." libdbus clamps an INT_MAX + * timeout down to a few hours timeout though. + * + * @warning if the connection is disconnected, the #DBusPendingCall + * will be set to #NULL, so be careful with this. * * @param connection the connection * @param message the message to send @@ -3123,16 +3123,24 @@ dbus_connection_send_with_reply (DBusConnection *connection, * Sends a message and blocks a certain time period while waiting for * a reply. This function does not reenter the main loop, * i.e. messages other than the reply are queued up but not - * processed. This function is used to do non-reentrant "method - * calls." + * processed. This function is used to invoke method calls on a + * remote object. * * If a normal reply is received, it is returned, and removed from the * incoming message queue. If it is not received, #NULL is returned * and the error is set to #DBUS_ERROR_NO_REPLY. If an error reply is * received, it is converted to a #DBusError and returned as an error, - * then the reply message is deleted. If something else goes wrong, - * result is set to whatever is appropriate, such as - * #DBUS_ERROR_NO_MEMORY or #DBUS_ERROR_DISCONNECTED. + * then the reply message is deleted and #NULL is returned. If + * something else goes wrong, result is set to whatever is + * appropriate, such as #DBUS_ERROR_NO_MEMORY or + * #DBUS_ERROR_DISCONNECTED. + * + * @warning While this function blocks the calling thread will not be + * processing the incoming message queue. This means you can end up + * deadlocked if the application you're talking to needs you to reply + * to a method. To solve this, either avoid the situation, block in a + * separate thread from the main connection-dispatching thread, or use + * dbus_pending_call_set_notify() to avoid blocking. * * @param connection the connection * @param message the message to send @@ -4076,25 +4084,33 @@ _dbus_connection_run_builtin_filters_unlocked_no_update (DBusConnection *connect /** * Processes any incoming data. * - * If there are messages in the incoming queue, - * dbus_connection_dispatch() removes one message from the queue and - * runs any handlers for it (handlers are added with - * dbus_connection_add_filter() or - * dbus_connection_register_object_path() for example). - * * If there's incoming raw data that has not yet been parsed, it is * parsed, which may or may not result in adding messages to the * incoming queue. + * + * The incoming data buffer is filled when the connection reads from + * its underlying transport (such as a socket). Reading usually + * happens in dbus_watch_handle() or dbus_connection_read_write(). * - * The incoming message queue is filled when the connection - * reads from its underlying transport (such as a socket). - * Reading usually happens in dbus_watch_handle() or - * dbus_connection_read_write(). - * - * If any data has been read from the underlying transport, but not - * yet dispatched, the dispatch status will be - * #DBUS_DISPATCH_DATA_REMAINS. See dbus_connection_get_dispatch_status() - * for more on dispatch statuses. + * If there are complete messages in the incoming queue, + * dbus_connection_dispatch() removes one message from the queue and + * processes it. Processing has three steps. + * + * First, any method replies are passed to #DBusPendingCall or + * dbus_connection_send_with_reply_and_block() in order to + * complete the pending method call. + * + * Second, any filters registered with dbus_connection_add_filter() + * are run. If any filter returns #DBUS_HANDLER_RESULT_HANDLED + * then processing stops after that filter. + * + * Third, if the message is a method call it is forwarded to + * any registered object path handlers added with + * dbus_connection_register_object_path() or + * dbus_connection_register_fallback(). + * + * A single call to dbus_connection_dispatch() will process at most + * one message; it will not clear the entire message queue. * * Be careful about calling dbus_connection_dispatch() from inside a * message handler, i.e. calling dbus_connection_dispatch() diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h index 71f2f6a4..befb3e0f 100644 --- a/dbus/dbus-hash.h +++ b/dbus/dbus-hash.h @@ -123,6 +123,8 @@ dbus_bool_t _dbus_hash_table_insert_ulong (DBusHashTable *table, int _dbus_hash_table_get_n_entries (DBusHashTable *table); /* Preallocation */ + +/** A preallocated hash entry */ typedef struct DBusPreallocatedHash DBusPreallocatedHash; DBusPreallocatedHash *_dbus_hash_table_preallocate_entry (DBusHashTable *table); diff --git a/dbus/dbus-marshal-recursive.c b/dbus/dbus-marshal-recursive.c index bcea4c36..7a83e357 100644 --- a/dbus/dbus-marshal-recursive.c +++ b/dbus/dbus-marshal-recursive.c @@ -321,7 +321,7 @@ skip_one_complete_type (const DBusString *type_str, * type position is stored in the same variable. * * @param type_str a type signature (must be valid) - * @param type_pos an integer position in the type signtaure (in and out) + * @param type_pos an integer position in the type signature (in and out) */ void _dbus_type_signature_next (const char *type_str, diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h index e5f0bdae..a390aae3 100644 --- a/dbus/dbus-marshal-validate.h +++ b/dbus/dbus-marshal-validate.h @@ -183,11 +183,17 @@ _dbus_check_is_valid_##what (const char *name) \ } #endif /* !DBUS_DISABLE_CHECKS */ +/** defines _dbus_check_is_valid_path() */ DECLARE_DBUS_NAME_CHECK(path); +/** defines _dbus_check_is_valid_interface() */ DECLARE_DBUS_NAME_CHECK(interface); +/** defines _dbus_check_is_valid_member() */ DECLARE_DBUS_NAME_CHECK(member); +/** defines _dbus_check_is_valid_error_name() */ DECLARE_DBUS_NAME_CHECK(error_name); +/** defines _dbus_check_is_valid_bus_name() */ DECLARE_DBUS_NAME_CHECK(bus_name); +/** defines _dbus_check_is_valid_signature() */ DECLARE_DBUS_NAME_CHECK(signature); /** @} */ diff --git a/dbus/dbus-pending-call.c b/dbus/dbus-pending-call.c index 403bf57c..ba174ef5 100644 --- a/dbus/dbus-pending-call.c +++ b/dbus/dbus-pending-call.c @@ -615,8 +615,14 @@ dbus_pending_call_set_notify (DBusPendingCall *pending, * Cancels the pending call, such that any reply or error received * will just be ignored. Drops the dbus library's internal reference * to the #DBusPendingCall so will free the call if nobody else is - * holding a reference. However you usually get a reference - * from dbus_connection_send() so probably your app owns a ref also. + * holding a reference. However you usually get a reference from + * dbus_connection_send_with_reply() so probably your app owns a ref + * also. + * + * Note that canceling a pending call will <em>not</em> simulate a + * timed-out call; if a call times out, then a timeout error reply is + * received. If you cancel the call, no reply is received unless the + * the reply was already received before you canceled. * * @param pending the pending call */ diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h index 6198fd88..c7693cd6 100644 --- a/dbus/dbus-protocol.h +++ b/dbus/dbus-protocol.h @@ -50,10 +50,10 @@ extern "C" { /* Message byte order */ -#define DBUS_LITTLE_ENDIAN ('l') /**< LSB first */ -#define DBUS_BIG_ENDIAN ('B') /**< MSB first */ +#define DBUS_LITTLE_ENDIAN ('l') /**< Code marking LSB-first byte order in the wire protocol. */ +#define DBUS_BIG_ENDIAN ('B') /**< Code marking MSB-first byte order in the wire protocol. */ -/** Protocol version */ +/** Protocol version. */ #define DBUS_MAJOR_PROTOCOL_VERSION 1 /** Type code that is never equal to a legitimate type code */ diff --git a/dbus/dbus-server.c b/dbus/dbus-server.c index 0fe8adc0..f5c8e7cc 100644 --- a/dbus/dbus-server.c +++ b/dbus/dbus-server.c @@ -36,12 +36,11 @@ * @ingroup DBus * @brief Server that listens for new connections. * - * Types and functions related to DBusServer. * A DBusServer represents a server that other applications * can connect to. Each connection from another application - * is represented by a DBusConnection. + * is represented by a #DBusConnection. * - * @todo Thread safety hasn't been looked at for #DBusServer + * @todo Thread safety hasn't been tested much for #DBusServer * @todo Need notification to apps of disconnection, may matter for some transports */ @@ -518,20 +517,23 @@ static const struct { }; /** - * Listens for new connections on the given address. - * If there are multiple address entries in the address, - * tries each one and listens on the first one that - * works. + * Listens for new connections on the given address. If there are + * multiple semicolon-separated address entries in the address, tries + * each one and listens on the first one that works. * * Returns #NULL and sets error if listening fails for any reason. * Otherwise returns a new #DBusServer. - * dbus_server_set_new_connection_function() and - * dbus_server_set_watch_functions() should be called - * immediately to render the server fully functional. + * dbus_server_set_new_connection_function(), + * dbus_server_set_watch_functions(), and + * dbus_server_set_timeout_functions() should be called immediately to + * render the server fully functional. + * + * To free the server, applications must call first + * dbus_server_disconnect() and then dbus_server_unref(). * * @param address the address of this server. - * @param error location to store rationale for failure. - * @returns a new DBusServer, or #NULL on failure. + * @param error location to store reason for failure. + * @returns a new #DBusServer, or #NULL on failure. * */ DBusServer* @@ -841,7 +843,7 @@ dbus_server_set_new_connection_function (DBusServer *server, } /** - * Sets the watch functions for the connection. These functions are + * Sets the watch functions for the server. These functions are * responsible for making the application's main loop aware of file * descriptors that need to be monitored for events. * @@ -895,7 +897,7 @@ dbus_server_set_watch_functions (DBusServer *server, } /** - * Sets the timeout functions for the connection. These functions are + * Sets the timeout functions for the server. These functions are * responsible for making the application's main loop aware of timeouts. * * This function behaves exactly like dbus_connection_set_timeout_functions(); @@ -948,10 +950,13 @@ dbus_server_set_timeout_functions (DBusServer *server, } /** - * Sets the authentication mechanisms that this server offers - * to clients, as a list of SASL mechanisms. This function - * only affects connections created *after* it is called. - * Pass #NULL instead of an array to use all available mechanisms. + * Sets the authentication mechanisms that this server offers to + * clients, as a #NULL-terminated array of mechanism names. This + * function only affects connections created <em>after</em> it is + * called. Pass #NULL instead of an array to use all available + * mechanisms (this is the default behavior). + * + * The D-Bus specification describes some of the supported mechanisms. * * @param server the server * @param mechanisms #NULL-terminated array of mechanisms diff --git a/dbus/dbus-shared.h b/dbus/dbus-shared.h index 6d9284e7..e02cad4d 100644 --- a/dbus/dbus-shared.h +++ b/dbus/dbus-shared.h @@ -116,8 +116,8 @@ typedef enum #define DBUS_RELEASE_NAME_REPLY_NOT_OWNER 3 /**< Service is not an owner of the given name */ /* Replies to service starts */ -#define DBUS_START_REPLY_SUCCESS 1 /**< service was auto started */ -#define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< service was already running */ +#define DBUS_START_REPLY_SUCCESS 1 /**< Service was auto started */ +#define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< Service was already running */ /** @} */ diff --git a/dbus/dbus-signature.c b/dbus/dbus-signature.c index 233310ed..c756f1c2 100644 --- a/dbus/dbus-signature.c +++ b/dbus/dbus-signature.c @@ -37,6 +37,14 @@ typedef struct unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */ } DBusSignatureRealIter; +/** macro that checks whether a typecode is a container type */ +#define TYPE_IS_CONTAINER(typecode) \ + ((typecode) == DBUS_TYPE_STRUCT || \ + (typecode) == DBUS_TYPE_DICT_ENTRY || \ + (typecode) == DBUS_TYPE_VARIANT || \ + (typecode) == DBUS_TYPE_ARRAY) + + /** * @defgroup DBusSignature Type signature parsing * @ingroup DBus @@ -73,10 +81,10 @@ dbus_signature_iter_init (DBusSignatureIter *iter, * character such as '(' for a structure, the corresponding type for * the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('. * In this case, you should initialize a sub-iterator with - * dbus_signature_iter_recurse to parse the container type. + * dbus_signature_iter_recurse() to parse the container type. * * @param iter pointer to an iterator - * @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY) + * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY) */ int dbus_signature_iter_get_current_type (const DBusSignatureIter *iter) @@ -87,11 +95,16 @@ dbus_signature_iter_get_current_type (const DBusSignatureIter *iter) } /** - * Returns the full type signature represented by the current - * iterator as a C string. + * Returns the signature of the single complete type starting at the + * given iterator. + * + * For example, if the iterator is pointing at the start of "(ii)ii" + * (which is "a struct of two ints, followed by an int, followed by an + * int"), then "(ii)" would be returned. If the iterator is pointing at + * one of the "i" then just that "i" would be returned. * * @param iter pointer to an iterator - * @returns current signature; or NULL on OOM. Should be freed with #dbus_free + * @returns current signature; or #NULL if no memory. Should be freed with dbus_free() */ char * dbus_signature_iter_get_signature (const DBusSignatureIter *iter) @@ -121,8 +134,8 @@ dbus_signature_iter_get_signature (const DBusSignatureIter *iter) * This function allows you to avoid initializing a sub-iterator and * getting its current type. * - * It is an error to invoke this function if the current type of the - * iterator is not DBUS_TYPE_ARRAY. + * Undefined behavior results if you invoke this function when the + * current type of the iterator is not #DBUS_TYPE_ARRAY. * * @param iter pointer to an iterator * @returns current array element type @@ -139,7 +152,7 @@ dbus_signature_iter_get_element_type (const DBusSignatureIter *iter) /** * Skip to the next value on this "level". e.g. the next field in a - * struct, the next value in an array. Returns FALSE at the end of the + * struct, the next value in an array. Returns #FALSE at the end of the * current container. * * @param iter the iterator @@ -178,9 +191,12 @@ dbus_signature_iter_next (DBusSignatureIter *iter) } /** - * Initialize a new iterator pointing to the first type current - * container. It's an error to call this if the current type is a - * non-container (i.e. if dbus_type_is_container returns FALSE). + * Initialize a new iterator pointing to the first type in the current + * container. + * + * The results are undefined when calling this if the current type is + * a non-container (i.e. if dbus_type_is_container() returns #FALSE + * for the result of dbus_signature_iter_get_current_type()). * * @param iter the current interator * @param subiter an iterator to initialize pointing to the first child @@ -203,11 +219,13 @@ dbus_signature_iter_recurse (const DBusSignatureIter *iter, } /** - * Check a type signature for validity. + * Check a type signature for validity. Remember that #NULL can always + * be passed instead of a DBusError*, if you don't care about having + * an error name and message. * * @param signature a potentially invalid type signature * @param error error return - * @returns TRUE iif signature is valid + * @returns #TRUE if signature is valid or #FALSE if an error is set */ dbus_bool_t dbus_signature_validate (const char *signature, @@ -224,12 +242,15 @@ dbus_signature_validate (const char *signature, } /** - * Check that a type signature is both valid and contains exactly - * one complete type. + * Check that a type signature is both valid and contains exactly one + * complete type. "One complete type" means a single basic type, + * array, struct, or dictionary, though the struct or array may be + * arbitrarily recursive and complex. More than one complete type + * would mean for example "ii" or two integers in sequence. * * @param signature a potentially invalid type signature * @param error error return - * @returns TRUE iif signature is valid and has exactly one complete type + * @returns #TRUE if signature is valid and has exactly one complete type */ dbus_bool_t dbus_signature_validate_single (const char *signature, @@ -250,16 +271,10 @@ dbus_signature_validate_single (const char *signature, return FALSE; } -/** macro that checks whether a typecode is a container type */ -#define TYPE_IS_CONTAINER(typecode) \ - ((typecode) == DBUS_TYPE_STRUCT || \ - (typecode) == DBUS_TYPE_DICT_ENTRY || \ - (typecode) == DBUS_TYPE_VARIANT || \ - (typecode) == DBUS_TYPE_ARRAY) - /** * A "container type" can contain basic types, or nested * container types. #DBUS_TYPE_INVALID is not a container type. + * * This function will crash if passed a typecode that isn't * in dbus-protocol.h * @@ -275,15 +290,15 @@ dbus_type_is_container (int typecode) } /** - * A "basic type" is a somewhat arbitrary concept, but the intent - * is to include those types that are fully-specified by a single - * typecode, with no additional type information or nested - * values. So all numbers and strings are basic types and - * structs, arrays, and variants are not basic types. - * #DBUS_TYPE_INVALID is not a basic type. + * A "basic type" is a somewhat arbitrary concept, but the intent is + * to include those types that are fully-specified by a single + * typecode, with no additional type information or nested values. So + * all numbers and strings are basic types and structs, arrays, and + * variants are not basic types. #DBUS_TYPE_INVALID is not a basic + * type. * * This function will crash if passed a typecode that isn't - * in dbus-protocol.h + * in dbus-protocol.h * * @returns #TRUE if type is basic */ @@ -304,14 +319,25 @@ dbus_type_is_basic (int typecode) * first byte of the old and new value would be in the same location, * so alignment padding is not a factor. * - * This function is useful to determine whether #dbus_message_iter_get_fixed_array - * may be used. + * This function is useful to determine whether + * dbus_message_iter_get_fixed_array() may be used. + * + * Some structs are fixed-size (if they contain only fixed-size types) + * but struct is not considered a fixed type for purposes of this + * function. * + * This function will crash if passed a typecode that isn't + * in dbus-protocol.h + * * @returns #FALSE if the type can occupy different lengths */ dbus_bool_t dbus_type_is_fixed (int typecode) { + /* only reasonable (non-line-noise) typecodes are allowed */ + _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID, + FALSE); + switch (typecode) { case DBUS_TYPE_BYTE: diff --git a/dbus/dbus-sysdeps.h b/dbus/dbus-sysdeps.h index 98ea8d1d..77eda965 100644 --- a/dbus/dbus-sysdeps.h +++ b/dbus/dbus-sysdeps.h @@ -56,41 +56,51 @@ DBUS_BEGIN_DECLS * dbus-memory.c) */ +/** An opaque string type */ typedef struct DBusString DBusString; #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4) #define _DBUS_GNUC_PRINTF( format_idx, arg_idx ) \ __attribute__((__format__ (__printf__, format_idx, arg_idx))) -#define _DBUS_GNUC_SCANF( format_idx, arg_idx ) \ - __attribute__((__format__ (__scanf__, format_idx, arg_idx))) -#define _DBUS_GNUC_FORMAT( arg_idx ) \ - __attribute__((__format_arg__ (arg_idx))) #define _DBUS_GNUC_NORETURN \ __attribute__((__noreturn__)) #else /* !__GNUC__ */ #define _DBUS_GNUC_PRINTF( format_idx, arg_idx ) -#define _DBUS_GNUC_SCANF( format_idx, arg_idx ) -#define _DBUS_GNUC_FORMAT( arg_idx ) #define _DBUS_GNUC_NORETURN #endif /* !__GNUC__ */ +/** @def _DBUS_GNUC_PRINTF + * used to tell gcc about printf format strings + */ +/** @def _DBUS_GNUC_NORETURN + * used to tell gcc about functions that never return, such as _dbus_abort() + */ + void _dbus_abort (void) _DBUS_GNUC_NORETURN; const char* _dbus_getenv (const char *varname); dbus_bool_t _dbus_setenv (const char *varname, const char *value); - +/** A process ID */ typedef unsigned long dbus_pid_t; +/** A user ID */ typedef unsigned long dbus_uid_t; +/** A group ID */ typedef unsigned long dbus_gid_t; +/** an invalid PID used to represent an uninitialized dbus_pid_t field */ #define DBUS_PID_UNSET ((dbus_pid_t) -1) +/** an invalid UID used to represent an uninitialized dbus_uid_t field */ #define DBUS_UID_UNSET ((dbus_uid_t) -1) +/** an invalid GID used to represent an uninitialized dbus_gid_t field */ #define DBUS_GID_UNSET ((dbus_gid_t) -1) +/** an appropriate printf format for dbus_pid_t */ #define DBUS_PID_FORMAT "%lu" +/** an appropriate printf format for dbus_uid_t */ #define DBUS_UID_FORMAT "%lu" +/** an appropriate printf format for dbus_gid_t */ #define DBUS_GID_FORMAT "%lu" @@ -156,7 +166,9 @@ dbus_bool_t _dbus_credentials_match (const DBusCredentials *expec const DBusCredentials *provided_credentials); +/** Information about a UNIX user */ typedef struct DBusUserInfo DBusUserInfo; +/** Information about a UNIX group */ typedef struct DBusGroupInfo DBusGroupInfo; /** @@ -202,10 +214,13 @@ unsigned long _dbus_getpid (void); dbus_uid_t _dbus_getuid (void); dbus_gid_t _dbus_getgid (void); +/** Opaque type representing an atomically-modifiable integer + * that can be used from multiple threads. + */ typedef struct DBusAtomic DBusAtomic; /** - * An atomic integer. + * An atomic integer safe to increment or decrement from multiple threads. */ struct DBusAtomic { @@ -215,12 +230,18 @@ struct DBusAtomic dbus_int32_t _dbus_atomic_inc (DBusAtomic *atomic); dbus_int32_t _dbus_atomic_dec (DBusAtomic *atomic); -#define _DBUS_POLLIN 0x0001 /* There is data to read */ -#define _DBUS_POLLPRI 0x0002 /* There is urgent data to read */ -#define _DBUS_POLLOUT 0x0004 /* Writing now will not block */ -#define _DBUS_POLLERR 0x0008 /* Error condition */ -#define _DBUS_POLLHUP 0x0010 /* Hung up */ -#define _DBUS_POLLNVAL 0x0020 /* Invalid request: fd not open */ +/** There is data to read */ +#define _DBUS_POLLIN 0x0001 +/** There is urgent data to read */ +#define _DBUS_POLLPRI 0x0002 +/** Writing now will not block */ +#define _DBUS_POLLOUT 0x0004 +/** Error condition */ +#define _DBUS_POLLERR 0x0008 +/** Hung up */ +#define _DBUS_POLLHUP 0x0010 +/** Invalid request: fd not open */ +#define _DBUS_POLLNVAL 0x0020 /** * A portable struct pollfd wrapper. @@ -267,6 +288,7 @@ dbus_bool_t _dbus_string_get_dirname (const DBusString *filename, DBusString *dirname); dbus_bool_t _dbus_path_is_absolute (const DBusString *filename); +/** Opaque type for reading a directory listing */ typedef struct DBusDirIter DBusDirIter; DBusDirIter* _dbus_directory_open (const DBusString *filename, @@ -295,7 +317,6 @@ dbus_bool_t _dbus_generate_random_bytes (DBusString *str, dbus_bool_t _dbus_generate_random_ascii (DBusString *str, int n_bytes); -const char *_dbus_errno_to_string (int errnum); const char* _dbus_error_from_errno (int error_number); void _dbus_disable_sigpipe (void); @@ -342,6 +363,7 @@ dbus_bool_t _dbus_change_identity (unsigned long uid, unsigned long gid, DBusError *error); +/** A UNIX signal handler */ typedef void (* DBusSignalHandler) (int sig); void _dbus_set_signal_handler (int sig, @@ -363,12 +385,18 @@ dbus_bool_t _dbus_user_at_console (const char *username, # endif /* va_list is a pointer */ #endif /* !DBUS_VA_COPY */ -/* On x86 there is an 80-bit FPU, and if you do "a == b" it may have a - * or b in an 80-bit register, thus failing to compare the two 64-bit - * doubles for bitwise equality. + +/** + * Casts a primitive C type to a byte array and then indexes + * a particular byte of the array. */ #define _DBUS_BYTE_OF_PRIMITIVE(p, i) \ (((const char*)&(p))[(i)]) +/** On x86 there is an 80-bit FPU, and if you do "a == b" it may have a + * or b in an 80-bit register, thus failing to compare the two 64-bit + * doubles for bitwise equality. So this macro compares the two doubles + * bitwise. + */ #define _DBUS_DOUBLES_BITWISE_EQUAL(a, b) \ (_DBUS_BYTE_OF_PRIMITIVE (a, 0) == _DBUS_BYTE_OF_PRIMITIVE (b, 0) && \ _DBUS_BYTE_OF_PRIMITIVE (a, 1) == _DBUS_BYTE_OF_PRIMITIVE (b, 1) && \ @@ -385,6 +413,9 @@ dbus_bool_t _dbus_parse_uid (const DBusString *uid_str, dbus_bool_t _dbus_get_autolaunch_address (DBusString *address, DBusError *error); +/** Type representing a universally unique ID + * @todo rename to UUID instead of GUID + */ typedef union DBusGUID DBusGUID; dbus_bool_t _dbus_read_local_machine_uuid (DBusGUID *machine_id, diff --git a/dbus/dbus-timeout.h b/dbus/dbus-timeout.h index 1ebf891e..8188920a 100644 --- a/dbus/dbus-timeout.h +++ b/dbus/dbus-timeout.h @@ -37,6 +37,7 @@ DBUS_BEGIN_DECLS typedef struct DBusTimeoutList DBusTimeoutList; +/** function to run when the timeout is handled */ typedef dbus_bool_t (* DBusTimeoutHandler) (void *data); DBusTimeout* _dbus_timeout_new (int interval, diff --git a/dbus/dbus-watch.h b/dbus/dbus-watch.h index cbb5945c..428307b1 100644 --- a/dbus/dbus-watch.h +++ b/dbus/dbus-watch.h @@ -37,6 +37,7 @@ DBUS_BEGIN_DECLS typedef struct DBusWatchList DBusWatchList; +/** function to run when the watch is handled */ typedef dbus_bool_t (* DBusWatchHandler) (DBusWatch *watch, unsigned int flags, void *data); |