diff options
Diffstat (limited to 'dbus')
| -rw-r--r-- | dbus/dbus-address.c | 27 | ||||
| -rw-r--r-- | dbus/dbus-auth.c | 40 | ||||
| -rw-r--r-- | dbus/dbus-connection.c | 35 | ||||
| -rw-r--r-- | dbus/dbus-connection.h | 16 | ||||
| -rw-r--r-- | dbus/dbus-dataslot.h | 10 | ||||
| -rw-r--r-- | dbus/dbus-errors.c | 84 | ||||
| -rw-r--r-- | dbus/dbus-errors.h | 3 | ||||
| -rw-r--r-- | dbus/dbus-hash.c | 1 | ||||
| -rw-r--r-- | dbus/dbus-hash.h | 18 | ||||
| -rw-r--r-- | dbus/dbus-internals.c | 1 | ||||
| -rw-r--r-- | dbus/dbus-keyring.c | 3 | ||||
| -rw-r--r-- | dbus/dbus-mainloop.c | 3 | ||||
| -rw-r--r-- | dbus/dbus-mainloop.h | 5 | ||||
| -rw-r--r-- | dbus/dbus-marshal.c | 11 | ||||
| -rw-r--r-- | dbus/dbus-md5.h | 9 | ||||
| -rw-r--r-- | dbus/dbus-message-builder.c | 5 | ||||
| -rw-r--r-- | dbus/dbus-message.c | 10 | ||||
| -rw-r--r-- | dbus/dbus-message.h | 33 | ||||
| -rw-r--r-- | dbus/dbus-object-tree.c | 60 | ||||
| -rw-r--r-- | dbus/dbus-server-protected.h | 6 | ||||
| -rw-r--r-- | dbus/dbus-sha.h | 5 | ||||
| -rw-r--r-- | dbus/dbus-spawn.c | 29 | ||||
| -rw-r--r-- | dbus/dbus-string.c | 2 | ||||
| -rw-r--r-- | dbus/dbus-string.h | 3 | ||||
| -rw-r--r-- | dbus/dbus-sysdeps.c | 5 | ||||
| -rw-r--r-- | dbus/dbus-sysdeps.h | 50 | ||||
| -rw-r--r-- | dbus/dbus-threads.h | 46 | ||||
| -rw-r--r-- | dbus/dbus-timeout.c | 3 | ||||
| -rw-r--r-- | dbus/dbus-transport-protected.h | 10 | ||||
| -rw-r--r-- | dbus/dbus-userdb.c | 13 | ||||
| -rw-r--r-- | dbus/dbus-watch.c | 3 |
31 files changed, 369 insertions, 180 deletions
diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c index 89dac41e..97af49fd 100644 --- a/dbus/dbus-address.c +++ b/dbus/dbus-address.c @@ -28,20 +28,26 @@ #include "dbus-string.h" /** - * @defgroup DBusAddress Address parsing - * @ingroup DBus - * @brief Parsing addresses of D-BUS servers. + * @defgroup DBusAddressInternals Address parsing + * @ingroup DBusInternals + * @brief Implementation of parsing addresses of D-BUS servers. * * @{ */ + +/** + * Internals of DBusAddressEntry + */ struct DBusAddressEntry { - DBusString method; + DBusString method; /**< The address type (unix, tcp, etc.) */ - DBusList *keys; - DBusList *values; + DBusList *keys; /**< List of keys */ + DBusList *values; /**< List of values */ }; +/** @} */ /* End of internals */ + static void dbus_address_entry_free (DBusAddressEntry *entry) { @@ -72,6 +78,13 @@ dbus_address_entry_free (DBusAddressEntry *entry) dbus_free (entry); } +/** + * @defgroup DBusAddress Address parsing + * @ingroup DBus + * @brief Parsing addresses of D-BUS servers. + * + * @{ + */ /** * Frees a #NULL-terminated array of address entries. @@ -372,7 +385,7 @@ dbus_parse_address (const char *address, } -/** @} */ +/** @} */ /* End of public API */ #ifdef DBUS_BUILD_TESTS #include "dbus-test.h" diff --git a/dbus/dbus-auth.c b/dbus/dbus-auth.c index 95910445..90c72fd5 100644 --- a/dbus/dbus-auth.c +++ b/dbus/dbus-auth.c @@ -73,10 +73,13 @@ typedef dbus_bool_t (* DBusProcessAuthCommandFunction) (DBusAuth *auth, const DBusString *command, const DBusString *args); +/** + * Handler for a given auth protocol command + */ typedef struct { - const char *command; - DBusProcessAuthCommandFunction func; + const char *command; /**< Name of the command */ + DBusProcessAuthCommandFunction func; /**< Function to handle the command */ } DBusAuthCommandHandler; /** @@ -111,18 +114,21 @@ typedef dbus_bool_t (* DBusAuthDecodeFunction) (DBusAuth *auth, */ typedef void (* DBusAuthShutdownFunction) (DBusAuth *auth); +/** + * Virtual table representing a particular auth mechanism. + */ typedef struct { - const char *mechanism; - DBusAuthDataFunction server_data_func; - DBusAuthEncodeFunction server_encode_func; - DBusAuthDecodeFunction server_decode_func; - DBusAuthShutdownFunction server_shutdown_func; - DBusInitialResponseFunction client_initial_response_func; - DBusAuthDataFunction client_data_func; - DBusAuthEncodeFunction client_encode_func; - DBusAuthDecodeFunction client_decode_func; - DBusAuthShutdownFunction client_shutdown_func; + const char *mechanism; /**< Name of the mechanism */ + DBusAuthDataFunction server_data_func; /**< Function on server side for DATA */ + DBusAuthEncodeFunction server_encode_func; /**< Function on server side to encode */ + DBusAuthDecodeFunction server_decode_func; /**< Function on server side to decode */ + DBusAuthShutdownFunction server_shutdown_func; /**< Function on server side to shut down */ + DBusInitialResponseFunction client_initial_response_func; /**< Function on client side to handle initial response */ + DBusAuthDataFunction client_data_func; /**< Function on client side for DATA */ + DBusAuthEncodeFunction client_encode_func; /**< Function on client side for encode */ + DBusAuthDecodeFunction client_decode_func; /**< Function on client side for decode */ + DBusAuthShutdownFunction client_shutdown_func; /**< Function on client side for shutdown */ } DBusAuthMechanismHandler; /** @@ -172,17 +178,23 @@ struct DBusAuth unsigned int buffer_outstanding : 1; /**< Buffer is "checked out" for reading data into */ }; +/** + * "Subclass" of DBusAuth for client side + */ typedef struct { - DBusAuth base; + DBusAuth base; /**< Parent class */ DBusList *mechs_to_try; /**< Mechanisms we got from the server that we're going to try using */ } DBusAuthClient; +/** + * "Subclass" of DBusAuth for server side. + */ typedef struct { - DBusAuth base; + DBusAuth base; /**< Parent class */ int failures; /**< Number of times client has been rejected */ int max_failures; /**< Number of times we reject before disconnect */ diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index b8e67c14..bab6ffd8 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -124,14 +124,31 @@ * @{ */ +/** + * Internal struct representing a message filter function + */ typedef struct DBusMessageFilter DBusMessageFilter; +/** + * Internal struct representing a message filter function + */ struct DBusMessageFilter { - DBusAtomic refcount; - DBusHandleMessageFunction function; - void *user_data; - DBusFreeFunction free_user_data_function; + DBusAtomic refcount; /**< Reference count */ + DBusHandleMessageFunction function; /**< Function to call to filter */ + void *user_data; /**< User data for the function */ + DBusFreeFunction free_user_data_function; /**< Function to free the user data */ +}; + + +/** + * Internals of DBusPreallocatedSend + */ +struct DBusPreallocatedSend +{ + DBusConnection *connection; /**< Connection we'd send the message to */ + DBusList *queue_link; /**< Preallocated link in the queue */ + DBusList *counter_link; /**< Preallocated link in the resource counter */ }; static dbus_bool_t _dbus_modify_sigpipe = TRUE; @@ -1339,13 +1356,6 @@ dbus_connection_get_is_authenticated (DBusConnection *connection) return res; } -struct DBusPreallocatedSend -{ - DBusConnection *connection; - DBusList *queue_link; - DBusList *counter_link; -}; - static DBusPreallocatedSend* _dbus_connection_preallocate_send_unlocked (DBusConnection *connection) { @@ -2992,7 +3002,8 @@ dbus_connection_add_filter (DBusConnection *connection, * instance). * * @param connection the connection - * @param handler the handler to remove + * @param function the handler to remove + * @param user_data user data for the handler to remove * */ void diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h index bbdbcda8..abc88056 100644 --- a/dbus/dbus-connection.h +++ b/dbus/dbus-connection.h @@ -214,15 +214,19 @@ typedef DBusHandlerResult (* DBusObjectPathMessageFunction) (DBusConnection DBusMessage *message, void *user_data); +/** + * Virtual table that must be implemented to handle a portion of the + * object path hierarchy. + */ struct DBusObjectPathVTable { - DBusObjectPathUnregisterFunction unregister_function; - DBusObjectPathMessageFunction message_function; + DBusObjectPathUnregisterFunction unregister_function; /**< Function to unregister this handler */ + DBusObjectPathMessageFunction message_function; /**< Function to handle messages */ - void (* dbus_internal_pad1) (void *); - void (* dbus_internal_pad2) (void *); - void (* dbus_internal_pad3) (void *); - void (* dbus_internal_pad4) (void *); + void (* dbus_internal_pad1) (void *); /**< Reserved for future expansion */ + void (* dbus_internal_pad2) (void *); /**< Reserved for future expansion */ + void (* dbus_internal_pad3) (void *); /**< Reserved for future expansion */ + void (* dbus_internal_pad4) (void *); /**< Reserved for future expansion */ }; dbus_bool_t dbus_connection_register_object_path (DBusConnection *connection, diff --git a/dbus/dbus-dataslot.h b/dbus/dbus-dataslot.h index 6f591eb5..c4a914b4 100644 --- a/dbus/dbus-dataslot.h +++ b/dbus/dbus-dataslot.h @@ -40,12 +40,18 @@ struct DBusDataSlot }; typedef struct DBusAllocatedSlot DBusAllocatedSlot; + +/** An allocated slot for storing data + */ struct DBusAllocatedSlot { dbus_int32_t slot_id; /**< ID of this slot */ int refcount; /**< Number of uses of the slot */ }; +/** + * An allocator that tracks a set of slot IDs. + */ struct DBusDataSlotAllocator { DBusAllocatedSlot *allocated_slots; /**< Allocated slots */ @@ -54,6 +60,10 @@ struct DBusDataSlotAllocator DBusMutex *lock; /**< thread lock */ }; +/** + * Data structure that stores the actual user data set at a given + * slot. + */ struct DBusDataSlotList { DBusDataSlot *slots; /**< Data slots */ diff --git a/dbus/dbus-errors.c b/dbus/dbus-errors.c index 82e48025..f7b2f740 100644 --- a/dbus/dbus-errors.c +++ b/dbus/dbus-errors.c @@ -28,48 +28,21 @@ #include <string.h> /** - * @defgroup DBusErrors Error reporting - * @ingroup DBus - * @brief Error reporting - * - * Types and functions related to reporting errors. - * - * - * In essence D-BUS error reporting works as follows: - * - * @code - * 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 - * - * 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(). - * + * @defgroup DBusErrorInternals Error reporting internals + * @ingroup DBusInternals + * @brief Error reporting internals * @{ */ - + +/** + * Internals of DBusError + */ typedef struct { const char *name; /**< error name */ char *message; /**< error message */ - unsigned int const_message : 1; /** Message is not owned by DBusError */ + unsigned int const_message : 1; /**< Message is not owned by DBusError */ unsigned int dummy2 : 1; /**< placeholder */ unsigned int dummy3 : 1; /**< placeholder */ @@ -127,6 +100,45 @@ message_from_error (const char *error) return error; } +/** @} */ /* End of internals */ + +/** + * @defgroup DBusErrors Error reporting + * @ingroup DBus + * @brief Error reporting + * + * Types and functions related to reporting errors. + * + * + * In essence D-BUS error reporting works as follows: + * + * @code + * 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 + * + * 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(). + * + * @{ + */ + /** * Initializes a DBusError structure. Does not allocate * any memory; the error only needs to be freed @@ -358,4 +370,4 @@ dbus_set_error (DBusError *error, dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY, NULL); } -/** @} */ +/** @} */ /* End public API */ diff --git a/dbus/dbus-errors.h b/dbus/dbus-errors.h index ca398a0b..ad4801c9 100644 --- a/dbus/dbus-errors.h +++ b/dbus/dbus-errors.h @@ -35,6 +35,9 @@ DBUS_BEGIN_DECLS; typedef struct DBusError DBusError; +/** + * Object representing an exception. + */ struct DBusError { const char *name; /**< error name */ diff --git a/dbus/dbus-hash.c b/dbus/dbus-hash.c index 044dc534..d35087b4 100644 --- a/dbus/dbus-hash.c +++ b/dbus/dbus-hash.c @@ -865,6 +865,7 @@ two_strings_hash (const char *str) return h; } +/** Key comparison function */ typedef int (* KeyCompareFunc) (const void *key_a, const void *key_b); static DBusHashEntry* diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h index 25b81dd6..5e7515f9 100644 --- a/dbus/dbus-hash.h +++ b/dbus/dbus-hash.h @@ -29,17 +29,17 @@ DBUS_BEGIN_DECLS; -/* The iterator is on the stack, but its real fields are - * hidden privately. +/** Hash iterator object. The iterator is on the stack, but its real + * fields are hidden privately. */ struct DBusHashIter { - void *dummy1; - void *dummy2; - void *dummy3; - void *dummy4; - int dummy5; - int dummy6; + void *dummy1; /**< Do not use. */ + void *dummy2; /**< Do not use. */ + void *dummy3; /**< Do not use. */ + void *dummy4; /**< Do not use. */ + int dummy5; /**< Do not use. */ + int dummy6; /**< Do not use. */ }; typedef struct DBusHashTable DBusHashTable; @@ -53,7 +53,7 @@ typedef struct DBusHashIter DBusHashIter; typedef enum { DBUS_HASH_STRING, /**< Hash keys are strings. */ - DBUS_HASH_TWO_STRINGS, /**< Hash key is two strings in one memory block, i.e. foo\0bar\0 */ + DBUS_HASH_TWO_STRINGS, /**< Hash key is two strings in one memory block, i.e. foo\\0bar\\0 */ DBUS_HASH_INT, /**< Hash keys are integers. */ DBUS_HASH_POINTER, /**< Hash keys are pointers. */ DBUS_HASH_ULONG /**< Hash keys are unsigned long. */ diff --git a/dbus/dbus-internals.c b/dbus/dbus-internals.c index 47a2b404..463e62e1 100644 --- a/dbus/dbus-internals.c +++ b/dbus/dbus-internals.c @@ -390,6 +390,7 @@ _dbus_type_to_string (int type) } #ifndef DBUS_DISABLE_CHECKS +/** String used in _dbus_return_if_fail macro */ const char _dbus_return_if_fail_warning_format[] = "Arguments to %s were incorrect, assertion \"%s\" failed in file %s line %d.\n" "This is normally a bug in some application using the D-BUS library.\n"; diff --git a/dbus/dbus-keyring.c b/dbus/dbus-keyring.c index b5974af0..e091d801 100644 --- a/dbus/dbus-keyring.c +++ b/dbus/dbus-keyring.c @@ -85,6 +85,9 @@ #define MAX_KEYS_IN_FILE 256 #endif +/** + * A single key from the cookie file + */ typedef struct { dbus_int32_t id; /**< identifier used to refer to the key */ diff --git a/dbus/dbus-mainloop.c b/dbus/dbus-mainloop.c index 51eb7b0d..f3b68272 100644 --- a/dbus/dbus-mainloop.c +++ b/dbus/dbus-mainloop.c @@ -23,6 +23,8 @@ #include "dbus-mainloop.h" +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include <dbus/dbus-list.h> #include <dbus/dbus-sysdeps.h> @@ -876,3 +878,4 @@ _dbus_wait_for_memory (void) _dbus_sleep_milliseconds (_dbus_get_oom_wait ()); } +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ diff --git a/dbus/dbus-mainloop.h b/dbus/dbus-mainloop.h index ac5731f5..8a3cde13 100644 --- a/dbus/dbus-mainloop.h +++ b/dbus/dbus-mainloop.h @@ -24,6 +24,8 @@ #ifndef DBUS_MAINLOOP_H #define DBUS_MAINLOOP_H +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include <dbus/dbus.h> typedef struct DBusLoop DBusLoop; @@ -68,4 +70,7 @@ dbus_bool_t _dbus_loop_dispatch (DBusLoop *loop); int _dbus_get_oom_wait (void); void _dbus_wait_for_memory (void); +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ + #endif /* DBUS_MAINLOOP_H */ + diff --git a/dbus/dbus-marshal.c b/dbus/dbus-marshal.c index c542ee8b..3d6184e9 100644 --- a/dbus/dbus-marshal.c +++ b/dbus/dbus-marshal.c @@ -73,13 +73,17 @@ swap_bytes (unsigned char *data, } #endif /* !DBUS_HAVE_INT64 */ +/** + * Union used to manipulate 8 bytes as if they + * were various types. + */ typedef union { #ifdef DBUS_HAVE_INT64 - dbus_int64_t s; - dbus_uint64_t u; + dbus_int64_t s; /**< 64-bit integer */ + dbus_uint64_t u; /**< 64-bit unsinged integer */ #endif - double d; + double d; /**< double */ } DBusOctets8; static DBusOctets8 @@ -1470,6 +1474,7 @@ _dbus_demarshal_string_array (const DBusString *str, return FALSE; } +/** Set to 1 to get a bunch of spew about disassembling the path string */ #define VERBOSE_DECOMPOSE 0 /** diff --git a/dbus/dbus-md5.h b/dbus/dbus-md5.h index 63fc62e8..e31711dd 100644 --- a/dbus/dbus-md5.h +++ b/dbus/dbus-md5.h @@ -31,11 +31,14 @@ DBUS_BEGIN_DECLS; typedef struct DBusMD5Context DBusMD5Context; +/** + * A context used to store the state of the MD5 algorithm + */ struct DBusMD5Context { - dbus_uint32_t count[2]; /* message length in bits, lsw first */ - dbus_uint32_t abcd[4]; /* digest buffer */ - unsigned char buf[64]; /* accumulate block */ + dbus_uint32_t count[2]; /**< message length in bits, lsw first */ + dbus_uint32_t abcd[4]; /**< digest buffer */ + unsigned char buf[64]; /**< accumulate block */ }; void _dbus_md5_init (DBusMD5Context *context); diff --git a/dbus/dbus-message-builder.c b/dbus/dbus-message-builder.c index 6d162310..52c78227 100644 --- a/dbus/dbus-message-builder.c +++ b/dbus/dbus-message-builder.c @@ -40,9 +40,12 @@ * @{ */ +/** + * Saved length + */ typedef struct { - DBusString name; + DBusString name; /**< Name of the length */ int start; /**< Calculate length since here */ int length; /**< length to write */ int offset; /**< where to write it into the data */ diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c index 090bdfc7..d62cbf4f 100644 --- a/dbus/dbus-message.c +++ b/dbus/dbus-message.c @@ -72,6 +72,9 @@ static dbus_bool_t field_is_named[FIELD_LAST] = TRUE /* FIELD_REPLY_SERIAL */ }; +/** + * Cached information about a header field in the message + */ typedef struct { int offset; /**< Offset to start of field (location of name of field @@ -79,9 +82,13 @@ typedef struct */ } HeaderField; +/** Offset to byte order from start of header */ #define BYTE_ORDER_OFFSET 0 +/** Offset to type from start of header */ #define TYPE_OFFSET 1 +/** Offset to flags from start of header */ #define FLAGS_OFFSET 2 +/** Offset to version from start of header */ #define VERSION_OFFSET 3 /** @@ -1161,6 +1168,7 @@ dbus_message_new_method_return (DBusMessage *method_call) * A signal is identified by its originating interface, and * the name of the signal. * + * @param path the path to the object emitting the signal * @param interface the interface the signal is emitted from * @param name name of the signal * @returns a new DBusMessage, free with dbus_message_unref() @@ -1576,7 +1584,7 @@ dbus_message_get_member (DBusMessage *message) * The name is fully-qualified (namespaced). * * @param message the message - * @param name the name + * @param error_name the name * @returns #FALSE if not enough memory */ dbus_bool_t diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h index def65379..888fe862 100644 --- a/dbus/dbus-message.h +++ b/dbus/dbus-message.h @@ -39,22 +39,25 @@ DBUS_BEGIN_DECLS; typedef struct DBusMessage DBusMessage; typedef struct DBusMessageIter DBusMessageIter; +/** + * DBusMessageIter struct; contains no public fields + */ struct DBusMessageIter -{ - void *dummy1; - void *dummy2; - dbus_uint32_t dummy3; - int dummy4; - int dummy5; - int dummy6; - int dummy7; - int dummy8; - int dummy9; - int dummy10; - int dummy11; - int pad1; - int pad2; - void *pad3; +{ + void *dummy1; /**< Don't use this */ + void *dummy2; /**< Don't use this */ + dbus_uint32_t dummy3; /**< Don't use this */ + int dummy4; /**< Don't use this */ + int dummy5; /**< Don't use this */ + int dummy6; /**< Don't use this */ + int dummy7; /**< Don't use this */ + int dummy8; /**< Don't use this */ + int dummy9; /**< Don't use this */ + int dummy10; /**< Don't use this */ + int dummy11; /**< Don't use this */ + int pad1; /**< Don't use this */ + int pad2; /**< Don't use this */ + void *pad3; /**< Don't use this */ }; DBusMessage* dbus_message_new (int message_type); diff --git a/dbus/dbus-object-tree.c b/dbus/dbus-object-tree.c index 8430b323..9922dec4 100644 --- a/dbus/dbus-object-tree.c +++ b/dbus/dbus-object-tree.c @@ -45,6 +45,7 @@ * @{ */ +/** Subnode of the object hierarchy */ typedef struct DBusObjectSubtree DBusObjectSubtree; static DBusObjectSubtree* _dbus_object_subtree_new (const char *name, @@ -53,28 +54,43 @@ static DBusObjectSubtree* _dbus_object_subtree_new (const char static void _dbus_object_subtree_ref (DBusObjectSubtree *subtree); static void _dbus_object_subtree_unref (DBusObjectSubtree *subtree); +/** + * Internals of DBusObjectTree + */ struct DBusObjectTree { - int refcount; - DBusConnection *connection; + int refcount; /**< Reference count */ + DBusConnection *connection; /**< Connection this tree belongs to */ - DBusObjectSubtree *root; + DBusObjectSubtree *root; /**< Root of the tree ("/" node) */ }; +/** + * Struct representing a single registered subtree handler, or node + * that's a parent of a registered subtree handler. If + * message_function != NULL there's actually a handler at this node. + */ struct DBusObjectSubtree { - DBusAtomic refcount; - DBusObjectSubtree *parent; - DBusObjectPathUnregisterFunction unregister_function; - DBusObjectPathMessageFunction message_function; - void *user_data; - DBusObjectSubtree **subtrees; - int n_subtrees; - unsigned int subtrees_sorted : 1; - unsigned int invoke_as_fallback : 1; + DBusAtomic refcount; /**< Reference count */ + DBusObjectSubtree *parent; /**< Parent node */ + DBusObjectPathUnregisterFunction unregister_function; /**< Function to call on unregister */ + DBusObjectPathMessageFunction message_function; /**< Function to handle messages */ + void *user_data; /**< Data for functions */ + DBusObjectSubtree **subtrees; /**< Child nodes */ + int n_subtrees; /**< Number of child nodes */ + unsigned int subtrees_sorted : 1; /**< Whether children are sorted */ + unsigned int invoke_as_fallback : 1; /**< Whether to invoke message_function when child nodes don't handle the message */ char name[1]; /**< Allocated as large as necessary */ }; +/** + * Creates a new object tree, representing a mapping from paths + * to handler vtables. + * + * @param connection the connection this tree belongs to + * @returns the new tree or #NULL if no memory + */ DBusObjectTree* _dbus_object_tree_new (DBusConnection *connection) { @@ -107,6 +123,10 @@ _dbus_object_tree_new (DBusConnection *connection) return NULL; } +/** + * Increment the reference count + * @param tree the object tree + */ void _dbus_object_tree_ref (DBusObjectTree *tree) { @@ -115,6 +135,10 @@ _dbus_object_tree_ref (DBusObjectTree *tree) tree->refcount += 1; } +/** + * Decrement the reference count + * @param tree the object tree + */ void _dbus_object_tree_unref (DBusObjectTree *tree) { @@ -160,6 +184,9 @@ ensure_sorted (DBusObjectSubtree *subtree) } } +/** Set to 1 to get a bunch of debug spew about finding the + * subtree nodes + */ #define VERBOSE_FIND 0 static DBusObjectSubtree* @@ -855,11 +882,14 @@ spew_tree (DBusObjectTree *tree) spew_subtree_recurse (tree->root, 0); } +/** + * Callback data used in tests + */ typedef struct { - const char **path; - dbus_bool_t message_handled; - dbus_bool_t handler_unregistered; + const char **path; /**< Path */ + dbus_bool_t message_handled; /**< Gets set to true if message handler called */ + dbus_bool_t handler_unregistered; /**< gets set to true if handler is unregistered */ } TreeTestData; diff --git a/dbus/dbus-server-protected.h b/dbus/dbus-server-protected.h index a3774c31..317805f5 100644 --- a/dbus/dbus-server-protected.h +++ b/dbus/dbus-server-protected.h @@ -34,6 +34,9 @@ DBUS_BEGIN_DECLS; typedef struct DBusServerVTable DBusServerVTable; +/** + * Virtual table to be implemented by all server "subclasses" + */ struct DBusServerVTable { void (* finalize) (DBusServer *server); @@ -43,6 +46,9 @@ struct DBusServerVTable /**< Disconnect this server. */ }; +/** + * Internals of DBusServer object + */ struct DBusServer { int refcount; /**< Reference count. */ diff --git a/dbus/dbus-sha.h b/dbus/dbus-sha.h index 7f793844..0a48d197 100644 --- a/dbus/dbus-sha.h +++ b/dbus/dbus-sha.h @@ -31,11 +31,14 @@ DBUS_BEGIN_DECLS; typedef struct DBusSHAContext DBusSHAContext; +/** + * Struct storing state of the SHA algorithm + */ struct DBusSHAContext { dbus_uint32_t digest[5]; /**< Message digest */ dbus_uint32_t count_lo; /**< 64-bit bit count */ - dbus_uint32_t count_hi; + dbus_uint32_t count_hi; /**< No clue */ dbus_uint32_t data[16]; /**< SHA data buffer */ }; diff --git a/dbus/dbus-spawn.c b/dbus/dbus-spawn.c index d4015561..604b9e7c 100644 --- a/dbus/dbus-spawn.c +++ b/dbus/dbus-spawn.c @@ -176,28 +176,31 @@ enum CHILD_PID /* Followed by pid_t */ }; +/** + * Babysitter implementation details + */ struct DBusBabysitter { - int refcount; + int refcount; /**< Reference count */ char *executable; /**< executable name to use in error messages */ - int socket_to_babysitter; - int error_pipe_from_child; + int socket_to_babysitter; /**< Connection to the babysitter process */ + int error_pipe_from_child; /**< Connection to the process that does the exec() */ - pid_t sitter_pid; - pid_t grandchild_pid; + pid_t sitter_pid; /**< PID Of the babysitter */ + pid_t grandchild_pid; /**< PID of the grandchild */ - DBusWatchList *watches; + DBusWatchList *watches; /**< Watches */ - DBusWatch *error_watch; - DBusWatch *sitter_watch; + DBusWatch *error_watch; /**< Error pipe watch */ + DBusWatch *sitter_watch; /**< Sitter pipe watch */ - int errnum; - int status; - unsigned int have_child_status : 1; - unsigned int have_fork_errnum : 1; - unsigned int have_exec_errnum : 1; + int errnum; /**< Error number */ + int status; /**< Exit status code */ + unsigned int have_child_status : 1; /**< True if child status has been reaped */ + unsigned int have_fork_errnum : 1; /**< True if we have an error code from fork() */ + unsigned int have_exec_errnum : 1; /**< True if we have an error code from exec() */ }; static DBusBabysitter* diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c index 54dbdb7f..40363686 100644 --- a/dbus/dbus-string.c +++ b/dbus/dbus-string.c @@ -1807,7 +1807,7 @@ _dbus_string_skip_white (const DBusString *str, } /** - * Assigns a newline-terminated or \r\n-terminated line from the front + * Assigns a newline-terminated or \\r\\n-terminated line from the front * of the string to the given dest string. The dest string's previous * contents are deleted. If the source string contains no newline, * moves the entire source string to the dest string. diff --git a/dbus/dbus-string.h b/dbus/dbus-string.h index 761ad487..70e83b33 100644 --- a/dbus/dbus-string.h +++ b/dbus/dbus-string.h @@ -34,6 +34,9 @@ DBUS_BEGIN_DECLS; +/** + * DBusString object + */ struct DBusString { void *dummy1; /**< placeholder */ diff --git a/dbus/dbus-sysdeps.c b/dbus/dbus-sysdeps.c index 5311b202..c3ddf8cd 100644 --- a/dbus/dbus-sysdeps.c +++ b/dbus/dbus-sysdeps.c @@ -2515,9 +2515,12 @@ _dbus_path_is_absolute (const DBusString *filename) return FALSE; } +/** + * Internals of directory iterator + */ struct DBusDirIter { - DIR *d; + DIR *d; /**< The DIR* from opendir() */ }; diff --git a/dbus/dbus-sysdeps.h b/dbus/dbus-sysdeps.h index bfdcfb0a..363f665d 100644 --- a/dbus/dbus-sysdeps.h +++ b/dbus/dbus-sysdeps.h @@ -97,12 +97,14 @@ typedef unsigned long dbus_gid_t; #define DBUS_UID_FORMAT "%lu" #define DBUS_GID_FORMAT "%lu" +/** + * Struct representing socket credentials + */ typedef struct { - /* Set to DBUS_PID_UNSET etc. if not available */ - dbus_pid_t pid; - dbus_uid_t uid; - dbus_gid_t gid; + dbus_pid_t pid; /**< process ID or DBUS_PID_UNSET */ + dbus_uid_t uid; /**< user ID or DBUS_UID_UNSET */ + dbus_gid_t gid; /**< group ID or DBUS_GID_UNSET */ } DBusCredentials; int _dbus_connect_unix_socket (const char *path, @@ -135,6 +137,9 @@ dbus_bool_t _dbus_credentials_match (const DBusCredentials *expec typedef struct DBusUserInfo DBusUserInfo; typedef struct DBusGroupInfo DBusGroupInfo; +/** + * Information about a UNIX user + */ struct DBusUserInfo { dbus_uid_t uid; /**< UID */ @@ -145,6 +150,9 @@ struct DBusUserInfo char *homedir; /**< Home directory */ }; +/** + * Information about a UNIX group + */ struct DBusGroupInfo { dbus_gid_t gid; /**< GID */ @@ -173,9 +181,13 @@ dbus_uid_t _dbus_getuid (void); dbus_gid_t _dbus_getgid (void); typedef struct DBusAtomic DBusAtomic; + +/** + * An atomic integer. + */ struct DBusAtomic { - volatile dbus_int32_t value; + volatile dbus_int32_t value; /**< Value of the atomic integer. */ }; dbus_int32_t _dbus_atomic_inc (DBusAtomic *atomic); @@ -188,11 +200,14 @@ dbus_int32_t _dbus_atomic_dec (DBusAtomic *atomic); #define _DBUS_POLLHUP 0x0010 /* Hung up */ #define _DBUS_POLLNVAL 0x0020 /* Invalid request: fd not open */ +/** + * A portable struct pollfd wrapper. + */ typedef struct { - int fd; - short events; - short revents; + int fd; /**< File descriptor */ + short events; /**< Events to poll for */ + short revents; /**< Events that occurred */ } DBusPollFD; int _dbus_poll (DBusPollFD *fds, @@ -249,16 +264,19 @@ void _dbus_fd_set_close_on_exec (int fd); void _dbus_exit (int code) _DBUS_GNUC_NORETURN; +/** + * Portable struct with stat() results + */ typedef struct { - unsigned long mode; - unsigned long nlink; - dbus_uid_t uid; - dbus_gid_t gid; - unsigned long size; - unsigned long atime; - unsigned long mtime; - unsigned long ctime; + unsigned long mode; /**< File mode */ + unsigned long nlink; /**< Number of hard links */ + dbus_uid_t uid; /**< User owning file */ + dbus_gid_t gid; /**< Group owning file */ + unsigned long size; /**< Size of file */ + unsigned long atime; /**< Access time */ + unsigned long mtime; /**< Modify time */ + unsigned long ctime; /**< Creation time */ } DBusStat; dbus_bool_t _dbus_stat (const DBusString *filename, diff --git a/dbus/dbus-threads.h b/dbus/dbus-threads.h index 0dcb1040..dea969a2 100644 --- a/dbus/dbus-threads.h +++ b/dbus/dbus-threads.h @@ -66,30 +66,34 @@ typedef enum DBUS_THREAD_FUNCTIONS_ALL_MASK = (1 << 10) - 1 } DBusThreadFunctionsMask; +/** + * Functions that must be implemented to make the D-BUS + * library thread-aware. + */ typedef struct { - unsigned int mask; - - DBusMutexNewFunction mutex_new; - DBusMutexFreeFunction mutex_free; - DBusMutexLockFunction mutex_lock; - DBusMutexUnlockFunction mutex_unlock; - - DBusCondVarNewFunction condvar_new; - DBusCondVarFreeFunction condvar_free; - DBusCondVarWaitFunction condvar_wait; - DBusCondVarWaitTimeoutFunction condvar_wait_timeout; - DBusCondVarWakeOneFunction condvar_wake_one; - DBusCondVarWakeAllFunction condvar_wake_all; + 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 */ + + DBusCondVarNewFunction condvar_new; /**< Function to create a condition variable */ + DBusCondVarFreeFunction condvar_free; /**< Function to free a condition variable */ + DBusCondVarWaitFunction condvar_wait; /**< Function to wait on a condition */ + DBusCondVarWaitTimeoutFunction condvar_wait_timeout; /**< Function to wait on a condition with a timeout */ + DBusCondVarWakeOneFunction condvar_wake_one; /**< Function to wake one thread waiting on the condition */ + DBusCondVarWakeAllFunction condvar_wake_all; /**< Function to wake all threads waiting on the condition */ - void (* padding1) (void); - void (* padding2) (void); - void (* padding3) (void); - void (* padding4) (void); - void (* padding5) (void); - void (* padding6) (void); - void (* padding7) (void); - void (* padding8) (void); + void (* padding1) (void); /**< Reserved for future expansion */ + void (* padding2) (void); /**< Reserved for future expansion */ + void (* padding3) (void); /**< Reserved for future expansion */ + void (* padding4) (void); /**< Reserved for future expansion */ + void (* padding5) (void); /**< Reserved for future expansion */ + void (* padding6) (void); /**< Reserved for future expansion */ + void (* padding7) (void); /**< Reserved for future expansion */ + void (* padding8) (void); /**< Reserved for future expansion */ } DBusThreadFunctions; diff --git a/dbus/dbus-timeout.c b/dbus/dbus-timeout.c index 289d6347..b15089db 100644 --- a/dbus/dbus-timeout.c +++ b/dbus/dbus-timeout.c @@ -33,6 +33,9 @@ * @{ */ +/** + * Internals of DBusTimeout + */ struct DBusTimeout { int refcount; /**< Reference count */ diff --git a/dbus/dbus-transport-protected.h b/dbus/dbus-transport-protected.h index 1c5b4208..d4d20957 100644 --- a/dbus/dbus-transport-protected.h +++ b/dbus/dbus-transport-protected.h @@ -34,6 +34,10 @@ DBUS_BEGIN_DECLS; typedef struct DBusTransportVTable DBusTransportVTable; +/** + * The virtual table that must be implemented to + * create a new kind of transport. + */ struct DBusTransportVTable { void (* finalize) (DBusTransport *transport); @@ -69,6 +73,12 @@ struct DBusTransportVTable /**< Outstanding messages counter changed */ }; +/** + * Object representing a transport such as a socket. + * A transport can shuttle messages from point A to point B, + * and is the backend for a #DBusConnection. + * + */ struct DBusTransport { int refcount; /**< Reference count. */ diff --git a/dbus/dbus-userdb.c b/dbus/dbus-userdb.c index 4a7b7488..95f13981 100644 --- a/dbus/dbus-userdb.c +++ b/dbus/dbus-userdb.c @@ -26,14 +26,17 @@ #include "dbus-internals.h" #include <string.h> +/** + * Internals of DBusUserDatabase + */ struct DBusUserDatabase { - int refcount; + int refcount; /**< Reference count */ - DBusHashTable *users; - DBusHashTable *groups; - DBusHashTable *users_by_name; - DBusHashTable *groups_by_name; + DBusHashTable *users; /**< Users in the database by UID */ + DBusHashTable *groups; /**< Groups in the database by GID */ + DBusHashTable *users_by_name; /**< Users in the database by name */ + DBusHashTable *groups_by_name; /**< Groups in the database by name */ }; static void diff --git a/dbus/dbus-watch.c b/dbus/dbus-watch.c index 5b59e8c8..f212090a 100644 --- a/dbus/dbus-watch.c +++ b/dbus/dbus-watch.c @@ -33,6 +33,9 @@ * @{ */ +/** + * Implementation of DBusWatch + */ struct DBusWatch { int refcount; /**< Reference count */ |