From 31988af4089f3793940417535f8eabaae1ac26c8 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 16 Jan 2005 15:51:55 +0000 Subject: 2005-01-16 Havoc Pennington * 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 --- dbus/dbus-marshal-basic.c | 1 + dbus/dbus-marshal-basic.h | 33 +++++--- dbus/dbus-marshal-header.c | 9 +++ dbus/dbus-marshal-header.h | 3 + dbus/dbus-marshal-recursive.c | 174 +++++++++++++++++++++++++++++++----------- dbus/dbus-marshal-recursive.h | 78 +++++++++++-------- dbus/dbus-marshal-validate.c | 12 ++- dbus/dbus-marshal-validate.h | 4 +- dbus/dbus-message.c | 31 ++++---- dbus/dbus-message.h | 33 ++++---- dbus/dbus-string.c | 7 +- 11 files changed, 261 insertions(+), 124 deletions(-) (limited to 'dbus') 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. */ -- cgit