summaryrefslogtreecommitdiffstats
path: root/dbus
diff options
context:
space:
mode:
Diffstat (limited to 'dbus')
-rw-r--r--dbus/dbus-address.c27
-rw-r--r--dbus/dbus-auth.c40
-rw-r--r--dbus/dbus-connection.c35
-rw-r--r--dbus/dbus-connection.h16
-rw-r--r--dbus/dbus-dataslot.h10
-rw-r--r--dbus/dbus-errors.c84
-rw-r--r--dbus/dbus-errors.h3
-rw-r--r--dbus/dbus-hash.c1
-rw-r--r--dbus/dbus-hash.h18
-rw-r--r--dbus/dbus-internals.c1
-rw-r--r--dbus/dbus-keyring.c3
-rw-r--r--dbus/dbus-mainloop.c3
-rw-r--r--dbus/dbus-mainloop.h5
-rw-r--r--dbus/dbus-marshal.c11
-rw-r--r--dbus/dbus-md5.h9
-rw-r--r--dbus/dbus-message-builder.c5
-rw-r--r--dbus/dbus-message.c10
-rw-r--r--dbus/dbus-message.h33
-rw-r--r--dbus/dbus-object-tree.c60
-rw-r--r--dbus/dbus-server-protected.h6
-rw-r--r--dbus/dbus-sha.h5
-rw-r--r--dbus/dbus-spawn.c29
-rw-r--r--dbus/dbus-string.c2
-rw-r--r--dbus/dbus-string.h3
-rw-r--r--dbus/dbus-sysdeps.c5
-rw-r--r--dbus/dbus-sysdeps.h50
-rw-r--r--dbus/dbus-threads.h46
-rw-r--r--dbus/dbus-timeout.c3
-rw-r--r--dbus/dbus-transport-protected.h10
-rw-r--r--dbus/dbus-userdb.c13
-rw-r--r--dbus/dbus-watch.c3
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 */