Commit 85ab0327 authored by Havoc Pennington's avatar Havoc Pennington

2003-09-07 Havoc Pennington <hp@pobox.com>

	* Make Doxygen contented.
parent 32bd6660
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
......
......@@ -49,7 +49,7 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = dbus bus glib
INPUT = dbus glib
FILE_PATTERNS = *.c *.h
RECURSIVE = YES
#EXCLUDE = test
......
......@@ -88,9 +88,12 @@ typedef struct
} Element;
/**
* Parser for bus configuration file.
*/
struct BusConfigParser
{
int refcount;
int refcount; /**< Reference count */
DBusString basedir; /**< Directory we resolve paths relative to */
......
......@@ -48,15 +48,19 @@ struct BusDesktopFile
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;
......
......@@ -417,10 +417,14 @@ bus_service_relink (BusService *service,
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
......
......@@ -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"
......
......@@ -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 */
......
......@@ -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
......
......@@ -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,
......
......@@ -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 */
......
......@@ -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 */
......@@ -35,6 +35,9 @@ DBUS_BEGIN_DECLS;
typedef struct DBusError DBusError;
/**
* Object representing an exception.
*/
struct DBusError
{
const char *name; /**< error name */
......
......@@ -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*
......
......@@ -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. */
......
......@@ -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";
......
......@@ -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 */
......
......@@ -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 */
......@@ -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 */
......@@ -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
/**
......
......@@ -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);
......
......@@ -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 */
......
......@@ -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
......
......@@ -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);
......
......@@ -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