summaryrefslogtreecommitdiffstats
path: root/dbus
diff options
context:
space:
mode:
authorHavoc Pennington <hp@redhat.com>2005-01-16 15:51:55 +0000
committerHavoc Pennington <hp@redhat.com>2005-01-16 15:51:55 +0000
commit31988af4089f3793940417535f8eabaae1ac26c8 (patch)
tree2b0d7016481a34764dd35b6391d05e2629a45f2f /dbus
parentb3416423b1e3c17357833d896c1b7cd684660771 (diff)
2005-01-16 Havoc Pennington <hp@redhat.com>
* Add and fix docs according to Doxygen warnings throughout source. * dbus/dbus-marshal-recursive.c (_dbus_type_reader_array_is_empty): change this to just call array_reader_get_array_len() and make it static * dbus/dbus-message.c (dbus_message_iter_get_element_type): rename from get_array_type (dbus_message_iter_init_append): rename from append_iter_init * dbus/dbus-marshal-recursive.c (_dbus_type_reader_get_element_type): rename from _dbus_type_reader_get_array_type
Diffstat (limited to 'dbus')
-rw-r--r--dbus/dbus-marshal-basic.c1
-rw-r--r--dbus/dbus-marshal-basic.h33
-rw-r--r--dbus/dbus-marshal-header.c9
-rw-r--r--dbus/dbus-marshal-header.h3
-rw-r--r--dbus/dbus-marshal-recursive.c174
-rw-r--r--dbus/dbus-marshal-recursive.h78
-rw-r--r--dbus/dbus-marshal-validate.c12
-rw-r--r--dbus/dbus-marshal-validate.h4
-rw-r--r--dbus/dbus-message.c31
-rw-r--r--dbus/dbus-message.h33
-rw-r--r--dbus/dbus-string.c7
11 files changed, 261 insertions, 124 deletions
diff --git a/dbus/dbus-marshal-basic.c b/dbus/dbus-marshal-basic.c
index a2e32752..0da10358 100644
--- a/dbus/dbus-marshal-basic.c
+++ b/dbus/dbus-marshal-basic.c
@@ -1173,6 +1173,7 @@ _dbus_type_is_valid (int typecode)
}
}
+/** macro that checks whether a typecode is a container type */
#define TYPE_IS_CONTAINER(typecode) \
((typecode) == DBUS_TYPE_STRUCT || \
(typecode) == DBUS_TYPE_VARIANT || \
diff --git a/dbus/dbus-marshal-basic.h b/dbus/dbus-marshal-basic.h
index cf86e713..870fc0f7 100644
--- a/dbus/dbus-marshal-basic.h
+++ b/dbus/dbus-marshal-basic.h
@@ -112,28 +112,37 @@
#define DBUS_UINT64_FROM_BE(val) (DBUS_UINT64_TO_BE (val))
#endif /* DBUS_HAVE_INT64 */
-#ifdef DBUS_HAVE_INT64
+#ifndef DBUS_HAVE_INT64
+/**
+ * An 8-byte struct you could use to access int64 without having
+ * int64 support
+ */
typedef struct
{
- dbus_uint32_t first32;
- dbus_uint32_t second32;
+ dbus_uint32_t first32; /**< first 32 bits in the 8 bytes (beware endian issues) */
+ dbus_uint32_t second32; /**< second 32 bits in the 8 bytes (beware endian issues) */
} DBus8ByteStruct;
#endif /* DBUS_HAVE_INT64 */
+/**
+ * A simple 8-byte value union that lets you access 8 bytes as if they
+ * were various types; useful when dealing with basic types via
+ * void pointers and varargs.
+ */
typedef union
{
- dbus_int32_t i32;
- dbus_uint32_t u32;
+ dbus_int32_t i32; /**< as int32 */
+ dbus_uint32_t u32; /**< as int32 */
#ifdef DBUS_HAVE_INT64
- dbus_int64_t i64;
- dbus_uint64_t u64;
+ dbus_int64_t i64; /**< as int32 */
+ dbus_uint64_t u64; /**< as int32 */
#else
- DBus8ByteStruct u64;
+ DBus8ByteStruct u64; /**< as 8-byte-struct */
#endif
- double dbl;
- unsigned char byt;
- unsigned char boo;
- char *str;
+ double dbl; /**< as double */
+ unsigned char byt; /**< as byte */
+ unsigned char boo; /**< as boolean */
+ char *str; /**< as char* */
} DBusBasicValue;
#ifdef DBUS_DISABLE_ASSERT
diff --git a/dbus/dbus-marshal-header.c b/dbus/dbus-marshal-header.c
index 58ba86fe..a3711155 100644
--- a/dbus/dbus-marshal-header.c
+++ b/dbus/dbus-marshal-header.c
@@ -33,11 +33,16 @@
/* Not thread locked, but strictly const/read-only so should be OK
*/
+/** Static #DBusString containing the signature of a message header */
_DBUS_STRING_DEFINE_STATIC(_dbus_header_signature_str, DBUS_HEADER_SIGNATURE);
+/** Static #DBusString containing the local interface */
_DBUS_STRING_DEFINE_STATIC(_dbus_local_interface_str, DBUS_INTERFACE_ORG_FREEDESKTOP_LOCAL);
+/** Static #DBusString containing the local path */
_DBUS_STRING_DEFINE_STATIC(_dbus_local_path_str, DBUS_PATH_ORG_FREEDESKTOP_LOCAL);
+/** Offset from start of _dbus_header_signature_str to the signature of the fields array */
#define FIELDS_ARRAY_SIGNATURE_OFFSET 6
+/** Offset from start of _dbus_header_signature_str to the signature of an element of the fields array */
#define FIELDS_ARRAY_ELEMENT_SIGNATURE_OFFSET 7
@@ -77,8 +82,10 @@ _dbus_header_field_types[DBUS_HEADER_FIELD_LAST+1] = {
{ DBUS_HEADER_FIELD_SIGNATURE, DBUS_TYPE_SIGNATURE }
};
+/** Macro to look up the correct type for a field */
#define EXPECTED_TYPE_OF_FIELD(field) (_dbus_header_field_types[field].type)
+/** The most padding we could ever need for a header */
#define MAX_POSSIBLE_HEADER_PADDING 7
static dbus_bool_t
reserve_header_padding (DBusHeader *header)
@@ -108,6 +115,7 @@ correct_header_padding (DBusHeader *header)
header->padding = _dbus_string_get_length (&header->data) - unpadded_len;
}
+/** Compute the end of the header, ignoring padding */
#define HEADER_END_BEFORE_PADDING(header) \
(_dbus_string_get_length (&(header)->data) - (header)->padding)
@@ -635,6 +643,7 @@ _dbus_header_create (DBusHeader *header,
* contain the entire message (assuming the claimed lengths are
* accurate). Also checks that the lengths are in sanity parameters.
*
+ * @param max_message_length maximum length of a valid message
* @param validity return location for why the data is invalid if it is
* @param byte_order return location for byte order
* @param fields_array_len return location for claimed fields array length
diff --git a/dbus/dbus-marshal-header.h b/dbus/dbus-marshal-header.h
index 32bf51eb..61e9246a 100644
--- a/dbus/dbus-marshal-header.h
+++ b/dbus/dbus-marshal-header.h
@@ -46,6 +46,9 @@ struct DBusHeaderField
int value_pos; /**< Position of field value, or -1/-2 */
};
+/**
+ * Message header data and some cached details of it.
+ */
struct DBusHeader
{
DBusString data; /**< Header network data, stored
diff --git a/dbus/dbus-marshal-recursive.c b/dbus/dbus-marshal-recursive.c
index a8bad46a..2d4338ad 100644
--- a/dbus/dbus-marshal-recursive.c
+++ b/dbus/dbus-marshal-recursive.c
@@ -29,7 +29,11 @@
* @addtogroup DBusMarshal
* @{
*/
+
+/** turn this on to get deluged in TypeReader verbose spam */
#define RECURSIVE_MARSHAL_READ_TRACE 0
+
+/** turn this on to get deluged in TypeWriter verbose spam */
#define RECURSIVE_MARSHAL_WRITE_TRACE 0
static void
@@ -101,18 +105,21 @@ apply_and_free_fixups (DBusList **fixups,
*fixups = NULL;
}
+/**
+ * Virtual table for a type reader.
+ */
struct DBusTypeReaderClass
{
- const char *name;
- int id; /* index in all_reader_classes */
- dbus_bool_t types_only; /* only iterates over types, not values */
+ const char *name; /**< name for debugging */
+ int id; /**< index in all_reader_classes */
+ dbus_bool_t types_only; /**< only iterates over types, not values */
void (* recurse) (DBusTypeReader *sub,
- DBusTypeReader *parent);
- dbus_bool_t (* check_finished) (const DBusTypeReader *reader);
+ DBusTypeReader *parent); /**< recurse with this reader as sub */
+ dbus_bool_t (* check_finished) (const DBusTypeReader *reader); /**< check whether reader is at the end */
void (* next) (DBusTypeReader *reader,
- int current_type);
+ int current_type); /**< go to the next value */
void (* init_from_mark) (DBusTypeReader *reader,
- const DBusTypeMark *mark);
+ const DBusTypeMark *mark); /**< uncompress from a mark */
};
static int
@@ -201,7 +208,8 @@ array_types_only_reader_recurse (DBusTypeReader *sub,
sub->array_len_offset = 7;
}
-/* array_len_offset is the offset back from start_pos to end of the len */
+/** compute position of array length given array_len_offset, which is
+ the offset back from start_pos to end of the len */
#define ARRAY_READER_LEN_POS(reader) \
((reader)->u.array.start_pos - ((int)(reader)->array_len_offset) - 4)
@@ -216,7 +224,7 @@ array_reader_get_array_len (const DBusTypeReader *reader)
_dbus_assert (_DBUS_ALIGN_VALUE (len_pos, 4) == (unsigned) len_pos);
array_len = _dbus_unpack_uint32 (reader->byte_order,
_dbus_string_get_const_data_len (reader->value_str, len_pos, 4));
-
+
#if RECURSIVE_MARSHAL_READ_TRACE
_dbus_verbose (" reader %p len_pos %d array len %u len_offset %d\n",
reader, len_pos, array_len, reader->array_len_offset);
@@ -315,27 +323,27 @@ skip_one_complete_type (const DBusString *type_str,
{
const unsigned char *p;
const unsigned char *start;
-
+
start = _dbus_string_get_const_data (type_str);
p = start + *type_pos;
while (*p == DBUS_TYPE_ARRAY)
++p;
-
+
if (*p == DBUS_STRUCT_BEGIN_CHAR)
{
int depth;
-
+
depth = 1;
-
+
while (TRUE)
{
_dbus_assert (*p != DBUS_TYPE_INVALID);
-
+
++p;
_dbus_assert (*p != DBUS_TYPE_INVALID);
-
+
if (*p == DBUS_STRUCT_BEGIN_CHAR)
depth += 1;
else if (*p == DBUS_STRUCT_END_CHAR)
@@ -632,6 +640,16 @@ all_reader_classes[] = {
&variant_reader_class
};
+/**
+ * Initializes a type reader.
+ *
+ * @param reader the reader
+ * @param byte_order the byte order of the block to read
+ * @param type_str the signature of the block to read
+ * @param type_pos location of signature
+ * @param value_str the string containing values block
+ * @param value_pos start of values block
+ */
void
_dbus_type_reader_init (DBusTypeReader *reader,
int byte_order,
@@ -652,6 +670,17 @@ _dbus_type_reader_init (DBusTypeReader *reader,
#endif
}
+/**
+ * Initializes a type reader that's been compressed into a
+ * DBusTypeMark. The args have to be the same as those passed in to
+ * create the original #DBusTypeReader.
+ *
+ * @param reader the reader
+ * @param byte_order the byte order of the value block
+ * @param type_str string containing the type signature
+ * @param value_str string containing the values block
+ * @param mark the mark to decompress from
+ */
void
_dbus_type_reader_init_from_mark (DBusTypeReader *reader,
int byte_order,
@@ -676,6 +705,14 @@ _dbus_type_reader_init_from_mark (DBusTypeReader *reader,
#endif
}
+/**
+ * Like _dbus_type_reader_init() but the iteration is over the
+ * signature, not over values.
+ *
+ * @param reader the reader
+ * @param type_str the signature string
+ * @param type_pos location in the signature string
+ */
void
_dbus_type_reader_init_types_only (DBusTypeReader *reader,
const DBusString *type_str,
@@ -693,6 +730,14 @@ _dbus_type_reader_init_types_only (DBusTypeReader *reader,
#endif
}
+/**
+ * Like _dbus_type_reader_init_from_mark() but only iterates over
+ * the signature, not the values.
+ *
+ * @param reader the reader
+ * @param type_str the signature string
+ * @param mark the mark to decompress from
+ */
void
_dbus_type_reader_init_types_only_from_mark (DBusTypeReader *reader,
const DBusString *type_str,
@@ -716,6 +761,13 @@ _dbus_type_reader_init_types_only_from_mark (DBusTypeReader *reader,
#endif
}
+/**
+ * Compresses a type reader into a #DBusTypeMark, useful for example
+ * if you want to cache a bunch of positions in a block of values.
+ *
+ * @param reader the reader
+ * @param mark the mark to init
+ */
void
_dbus_type_reader_save_mark (const DBusTypeReader *reader,
DBusTypeMark *mark)
@@ -732,6 +784,14 @@ _dbus_type_reader_save_mark (const DBusTypeReader *reader,
mark->array_start_pos = reader->u.array.start_pos;
}
+/**
+ * Gets the type of the value the reader is currently pointing to;
+ * or for a types-only reader gets the type it's currently pointing to.
+ * If the reader is at the end of a block or end of a container such
+ * as an array, returns #DBUS_TYPE_INVALID.
+ *
+ * @param reader the reader
+ */
int
_dbus_type_reader_get_current_type (const DBusTypeReader *reader)
{
@@ -757,8 +817,16 @@ _dbus_type_reader_get_current_type (const DBusTypeReader *reader)
return t;
}
+/**
+ * Gets the type of an element of the array the reader is currently
+ * pointing to. It's an error to call this if
+ * _dbus_type_reader_get_current_type() doesn't return #DBUS_TYPE_ARRAY
+ * for this reader.
+ *
+ * @param reader the reader
+ */
int
-_dbus_type_reader_get_array_type (const DBusTypeReader *reader)
+_dbus_type_reader_get_element_type (const DBusTypeReader *reader)
{
int element_type;
@@ -770,36 +838,25 @@ _dbus_type_reader_get_array_type (const DBusTypeReader *reader)
return element_type;
}
+/**
+ * Gets the current position in the value block
+ * @param reader the reader
+ */
int
_dbus_type_reader_get_value_pos (const DBusTypeReader *reader)
{
return reader->value_pos;
}
-dbus_bool_t
+/**
+ * Checks whether an array has any elements.
+ *
+ * @param reader the reader
+ */
+static dbus_bool_t
_dbus_type_reader_array_is_empty (const DBusTypeReader *reader)
{
- dbus_uint32_t array_len;
-
- _dbus_assert (_dbus_type_reader_get_current_type (reader) == DBUS_TYPE_ARRAY);
- _dbus_assert (!reader->klass->types_only);
-
- /* reader is supposed to be at an array child */
-#if RECURSIVE_MARSHAL_READ_TRACE
- _dbus_verbose ("checking array len at %d\n", reader->value_pos);
-#endif
-
- _dbus_marshal_read_basic (reader->value_str,
- reader->value_pos,
- DBUS_TYPE_UINT32,
- &array_len,
- reader->byte_order,
- NULL);
-#if RECURSIVE_MARSHAL_READ_TRACE
- _dbus_verbose (" ... array len = %d\n", array_len);
-#endif
-
- return array_len == 0;
+ return array_reader_get_array_len (reader) == 0;
}
/**
@@ -822,6 +879,12 @@ _dbus_type_reader_read_raw (const DBusTypeReader *reader,
0);
}
+/**
+ * Reads a basic-typed value, as with _dbus_marshal_read_basic().
+ *
+ * @param reader the reader
+ * @param value the address of the value
+ */
void
_dbus_type_reader_read_basic (const DBusTypeReader *reader,
void *value)
@@ -1852,7 +1915,7 @@ writer_recurse_array (DBusTypeWriter *writer,
_dbus_string_get_const_data_len (sub->value_str,
sub->u.array.len_pos,
4));
-
+
sub->value_pos += len;
}
}
@@ -2006,6 +2069,16 @@ _dbus_type_writer_recurse_contained_len (DBusTypeWriter *writer,
}
}
+/**
+ * Opens a new container and writes out the initial information for that container.
+ *
+ * @param writer the writer
+ * @param container_type the type of the container to open
+ * @param contained_type the array element type or variant content type
+ * @param contained_type_start position to look for the type
+ * @param sub the new sub-writer to write container contents
+ * @returns #FALSE if no memory
+ */
dbus_bool_t
_dbus_type_writer_recurse (DBusTypeWriter *writer,
int container_type,
@@ -2068,6 +2141,14 @@ writer_get_array_len (DBusTypeWriter *writer)
return writer->value_pos - writer->u.array.start_pos;
}
+/**
+ * Closes a container created by _dbus_type_writer_recurse()
+ * and writes any additional information to the values block.
+ *
+ * @param writer the writer
+ * @param sub the sub-writer created by _dbus_type_writer_recurse()
+ * @returns #FALSE if no memory
+ */
dbus_bool_t
_dbus_type_writer_unrecurse (DBusTypeWriter *writer,
DBusTypeWriter *sub)
@@ -2182,6 +2263,14 @@ _dbus_type_writer_unrecurse (DBusTypeWriter *writer,
return TRUE;
}
+/**
+ * Writes out a basic type.
+ *
+ * @param writer the writer
+ * @param type the type to write
+ * @param value the address of the value to write
+ * @returns #FALSE if no memory
+ */
dbus_bool_t
_dbus_type_writer_write_basic (DBusTypeWriter *writer,
int type,
@@ -2452,7 +2541,7 @@ writer_write_reader_helper (DBusTypeWriter *writer,
_dbus_assert (_DBUS_ALIGN_VALUE (fixup.len_pos_in_reader, 4) ==
(unsigned) fixup.len_pos_in_reader);
-
+
old_len = _dbus_unpack_uint32 (reader->byte_order,
_dbus_string_get_const_data_len (reader->value_str,
fixup.len_pos_in_reader, 4));
@@ -3515,7 +3604,6 @@ typedef struct
int n_nodes;
} NodeIterationData;
-
static dbus_bool_t
run_test_copy (NodeIterationData *nid)
{
@@ -5345,7 +5433,7 @@ array_read_or_set_value (TestTypeNode *node,
_dbus_type_reader_recurse (reader, &sub);
if (realign_root == NULL && arrays_write_fixed_in_blocks &&
- _dbus_type_is_fixed (_dbus_type_reader_get_array_type (reader)) &&
+ _dbus_type_is_fixed (_dbus_type_reader_get_element_type (reader)) &&
child->klass->read_multi)
{
if (!node_read_multi (child, &sub, seed, n_copies))
@@ -5365,7 +5453,7 @@ array_read_or_set_value (TestTypeNode *node,
DBusList *next = _dbus_list_get_next_link (&container->children, link);
_dbus_assert (child->klass->typecode ==
- _dbus_type_reader_get_array_type (reader));
+ _dbus_type_reader_get_element_type (reader));
if (realign_root == NULL)
{
diff --git a/dbus/dbus-marshal-recursive.h b/dbus/dbus-marshal-recursive.h
index 203e2f8c..fe9e1426 100644
--- a/dbus/dbus-marshal-recursive.h
+++ b/dbus/dbus-marshal-recursive.h
@@ -57,75 +57,88 @@ typedef struct DBusTypeWriter DBusTypeWriter;
typedef struct DBusTypeReaderClass DBusTypeReaderClass;
typedef struct DBusArrayLenFixup DBusArrayLenFixup;
-/* The mark is a way to compress a TypeReader; it isn't all that
+/** The mark is a way to compress a #DBusTypeReader; it isn't all that
* successful though. The idea was to use this for caching header
* fields in dbus-message.c. However now I'm thinking why not cache
* the actual values (e.g. char*) and if the field needs to be set or
* deleted, just linear search for it. Those operations are uncommon,
* and getting the values should be fast and not involve all this type
* reader nonsense.
+ *
+ * @todo DBusTypeMark isn't used right now and probably won't be, we should delete it
*/
struct DBusTypeMark
{
- dbus_uint32_t type_pos_in_value_str : 1;
- dbus_uint32_t container_type : 3;
- dbus_uint32_t array_len_offset : 3; /* bytes back from start_pos that len ends */
- dbus_uint32_t type_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
- dbus_uint32_t value_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
- dbus_uint32_t array_start_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
+ dbus_uint32_t type_pos_in_value_str : 1; /**< true if the type_pos is in value_str and not type_str */
+ dbus_uint32_t container_type : 3; /**< the "id" of the container type */
+ dbus_uint32_t array_len_offset : 3; /**< bytes back from start_pos that len ends */
+ dbus_uint32_t type_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< position in type_str */
+ dbus_uint32_t value_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< position in value_str */
+ dbus_uint32_t array_start_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< start of the array the reader was iterating over */
};
+/**
+ * The type reader is an iterator for reading values from a block of
+ * values.
+ */
struct DBusTypeReader
{
- dbus_uint32_t byte_order : 8;
+ dbus_uint32_t byte_order : 8; /**< byte order of the block */
- dbus_uint32_t finished : 1; /* marks we're at end iterator for cases
+ dbus_uint32_t finished : 1; /**< marks we're at end iterator for cases
* where we don't have another way to tell
*/
- dbus_uint32_t array_len_offset : 3; /* bytes back from start_pos that len ends */
- const DBusString *type_str;
- int type_pos;
- const DBusString *value_str;
- int value_pos;
+ dbus_uint32_t array_len_offset : 3; /**< bytes back from start_pos that len ends */
+ const DBusString *type_str; /**< string containing signature of block */
+ int type_pos; /**< current position in signature */
+ const DBusString *value_str; /**< string containing values of block */
+ int value_pos; /**< current position in values */
- const DBusTypeReaderClass *klass;
+ const DBusTypeReaderClass *klass; /**< the vtable for the reader */
union
{
struct {
- int start_pos;
+ int start_pos; /**< for array readers, the start of the array values */
} array;
- } u;
+ } u; /**< class-specific data */
};
+/**
+ * The type writer is an iterator for writing to a block of values.
+ */
struct DBusTypeWriter
{
- dbus_uint32_t byte_order : 8;
+ dbus_uint32_t byte_order : 8; /**< byte order to write values with */
- dbus_uint32_t container_type : 8;
+ dbus_uint32_t container_type : 8; /**< what are we inside? (e.g. struct, variant, array) */
- dbus_uint32_t type_pos_is_expectation : 1; /* type_pos is an insertion point or an expected next type */
+ dbus_uint32_t type_pos_is_expectation : 1; /**< type_pos can be either an insertion point for or an expected next type */
- dbus_uint32_t enabled : 1; /* whether to write values */
+ dbus_uint32_t enabled : 1; /**< whether to write values */
- DBusString *type_str;
- int type_pos;
- DBusString *value_str;
- int value_pos;
+ DBusString *type_str; /**< where to write typecodes (or read type expectations) */
+ int type_pos; /**< current pos in type_str */
+ DBusString *value_str; /**< where to write values */
+ int value_pos; /**< next position to write */
union
{
struct {
- int start_pos; /* first element */
- int len_pos;
- int element_type_pos; /* position of array element type in type_str */
+ int start_pos; /**< position of first element in the array */
+ int len_pos; /**< position of length of the array */
+ int element_type_pos; /**< position of array element type in type_str */
} array;
- } u;
+ } u; /**< class-specific data */
};
+/**
+ * When modifying an existing block of values, array lengths may need
+ * to be adjusted; those adjustments are described by this struct.
+ */
struct DBusArrayLenFixup
{
- int len_pos_in_reader;
- int new_len;
+ int len_pos_in_reader; /**< where the length was in the original block */
+ int new_len; /**< the new value of the length in the written-out block */
};
void _dbus_type_reader_init (DBusTypeReader *reader,
@@ -148,9 +161,8 @@ void _dbus_type_reader_init_types_only_from_mark (DBusTypeReader *
void _dbus_type_reader_save_mark (const DBusTypeReader *reader,
DBusTypeMark *mark);
int _dbus_type_reader_get_current_type (const DBusTypeReader *reader);
-int _dbus_type_reader_get_array_type (const DBusTypeReader *reader);
+int _dbus_type_reader_get_element_type (const DBusTypeReader *reader);
int _dbus_type_reader_get_value_pos (const DBusTypeReader *reader);
-dbus_bool_t _dbus_type_reader_array_is_empty (const DBusTypeReader *reader);
void _dbus_type_reader_read_basic (const DBusTypeReader *reader,
void *value);
void _dbus_type_reader_read_fixed_multi (const DBusTypeReader *reader,
diff --git a/dbus/dbus-marshal-validate.c b/dbus/dbus-marshal-validate.c
index cf409758..d3507739 100644
--- a/dbus/dbus-marshal-validate.c
+++ b/dbus/dbus-marshal-validate.c
@@ -203,7 +203,7 @@ validate_body_helper (DBusTypeReader *reader,
if (current_type == DBUS_TYPE_ARRAY)
{
- int array_elem_type = _dbus_type_reader_get_array_type (reader);
+ int array_elem_type = _dbus_type_reader_get_element_type (reader);
alignment = _dbus_type_get_alignment (array_elem_type);
p = _DBUS_ALIGN_ADDRESS (p, alignment);
}
@@ -419,6 +419,7 @@ validate_body_helper (DBusTypeReader *reader,
* @param expected_signature_start where in expected_signature is the signature
* @param byte_order the byte order
* @param bytes_remaining place to store leftover bytes
+ * @param value_str the string containing the body
* @param value_pos where the values start
* @param len length of values after value_pos
* @returns #DBUS_VALID if valid, reason why invalid otherwise
@@ -814,14 +815,17 @@ _dbus_validate_signature (const DBusString *str,
return _dbus_validate_signature_with_reason (str, start, len) == DBUS_VALID;
}
-/* If the compiler hates these semicolons, add "extern int
- * allow_parens" at the end in the the macro perhaps
- */
+/** define _dbus_check_is_valid_path() */
DEFINE_DBUS_NAME_CHECK(path);
+/** define _dbus_check_is_valid_interface() */
DEFINE_DBUS_NAME_CHECK(interface);
+/** define _dbus_check_is_valid_member() */
DEFINE_DBUS_NAME_CHECK(member);
+/** define _dbus_check_is_valid_error_name() */
DEFINE_DBUS_NAME_CHECK(error_name);
+/** define _dbus_check_is_valid_service() */
DEFINE_DBUS_NAME_CHECK(service);
+/** define _dbus_check_is_valid_signature() */
DEFINE_DBUS_NAME_CHECK(signature);
/** @} */
diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h
index 8f4e7ef6..a4950dbe 100644
--- a/dbus/dbus-marshal-validate.h
+++ b/dbus/dbus-marshal-validate.h
@@ -132,12 +132,14 @@ dbus_bool_t _dbus_validate_signature (const DBusString *str,
#else /* !DBUS_DISABLE_CHECKS */
-/* A name check is used in _dbus_return_if_fail(), it's not suitable
+/** A name check is used in _dbus_return_if_fail(), it's not suitable
* for validating untrusted data. use _dbus_validate_##what for that.
*/
#define DECLARE_DBUS_NAME_CHECK(what) \
dbus_bool_t _dbus_check_is_valid_##what (const char *name)
+/** Define a name check to be used in _dbus_return_if_fail() statements.
+ */
#define DEFINE_DBUS_NAME_CHECK(what) \
dbus_bool_t \
_dbus_check_is_valid_##what (const char *name) \
diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 8cb3dc64..70e1d022 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -55,8 +55,10 @@ static dbus_bool_t dbus_message_iter_get_args_valist (DBusMessageIter *iter,
/* Not thread locked, but strictly const/read-only so should be OK
*/
+/** An static string representing an empty signature */
_DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
+/** How many bits are in the changed_stamp used to validate iterators */
#define CHANGED_STAMP_BITS 21
/**
@@ -114,9 +116,9 @@ struct DBusMessageRealIter
dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
union
{
- DBusTypeWriter writer;
- DBusTypeReader reader;
- } u;
+ DBusTypeWriter writer; /**< writer */
+ DBusTypeReader reader; /**< reader */
+ } u; /**< the type writer or reader that does all the work */
};
/**
@@ -515,9 +517,10 @@ dbus_message_finalize (DBusMessage *message)
* mempool).
*/
-/* Avoid caching huge messages */
+/** Avoid caching huge messages */
#define MAX_MESSAGE_SIZE_TO_CACHE _DBUS_ONE_MEGABYTE
-/* Avoid caching too many messages */
+
+/** Avoid caching too many messages */
#define MAX_MESSAGE_CACHE_SIZE 5
_DBUS_DEFINE_GLOBAL_LOCK (message_cache);
@@ -949,7 +952,7 @@ dbus_message_new_error (DBusMessage *reply_to,
if (error_message != NULL)
{
- dbus_message_append_iter_init (message, &iter);
+ dbus_message_iter_init_append (message, &iter);
if (!dbus_message_iter_append_basic (&iter,
DBUS_TYPE_STRING,
&error_message))
@@ -1232,7 +1235,7 @@ dbus_message_append_args_valist (DBusMessage *message,
type = first_arg_type;
- dbus_message_append_iter_init (message, &iter);
+ dbus_message_iter_init_append (message, &iter);
while (type != DBUS_TYPE_INVALID)
{
@@ -1574,7 +1577,7 @@ dbus_message_iter_get_arg_type (DBusMessageIter *iter)
* @returns the array element type
*/
int
-dbus_message_iter_get_array_type (DBusMessageIter *iter)
+dbus_message_iter_get_element_type (DBusMessageIter *iter)
{
DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
@@ -1582,7 +1585,7 @@ dbus_message_iter_get_array_type (DBusMessageIter *iter)
_dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
_dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
- return _dbus_type_reader_get_array_type (&real->u.reader);
+ return _dbus_type_reader_get_element_type (&real->u.reader);
}
/**
@@ -1685,7 +1688,7 @@ dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
_dbus_return_if_fail (_dbus_message_iter_check (real));
_dbus_return_if_fail (value != NULL);
- _dbus_return_if_fail (_dbus_type_is_fixed (_dbus_type_reader_get_array_type (&real->u.reader)));
+ _dbus_return_if_fail (_dbus_type_is_fixed (_dbus_type_reader_get_element_type (&real->u.reader)));
_dbus_type_reader_read_fixed_multi (&real->u.reader,
value, n_elements);
@@ -1760,7 +1763,7 @@ dbus_message_iter_get_args_valist (DBusMessageIter *iter,
DBusTypeReader array;
spec_element_type = va_arg (var_args, int);
- element_type = _dbus_type_reader_get_array_type (&real->u.reader);
+ element_type = _dbus_type_reader_get_element_type (&real->u.reader);
if (spec_element_type != element_type)
{
@@ -1894,7 +1897,7 @@ dbus_message_iter_get_args_valist (DBusMessageIter *iter,
* @param iter pointer to an iterator to initialize
*/
void
-dbus_message_append_iter_init (DBusMessage *message,
+dbus_message_iter_init_append (DBusMessage *message,
DBusMessageIter *iter)
{
DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
@@ -2115,7 +2118,7 @@ dbus_message_iter_append_basic (DBusMessageIter *iter,
* you have to start over building the whole message.
*
* @param iter the append iterator
- * @param type the type of the array elements
+ * @param element_type the type of the array elements
* @param value the address of the array
* @param n_elements the number of elements to append
* @returns #FALSE if not enough memory
@@ -4596,7 +4599,7 @@ _dbus_message_test (const char *test_data_dir)
_dbus_message_set_serial (message, 1);
dbus_message_set_reply_serial (message, 0x12345678);
- dbus_message_append_iter_init (message, &iter);
+ dbus_message_iter_init_append (message, &iter);
dbus_message_iter_append_string (&iter, "Test string");
dbus_message_iter_append_int32 (&iter, -0x12345678);
dbus_message_iter_append_uint32 (&iter, 0xedd1e);
diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h
index fd6b96d4..7dcedcc7 100644
--- a/dbus/dbus-message.h
+++ b/dbus/dbus-message.h
@@ -1,7 +1,7 @@
/* -*- mode: C; c-file-style: "gnu" -*- */
/* dbus-message.h DBusMessage object
*
- * Copyright (C) 2002, 2003 Red Hat Inc.
+ * Copyright (C) 2002, 2003, 2005 Red Hat Inc.
*
* Licensed under the Academic Free License version 2.1
*
@@ -146,21 +146,22 @@ dbus_bool_t dbus_message_get_args_valist (DBusMessage *message,
va_list var_args);
-dbus_bool_t dbus_message_iter_init (DBusMessage *message,
- DBusMessageIter *iter);
-dbus_bool_t dbus_message_iter_has_next (DBusMessageIter *iter);
-dbus_bool_t dbus_message_iter_next (DBusMessageIter *iter);
-int dbus_message_iter_get_arg_type (DBusMessageIter *iter);
-int dbus_message_iter_get_array_type (DBusMessageIter *iter);
-void dbus_message_iter_recurse (DBusMessageIter *iter,
- DBusMessageIter *sub);
-void dbus_message_iter_get_basic (DBusMessageIter *iter,
- void *value);
-void dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
- void *value,
- int *n_elements);
-
-void dbus_message_append_iter_init (DBusMessage *message,
+dbus_bool_t dbus_message_iter_init (DBusMessage *message,
+ DBusMessageIter *iter);
+dbus_bool_t dbus_message_iter_has_next (DBusMessageIter *iter);
+dbus_bool_t dbus_message_iter_next (DBusMessageIter *iter);
+int dbus_message_iter_get_arg_type (DBusMessageIter *iter);
+int dbus_message_iter_get_element_type (DBusMessageIter *iter);
+void dbus_message_iter_recurse (DBusMessageIter *iter,
+ DBusMessageIter *sub);
+void dbus_message_iter_get_basic (DBusMessageIter *iter,
+ void *value);
+void dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
+ void *value,
+ int *n_elements);
+
+
+void dbus_message_iter_init_append (DBusMessage *message,
DBusMessageIter *iter);
dbus_bool_t dbus_message_iter_append_basic (DBusMessageIter *iter,
int type,
diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c
index dccf5176..52099d65 100644
--- a/dbus/dbus-string.c
+++ b/dbus/dbus-string.c
@@ -809,7 +809,7 @@ _dbus_string_copy_data_len (const DBusString *str,
*
* @param str a string
* @param buffer a C buffer to copy data to
- * @param len maximum length of C buffer
+ * @param avail_len maximum length of C buffer
*/
void
_dbus_string_copy_to_buffer (const DBusString *str,
@@ -1046,13 +1046,16 @@ _dbus_string_append (DBusString *str,
return append (real, buffer, buffer_len);
}
+/** assign 4 bytes from one string to another */
#define ASSIGN_4_OCTETS(p, octets) \
*((dbus_uint32_t*)(p)) = *((dbus_uint32_t*)(octets));
#ifdef DBUS_HAVE_INT64
+/** assign 8 bytes from one string to another */
#define ASSIGN_8_OCTETS(p, octets) \
*((dbus_uint64_t*)(p)) = *((dbus_uint64_t*)(octets));
#else
+/** assign 8 bytes from one string to another */
#define ASSIGN_8_OCTETS(p, octets) \
do { \
unsigned char *b; \
@@ -1120,6 +1123,7 @@ _dbus_string_append_8_aligned (DBusString *str,
* with any alignment padding initialized to 0.
*
* @param str the DBusString
+ * @param insert_at where to insert
* @param octets 4 bytes to insert
* @returns #FALSE if not enough memory.
*/
@@ -1143,6 +1147,7 @@ _dbus_string_insert_4_aligned (DBusString *str,
* with any alignment padding initialized to 0.
*
* @param str the DBusString
+ * @param insert_at where to insert
* @param octets 8 bytes to insert
* @returns #FALSE if not enough memory.
*/