* Make Doxygen contented.
+2003-09-07 Havoc Pennington <hp@pobox.com>
+
+ * Make Doxygen contented.
+
2003-09-07 Havoc Pennington <hp@pobox.com>
* doc/dbus-specification.sgml: more updates
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
-INPUT = dbus bus glib
+INPUT = dbus glib
FILE_PATTERNS = *.c *.h
RECURSIVE = YES
#EXCLUDE = test
} Element;
+/**
+ * Parser for bus configuration file.
+ */
struct BusConfigParser
{
- int refcount;
+ int refcount; /**< Reference count */
DBusString basedir; /**< Directory we resolve paths relative to */
int n_allocated_sections;
};
+/**
+ * Parser for service files.
+ */
typedef struct
{
- DBusString data;
+ DBusString data; /**< The data from the file */
- BusDesktopFile *desktop_file;
- int current_section;
+ BusDesktopFile *desktop_file; /**< The resulting object */
+ int current_section; /**< The current section being parsed */
- int pos, len;
- int line_num;
+ int pos; /**< Current position */
+ int len; /**< Length */
+ int line_num; /**< Current line number */
} BusDesktopFileParser;
bus_service_ref (service);
}
+/**
+ * Data used to represent an ownership cancellation in
+ * a bus transaction.
+ */
typedef struct
{
- DBusConnection *connection;
- BusService *service;
+ DBusConnection *connection; /**< the connection */
+ BusService *service; /**< service to cancel ownership of */
} OwnershipCancelData;
static void
#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)
{
dbus_free (entry);
}
+/**
+ * @defgroup DBusAddress Address parsing
+ * @ingroup DBus
+ * @brief Parsing addresses of D-BUS servers.
+ *
+ * @{
+ */
/**
* Frees a #NULL-terminated array of address entries.
}
-/** @} */
+/** @} */ /* End of public API */
#ifdef DBUS_BUILD_TESTS
#include "dbus-test.h"
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;
/**
*/
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;
/**
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 */
* @{
*/
+/**
+ * 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;
return res;
}
-struct DBusPreallocatedSend
-{
- DBusConnection *connection;
- DBusList *queue_link;
- DBusList *counter_link;
-};
-
static DBusPreallocatedSend*
_dbus_connection_preallocate_send_unlocked (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
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,
};
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 */
DBusMutex *lock; /**< thread lock */
};
+/**
+ * Data structure that stores the actual user data set at a given
+ * slot.
+ */
struct DBusDataSlotList
{
DBusDataSlot *slots; /**< Data slots */
#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 */
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
dbus_set_error_const (error, DBUS_ERROR_NO_MEMORY, NULL);
}
-/** @} */
+/** @} */ /* End public API */
typedef struct DBusError DBusError;
+/**
+ * Object representing an exception.
+ */
struct DBusError
{
const char *name; /**< error name */
return h;
}
+/** Key comparison function */
typedef int (* KeyCompareFunc) (const void *key_a, const void *key_b);
static DBusHashEntry*
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;
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. */
}
#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";
#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 */
#include "dbus-mainloop.h"
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
#include <dbus/dbus-list.h>
#include <dbus/dbus-sysdeps.h>
_dbus_sleep_milliseconds (_dbus_get_oom_wait ());
}
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DBUS_MAINLOOP_H
#define DBUS_MAINLOOP_H
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
#include <dbus/dbus.h>
typedef struct DBusLoop DBusLoop;
int _dbus_get_oom_wait (void);
void _dbus_wait_for_memory (void);
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
#endif /* DBUS_MAINLOOP_H */
+
}
#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
return FALSE;
}
+/** Set to 1 to get a bunch of spew about disassembling the path string */
#define VERBOSE_DECOMPOSE 0
/**
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);
* @{
*/
+/**
+ * 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 */
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
*/
} 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
/**
* 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()
* 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
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);
* @{
*/
+/** Subnode of the object hierarchy */
typedef struct DBusObjectSubtree DBusObjectSubtree;
static DBusObjectSubtree* _dbus_object_subtree_new (const char *name,
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)
{
return NULL;
}
+/**
+ * Increment the reference count
+ * @param tree the object tree
+ */
void
_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)
{
}
}
+/** Set to 1 to get a bunch of debug spew about finding the
+ * subtree nodes
+ */
#define VERBOSE_FIND 0
static DBusObjectSubtree*
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;
typedef struct DBusServerVTable DBusServerVTable;
+/**
+ * Virtual table to be implemented by all server "subclasses"
+ */
struct DBusServerVTable
{
void (* finalize) (DBusServer *server);
/**< Disconnect this server. */
};
+/**
+ * Internals of DBusServer object
+ */
struct DBusServer
{
int refcount; /**< Reference count. */
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 */
};
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*
}
/**
- * 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.
DBUS_BEGIN_DECLS;
+/**
+ * DBusString object
+ */
struct DBusString
{
void *dummy1; /**< placeholder */
return FALSE;
}
+/**
+ * Internals of directory iterator
+ */
struct DBusDirIter
{
- DIR *d;
+ DIR *d; /**< The DIR* from opendir() */
};
#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,
typedef struct DBusUserInfo DBusUserInfo;
typedef struct DBusGroupInfo DBusGroupInfo;
+/**
+ * Information about a UNIX user
+ */
struct DBusUserInfo
{
dbus_uid_t uid; /**< UID */
char *homedir; /**< Home directory */
};
+/**
+ * Information about a UNIX group
+ */
struct DBusGroupInfo
{
dbus_gid_t gid; /**< GID */
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);
#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,
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,
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;
* @{
*/
+/**
+ * Internals of DBusTimeout
+ */
struct DBusTimeout
{
int refcount; /**< Reference count */
typedef struct DBusTransportVTable DBusTransportVTable;
+/**
+ * The virtual table that must be implemented to
+ * create a new kind of transport.
+ */
struct DBusTransportVTable
{
void (* finalize) (DBusTransport *transport);
/**< 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. */
#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
* @{
*/
+/**
+ * Implementation of DBusWatch
+ */
struct DBusWatch
{
int refcount; /**< Reference count */
#include "dbus-gidl.h"
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
struct NodeInfo
{
int refcount;
}
#endif /* DBUS_BUILD_TESTS */
+
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DBUS_GLIB_IDL_H
#define DBUS_GLIB_IDL_H
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
#include <dbus/dbus.h>
#include <glib.h>
G_END_DECLS
#endif /* DBUS_GLIB_IDL_H */
+
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
typedef struct DBusGObjectInfo DBusGObjectInfo;
typedef struct DBusGMethodInfo DBusGMethodInfo;
+/**
+ * Object typically generated by dbus-glib-tool that
+ * stores a mapping from introspection data to a
+ * function pointer for a C method to be invoked.
+ */
struct DBusGMethodInfo
{
- GCallback function;
- DBusHandleMessageFunction marshaller;
- int data_offset;
+ GCallback function; /**< C method to invoke */
+ DBusHandleMessageFunction marshaller; /**< Marshaller to go DBusMessage to C method */
+ int data_offset; /**< Offset into the introspection data */
};
+/**
+ * Introspection data for a GObject, normally autogenerated by
+ * a tool such as dbus-glib-tool.
+ */
struct DBusGObjectInfo
{
- const DBusGMethodInfo *infos;
- const unsigned char *data;
- void *dbus_internal_padding1;
- void *dbus_internal_padding2;
+ const DBusGMethodInfo *infos; /**< Array of method pointers */
+ const unsigned char *data; /**< Introspection data */
+ void *dbus_internal_padding1; /**< Reserved for expansion */
+ void *dbus_internal_padding2; /**< Reserved for expansion */
};
void dbus_gobject_class_install_info (GObjectClass *object_class,
g_free
};
+/**
+ * Context for Expat parser for introspection data.
+ */
typedef struct
{
- Parser *parser;
- const char *filename;
- GString *content;
- GError **error;
- gboolean failed;
+ Parser *parser; /**< The parser for the introspection data */
+ const char *filename; /**< The filename being loaded */
+ GString *content; /**< The content of the current element */
+ GError **error; /**< Error return location */
+ gboolean failed; /**< True if parse has failed */
} ExpatParseContext;
static dbus_bool_t
*/
typedef struct DBusGSource DBusGSource;
+/**
+ * A GSource subclass for a DBusConnection.
+ */
struct DBusGSource
{
GSource source; /**< the parent GSource */
#define _(x) gettext ((x))
#define N_(x) x
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
#define ELEMENT_IS(name) (strcmp (element_name, (name)) == 0)
typedef struct
{
return parser->result;
}
+
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
* @{
*/
+/**
+ * Internals of DBusGProxy
+ */
struct DBusGProxy
{
- GStaticMutex lock;
- int refcount;
- DBusConnection *connection;
- char *service;
- char *interface;
- char *path;
+ GStaticMutex lock; /**< Thread lock */
+ int refcount; /**< Reference count */
+ DBusConnection *connection; /**< Connection to communicate over */
+ char *service; /**< Service messages go to or NULL */
+ char *interface; /**< Interface messages go to or NULL */
+ char *path; /**< Path messages go to or NULL */
};
+/** Lock the DBusGProxy */
#define LOCK_PROXY(proxy) (g_static_mutex_lock (&(proxy)->lock))
+/** Unlock the DBusGProxy */
#define UNLOCK_PROXY(proxy) (g_static_mutex_unlock (&(proxy)->lock))
static DBusGProxy*
projects / thirdparty / dbus.git / commitdiff
