Commit bf172ce4 authored by Havoc Pennington's avatar Havoc Pennington
Browse files

2006-10-21 Havoc Pennington <hp@redhat.com>

	* Documentation! Whee! Doxygen now 100% silent. If you make it
	angry again, you will be punished.
parent 58a0d275
2006-10-21 Havoc Pennington <hp@redhat.com>
* Documentation! Whee! Doxygen now 100% silent. If you make it
angry again, you will be punished.
2006-10-21 Havoc Pennington <hp@redhat.com> 2006-10-21 Havoc Pennington <hp@redhat.com>
* More documentation - all public API now documented according to * More documentation - all public API now documented according to
......
...@@ -2992,23 +2992,19 @@ reply_handler_timeout (void *data) ...@@ -2992,23 +2992,19 @@ reply_handler_timeout (void *data)
} }
/** /**
* Queues a message to send, as with dbus_connection_send_message(), * Queues a message to send, as with dbus_connection_send(),
* but also returns a #DBusPendingCall used to receive a reply to the * but also returns a #DBusPendingCall used to receive a reply to the
* message. If no reply is received in the given timeout_milliseconds, * message. If no reply is received in the given timeout_milliseconds,
* this function expires the pending reply and generates a synthetic * this function expires the pending reply and generates a synthetic
* error reply (generated in-process, not by the remote application) * error reply (generated in-process, not by the remote application)
* indicating that a timeout occurred. * indicating that a timeout occurred.
* *
* A #DBusPendingCall will see a reply message after any filters, but * A #DBusPendingCall will see a reply message before any filters or
* before any object instances or other handlers. A #DBusPendingCall * registered object path handlers. See dbus_connection_dispatch() for
* will always see exactly one reply message, unless it's cancelled * details on when handlers are run.
* with dbus_pending_call_cancel(). *
* * A #DBusPendingCall will always see exactly one reply message,
* If a filter filters out the reply before the handler sees it, the * unless it's cancelled with dbus_pending_call_cancel().
* reply is immediately timed out and a timeout error reply is
* generated. If a filter removes the timeout error reply then the
* #DBusPendingCall will get confused. Filtering the timeout error
* is thus considered a bug and will print a warning.
* *
* If #NULL is passed for the pending_return, the #DBusPendingCall * If #NULL is passed for the pending_return, the #DBusPendingCall
* will still be generated internally, and used to track * will still be generated internally, and used to track
...@@ -3019,7 +3015,11 @@ reply_handler_timeout (void *data) ...@@ -3019,7 +3015,11 @@ reply_handler_timeout (void *data)
* is typically the best value for the timeout for this reason, unless * is typically the best value for the timeout for this reason, unless
* you want a very short or very long timeout. There is no way to * you want a very short or very long timeout. There is no way to
* avoid a timeout entirely, other than passing INT_MAX for the * avoid a timeout entirely, other than passing INT_MAX for the
* timeout to postpone it indefinitely. * timeout to mean "very long timeout." libdbus clamps an INT_MAX
* timeout down to a few hours timeout though.
*
* @warning if the connection is disconnected, the #DBusPendingCall
* will be set to #NULL, so be careful with this.
* *
* @param connection the connection * @param connection the connection
* @param message the message to send * @param message the message to send
...@@ -3123,16 +3123,24 @@ dbus_connection_send_with_reply (DBusConnection *connection, ...@@ -3123,16 +3123,24 @@ dbus_connection_send_with_reply (DBusConnection *connection,
* Sends a message and blocks a certain time period while waiting for * Sends a message and blocks a certain time period while waiting for
* a reply. This function does not reenter the main loop, * a reply. This function does not reenter the main loop,
* i.e. messages other than the reply are queued up but not * i.e. messages other than the reply are queued up but not
* processed. This function is used to do non-reentrant "method * processed. This function is used to invoke method calls on a
* calls." * remote object.
* *
* If a normal reply is received, it is returned, and removed from the * If a normal reply is received, it is returned, and removed from the
* incoming message queue. If it is not received, #NULL is returned * incoming message queue. If it is not received, #NULL is returned
* and the error is set to #DBUS_ERROR_NO_REPLY. If an error reply is * and the error is set to #DBUS_ERROR_NO_REPLY. If an error reply is
* received, it is converted to a #DBusError and returned as an error, * received, it is converted to a #DBusError and returned as an error,
* then the reply message is deleted. If something else goes wrong, * then the reply message is deleted and #NULL is returned. If
* result is set to whatever is appropriate, such as * something else goes wrong, result is set to whatever is
* #DBUS_ERROR_NO_MEMORY or #DBUS_ERROR_DISCONNECTED. * appropriate, such as #DBUS_ERROR_NO_MEMORY or
* #DBUS_ERROR_DISCONNECTED.
*
* @warning While this function blocks the calling thread will not be
* processing the incoming message queue. This means you can end up
* deadlocked if the application you're talking to needs you to reply
* to a method. To solve this, either avoid the situation, block in a
* separate thread from the main connection-dispatching thread, or use
* dbus_pending_call_set_notify() to avoid blocking.
* *
* @param connection the connection * @param connection the connection
* @param message the message to send * @param message the message to send
...@@ -4076,25 +4084,33 @@ _dbus_connection_run_builtin_filters_unlocked_no_update (DBusConnection *connect ...@@ -4076,25 +4084,33 @@ _dbus_connection_run_builtin_filters_unlocked_no_update (DBusConnection *connect
/** /**
* Processes any incoming data. * Processes any incoming data.
* *
* If there are messages in the incoming queue,
* dbus_connection_dispatch() removes one message from the queue and
* runs any handlers for it (handlers are added with
* dbus_connection_add_filter() or
* dbus_connection_register_object_path() for example).
*
* If there's incoming raw data that has not yet been parsed, it is * If there's incoming raw data that has not yet been parsed, it is
* parsed, which may or may not result in adding messages to the * parsed, which may or may not result in adding messages to the
* incoming queue. * incoming queue.
*
* The incoming data buffer is filled when the connection reads from
* its underlying transport (such as a socket). Reading usually
* happens in dbus_watch_handle() or dbus_connection_read_write().
* *
* The incoming message queue is filled when the connection * If there are complete messages in the incoming queue,
* reads from its underlying transport (such as a socket). * dbus_connection_dispatch() removes one message from the queue and
* Reading usually happens in dbus_watch_handle() or * processes it. Processing has three steps.
* dbus_connection_read_write(). *
* * First, any method replies are passed to #DBusPendingCall or
* If any data has been read from the underlying transport, but not * dbus_connection_send_with_reply_and_block() in order to
* yet dispatched, the dispatch status will be * complete the pending method call.
* #DBUS_DISPATCH_DATA_REMAINS. See dbus_connection_get_dispatch_status() *
* for more on dispatch statuses. * Second, any filters registered with dbus_connection_add_filter()
* are run. If any filter returns #DBUS_HANDLER_RESULT_HANDLED
* then processing stops after that filter.
*
* Third, if the message is a method call it is forwarded to
* any registered object path handlers added with
* dbus_connection_register_object_path() or
* dbus_connection_register_fallback().
*
* A single call to dbus_connection_dispatch() will process at most
* one message; it will not clear the entire message queue.
* *
* Be careful about calling dbus_connection_dispatch() from inside a * Be careful about calling dbus_connection_dispatch() from inside a
* message handler, i.e. calling dbus_connection_dispatch() * message handler, i.e. calling dbus_connection_dispatch()
......
...@@ -123,6 +123,8 @@ dbus_bool_t _dbus_hash_table_insert_ulong (DBusHashTable *table, ...@@ -123,6 +123,8 @@ dbus_bool_t _dbus_hash_table_insert_ulong (DBusHashTable *table,
int _dbus_hash_table_get_n_entries (DBusHashTable *table); int _dbus_hash_table_get_n_entries (DBusHashTable *table);
/* Preallocation */ /* Preallocation */
/** A preallocated hash entry */
typedef struct DBusPreallocatedHash DBusPreallocatedHash; typedef struct DBusPreallocatedHash DBusPreallocatedHash;
DBusPreallocatedHash *_dbus_hash_table_preallocate_entry (DBusHashTable *table); DBusPreallocatedHash *_dbus_hash_table_preallocate_entry (DBusHashTable *table);
......
...@@ -321,7 +321,7 @@ skip_one_complete_type (const DBusString *type_str, ...@@ -321,7 +321,7 @@ skip_one_complete_type (const DBusString *type_str,
* type position is stored in the same variable. * type position is stored in the same variable.
* *
* @param type_str a type signature (must be valid) * @param type_str a type signature (must be valid)
* @param type_pos an integer position in the type signtaure (in and out) * @param type_pos an integer position in the type signature (in and out)
*/ */
void void
_dbus_type_signature_next (const char *type_str, _dbus_type_signature_next (const char *type_str,
......
...@@ -183,11 +183,17 @@ _dbus_check_is_valid_##what (const char *name) \ ...@@ -183,11 +183,17 @@ _dbus_check_is_valid_##what (const char *name) \
} }
#endif /* !DBUS_DISABLE_CHECKS */ #endif /* !DBUS_DISABLE_CHECKS */
/** defines _dbus_check_is_valid_path() */
DECLARE_DBUS_NAME_CHECK(path); DECLARE_DBUS_NAME_CHECK(path);
/** defines _dbus_check_is_valid_interface() */
DECLARE_DBUS_NAME_CHECK(interface); DECLARE_DBUS_NAME_CHECK(interface);
/** defines _dbus_check_is_valid_member() */
DECLARE_DBUS_NAME_CHECK(member); DECLARE_DBUS_NAME_CHECK(member);
/** defines _dbus_check_is_valid_error_name() */
DECLARE_DBUS_NAME_CHECK(error_name); DECLARE_DBUS_NAME_CHECK(error_name);
/** defines _dbus_check_is_valid_bus_name() */
DECLARE_DBUS_NAME_CHECK(bus_name); DECLARE_DBUS_NAME_CHECK(bus_name);
/** defines _dbus_check_is_valid_signature() */
DECLARE_DBUS_NAME_CHECK(signature); DECLARE_DBUS_NAME_CHECK(signature);
/** @} */ /** @} */
......
...@@ -615,8 +615,14 @@ dbus_pending_call_set_notify (DBusPendingCall *pending, ...@@ -615,8 +615,14 @@ dbus_pending_call_set_notify (DBusPendingCall *pending,
* Cancels the pending call, such that any reply or error received * Cancels the pending call, such that any reply or error received
* will just be ignored. Drops the dbus library's internal reference * will just be ignored. Drops the dbus library's internal reference
* to the #DBusPendingCall so will free the call if nobody else is * to the #DBusPendingCall so will free the call if nobody else is
* holding a reference. However you usually get a reference * holding a reference. However you usually get a reference from
* from dbus_connection_send() so probably your app owns a ref also. * dbus_connection_send_with_reply() so probably your app owns a ref
* also.
*
* Note that canceling a pending call will <em>not</em> simulate a
* timed-out call; if a call times out, then a timeout error reply is
* received. If you cancel the call, no reply is received unless the
* the reply was already received before you canceled.
* *
* @param pending the pending call * @param pending the pending call
*/ */
......
...@@ -50,10 +50,10 @@ extern "C" { ...@@ -50,10 +50,10 @@ extern "C" {
/* Message byte order */ /* Message byte order */
#define DBUS_LITTLE_ENDIAN ('l') /**< LSB first */ #define DBUS_LITTLE_ENDIAN ('l') /**< Code marking LSB-first byte order in the wire protocol. */
#define DBUS_BIG_ENDIAN ('B') /**< MSB first */ #define DBUS_BIG_ENDIAN ('B') /**< Code marking MSB-first byte order in the wire protocol. */
/** Protocol version */ /** Protocol version. */
#define DBUS_MAJOR_PROTOCOL_VERSION 1 #define DBUS_MAJOR_PROTOCOL_VERSION 1
/** Type code that is never equal to a legitimate type code */ /** Type code that is never equal to a legitimate type code */
......
...@@ -36,12 +36,11 @@ ...@@ -36,12 +36,11 @@
* @ingroup DBus * @ingroup DBus
* @brief Server that listens for new connections. * @brief Server that listens for new connections.
* *
* Types and functions related to DBusServer.
* A DBusServer represents a server that other applications * A DBusServer represents a server that other applications
* can connect to. Each connection from another application * can connect to. Each connection from another application
* is represented by a DBusConnection. * is represented by a #DBusConnection.
* *
* @todo Thread safety hasn't been looked at for #DBusServer * @todo Thread safety hasn't been tested much for #DBusServer
* @todo Need notification to apps of disconnection, may matter for some transports * @todo Need notification to apps of disconnection, may matter for some transports
*/ */
...@@ -518,20 +517,23 @@ static const struct { ...@@ -518,20 +517,23 @@ static const struct {
}; };
/** /**
* Listens for new connections on the given address. * Listens for new connections on the given address. If there are
* If there are multiple address entries in the address, * multiple semicolon-separated address entries in the address, tries
* tries each one and listens on the first one that * each one and listens on the first one that works.
* works.
* *
* Returns #NULL and sets error if listening fails for any reason. * Returns #NULL and sets error if listening fails for any reason.
* Otherwise returns a new #DBusServer. * Otherwise returns a new #DBusServer.
* dbus_server_set_new_connection_function() and * dbus_server_set_new_connection_function(),
* dbus_server_set_watch_functions() should be called * dbus_server_set_watch_functions(), and
* immediately to render the server fully functional. * dbus_server_set_timeout_functions() should be called immediately to
* render the server fully functional.
*
* To free the server, applications must call first
* dbus_server_disconnect() and then dbus_server_unref().
* *
* @param address the address of this server. * @param address the address of this server.
* @param error location to store rationale for failure. * @param error location to store reason for failure.
* @returns a new DBusServer, or #NULL on failure. * @returns a new #DBusServer, or #NULL on failure.
* *
*/ */
DBusServer* DBusServer*
...@@ -841,7 +843,7 @@ dbus_server_set_new_connection_function (DBusServer *server, ...@@ -841,7 +843,7 @@ dbus_server_set_new_connection_function (DBusServer *server,
} }
/** /**
* Sets the watch functions for the connection. These functions are * Sets the watch functions for the server. These functions are
* responsible for making the application's main loop aware of file * responsible for making the application's main loop aware of file
* descriptors that need to be monitored for events. * descriptors that need to be monitored for events.
* *
...@@ -895,7 +897,7 @@ dbus_server_set_watch_functions (DBusServer *server, ...@@ -895,7 +897,7 @@ dbus_server_set_watch_functions (DBusServer *server,
} }
/** /**
* Sets the timeout functions for the connection. These functions are * Sets the timeout functions for the server. These functions are
* responsible for making the application's main loop aware of timeouts. * responsible for making the application's main loop aware of timeouts.
* *
* This function behaves exactly like dbus_connection_set_timeout_functions(); * This function behaves exactly like dbus_connection_set_timeout_functions();
...@@ -948,10 +950,13 @@ dbus_server_set_timeout_functions (DBusServer *server, ...@@ -948,10 +950,13 @@ dbus_server_set_timeout_functions (DBusServer *server,
} }
/** /**
* Sets the authentication mechanisms that this server offers * Sets the authentication mechanisms that this server offers to
* to clients, as a list of SASL mechanisms. This function * clients, as a #NULL-terminated array of mechanism names. This
* only affects connections created *after* it is called. * function only affects connections created <em>after</em> it is
* Pass #NULL instead of an array to use all available mechanisms. * called. Pass #NULL instead of an array to use all available
* mechanisms (this is the default behavior).
*
* The D-Bus specification describes some of the supported mechanisms.
* *
* @param server the server * @param server the server
* @param mechanisms #NULL-terminated array of mechanisms * @param mechanisms #NULL-terminated array of mechanisms
......
...@@ -116,8 +116,8 @@ typedef enum ...@@ -116,8 +116,8 @@ typedef enum
#define DBUS_RELEASE_NAME_REPLY_NOT_OWNER 3 /**< Service is not an owner of the given name */ #define DBUS_RELEASE_NAME_REPLY_NOT_OWNER 3 /**< Service is not an owner of the given name */
/* Replies to service starts */ /* Replies to service starts */
#define DBUS_START_REPLY_SUCCESS 1 /**< service was auto started */ #define DBUS_START_REPLY_SUCCESS 1 /**< Service was auto started */
#define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< service was already running */ #define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< Service was already running */
/** @} */ /** @} */
......
...@@ -37,6 +37,14 @@ typedef struct ...@@ -37,6 +37,14 @@ typedef struct
unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */ unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
} DBusSignatureRealIter; } DBusSignatureRealIter;
/** macro that checks whether a typecode is a container type */
#define TYPE_IS_CONTAINER(typecode) \
((typecode) == DBUS_TYPE_STRUCT || \
(typecode) == DBUS_TYPE_DICT_ENTRY || \
(typecode) == DBUS_TYPE_VARIANT || \
(typecode) == DBUS_TYPE_ARRAY)
/** /**
* @defgroup DBusSignature Type signature parsing * @defgroup DBusSignature Type signature parsing
* @ingroup DBus * @ingroup DBus
...@@ -73,10 +81,10 @@ dbus_signature_iter_init (DBusSignatureIter *iter, ...@@ -73,10 +81,10 @@ dbus_signature_iter_init (DBusSignatureIter *iter,
* character such as '(' for a structure, the corresponding type for * character such as '(' for a structure, the corresponding type for
* the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('. * the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('.
* In this case, you should initialize a sub-iterator with * In this case, you should initialize a sub-iterator with
* dbus_signature_iter_recurse to parse the container type. * dbus_signature_iter_recurse() to parse the container type.
* *
* @param iter pointer to an iterator * @param iter pointer to an iterator
* @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY) * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY)
*/ */
int int
dbus_signature_iter_get_current_type (const DBusSignatureIter *iter) dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
...@@ -87,11 +95,16 @@ dbus_signature_iter_get_current_type (const DBusSignatureIter *iter) ...@@ -87,11 +95,16 @@ dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
} }
/** /**
* Returns the full type signature represented by the current * Returns the signature of the single complete type starting at the
* iterator as a C string. * given iterator.
*
* For example, if the iterator is pointing at the start of "(ii)ii"
* (which is "a struct of two ints, followed by an int, followed by an
* int"), then "(ii)" would be returned. If the iterator is pointing at
* one of the "i" then just that "i" would be returned.
* *
* @param iter pointer to an iterator * @param iter pointer to an iterator
* @returns current signature; or NULL on OOM. Should be freed with #dbus_free * @returns current signature; or #NULL if no memory. Should be freed with dbus_free()
*/ */
char * char *
dbus_signature_iter_get_signature (const DBusSignatureIter *iter) dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
...@@ -121,8 +134,8 @@ dbus_signature_iter_get_signature (const DBusSignatureIter *iter) ...@@ -121,8 +134,8 @@ dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
* This function allows you to avoid initializing a sub-iterator and * This function allows you to avoid initializing a sub-iterator and
* getting its current type. * getting its current type.
* *
* It is an error to invoke this function if the current type of the * Undefined behavior results if you invoke this function when the
* iterator is not DBUS_TYPE_ARRAY. * current type of the iterator is not #DBUS_TYPE_ARRAY.
* *
* @param iter pointer to an iterator * @param iter pointer to an iterator
* @returns current array element type * @returns current array element type
...@@ -139,7 +152,7 @@ dbus_signature_iter_get_element_type (const DBusSignatureIter *iter) ...@@ -139,7 +152,7 @@ dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
/** /**
* Skip to the next value on this "level". e.g. the next field in a * Skip to the next value on this "level". e.g. the next field in a
* struct, the next value in an array. Returns FALSE at the end of the * struct, the next value in an array. Returns #FALSE at the end of the
* current container. * current container.
* *
* @param iter the iterator * @param iter the iterator
...@@ -178,9 +191,12 @@ dbus_signature_iter_next (DBusSignatureIter *iter) ...@@ -178,9 +191,12 @@ dbus_signature_iter_next (DBusSignatureIter *iter)
} }
/** /**
* Initialize a new iterator pointing to the first type current * Initialize a new iterator pointing to the first type in the current
* container. It's an error to call this if the current type is a * container.
* non-container (i.e. if dbus_type_is_container returns FALSE). *
* The results are undefined when calling this if the current type is
* a non-container (i.e. if dbus_type_is_container() returns #FALSE
* for the result of dbus_signature_iter_get_current_type()).
* *
* @param iter the current interator * @param iter the current interator
* @param subiter an iterator to initialize pointing to the first child * @param subiter an iterator to initialize pointing to the first child
...@@ -203,11 +219,13 @@ dbus_signature_iter_recurse (const DBusSignatureIter *iter, ...@@ -203,11 +219,13 @@ dbus_signature_iter_recurse (const DBusSignatureIter *iter,
} }
/** /**
* Check a type signature for validity. * Check a type signature for validity. Remember that #NULL can always
* be passed instead of a DBusError*, if you don't care about having
* an error name and message.
* *
* @param signature a potentially invalid type signature * @param signature a potentially invalid type signature
* @param error error return * @param error error return
* @returns TRUE iif signature is valid * @returns #TRUE if signature is valid or #FALSE if an error is set
*/ */
dbus_bool_t dbus_bool_t
dbus_signature_validate (const char *signature, dbus_signature_validate (const char *signature,
...@@ -224,12 +242,15 @@ dbus_signature_validate (const char *signature, ...@@ -224,12 +242,15 @@ dbus_signature_validate (const char *signature,
} }
/** /**
* Check that a type signature is both valid and contains exactly * Check that a type signature is both valid and contains exactly one
* one complete type. * complete type. "One complete type" means a single basic type,
* array, struct, or dictionary, though the struct or array may be
* arbitrarily recursive and complex. More than one complete type
* would mean for example "ii" or two integers in sequence.
* *
* @param signature a potentially invalid type signature * @param signature a potentially invalid type signature
* @param error error return * @param error error return
* @returns TRUE iif signature is valid and has exactly one complete type * @returns #TRUE if signature is valid and has exactly one complete type
*/ */
dbus_bool_t dbus_bool_t
dbus_signature_validate_single (const char *signature, dbus_signature_validate_single (const char *signature,
...@@ -250,16 +271,10 @@ dbus_signature_validate_single (const char *signature, ...@@ -250,16 +271,10 @@ dbus_signature_validate_single (const char *signature,
return FALSE; return FALSE;
} }
/** macro that checks whether a typecode is a container type */
#define TYPE_IS_CONTAINER(typecode) \
((typecode) == DBUS_TYPE_STRUCT || \
(typecode) == DBUS_TYPE_DICT_ENTRY || \
(typecode) == DBUS_TYPE_VARIANT || \
(typecode) == DBUS_TYPE_ARRAY)
/** /**
* A "container type" can contain basic types, or nested * A "container type" can contain basic types, or nested
* container types. #DBUS_TYPE_INVALID is not a container type. * container types. #DBUS_TYPE_INVALID is not a container type.
*
* This function will crash if passed a typecode that isn't * This function will crash if passed a typecode that isn't
* in dbus-protocol.h * in dbus-protocol.h
* *
...@@ -275,15 +290,15 @@ dbus_type_is_container (int typecode) ...@@ -275,15 +290,15 @@ dbus_type_is_container (int typecode)
} }
/** /**
* A "basic type" is a somewhat arbitrary concept, but the intent * A "basic type" is a somewhat arbitrary concept, but the intent is
* is to include those types that are fully-specified by a single * to include those types that are fully-specified by a single
* typecode, with no additional type information or nested * typecode, with no additional type information or nested values. So
* values. So all numbers and strings are basic types and * all numbers and strings are basic types and structs, arrays, and
* structs, arrays, and variants are not basic types. * variants are not basic types. #DBUS_TYPE_INVALID is not a basic
* #DBUS_TYPE_INVALID is not a basic type. * type.
* *
* This function will crash if passed a typecode that isn't * This function will crash if passed a typecode that isn't
* in dbus-protocol.h * in dbus-protocol.h
* *
* @returns #TRUE if type is basic * @returns #TRUE if type is basic
*/ */
...@@ -304,14 +319,25 @@ dbus_type_is_basic (int typecode) ...@@ -304,14 +319,25 @@ dbus_type_is_basic (int typecode)
* first byte of the old and new value would be in the same location, * first byte of the old and new value would be in the same location,
* so alignment padding is not a factor. * so alignment padding is not a factor.
* *
* This function is useful to determine whether #dbus_message_iter_get_fixed_array * This function is useful to determine whether
* may be used. * dbus_message_iter_get_fixed_array() may be used.
*
* Some structs are fixed-size (if they contain only fixed-size types)
* but struct is not considered a fixed type for purposes of this
* function.
* *
* This function will crash if passed a typecode that isn't
* in dbus-protocol.h
*
* @returns #FALSE if the type can occupy different lengths * @returns #FALSE if the type can occupy different lengths
*/ */
dbus_bool_t dbus_bool_t
dbus_type_is_fixed (int typecode) dbus_type_is_fixed (int typecode)
{ {
/* only reasonable (non-line-noise) typecodes are allowed */
_dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
FALSE);
switch (typecode) switch (typecode)
{ {
case DBUS_TYPE_BYTE: case DBUS_TYPE_BYTE:
......
...@@ -56,41 +56,51 @@ DBUS_BEGIN_DECLS ...@@ -56,41 +56,51 @@ DBUS_BEGIN_DECLS
* dbus-memory.c) * dbus-memory.c)
*/ */