DBusMessage implementation details
[D-Bus secret internal implementation details]

DBusMessage private implementation details. More...

Data Structures
struct	DBusMessageLoader
	Implementation details of DBusMessageLoader. More...
struct	DBusMessage
	Internals of DBusMessage. More...
struct	DBusMessageRealIter
	Internals of DBusMessageIter. More...
Defines
#define	CHANGED_STAMP_BITS   21
	How many bits are in the changed_stamp used to validate iterators.
#define	ensure_byte_order(message)
	byte-swap the message if it doesn't match our byte order.
#define	MAX_MESSAGE_SIZE_TO_CACHE   10 * _DBUS_ONE_KILOBYTE
	Avoid caching huge messages.
#define	MAX_MESSAGE_CACHE_SIZE   5
	Avoid caching too many messages.
#define	INITIAL_LOADER_DATA_LEN   32
	The initial buffer size of the message loader.
Typedefs
typedef DBusMessageRealIter	DBusMessageRealIter
	typedef for internals of message iterator
typedef DBusMessageLoader	DBusMessageLoader
	The DBusMessageLoader object encapsulates the process of converting a byte stream into a series of DBusMessage.
Enumerations
enum	{ DBUS_MESSAGE_ITER_TYPE_READER = 3, DBUS_MESSAGE_ITER_TYPE_WRITER = 7 }
Functions
dbus_bool_t	_dbus_message_iter_get_args_valist (DBusMessageIter *iter, DBusError *error, int first_arg_type, va_list var_args)
	Implementation of the varargs arg-getting functions.
	_DBUS_STRING_DEFINE_STATIC (_dbus_empty_signature_str,"")
	An static string representing an empty signature.
void	_dbus_message_get_network_data (DBusMessage *message, const DBusString **header, const DBusString **body)
	Gets the data to be sent over the network for this message.
void	_dbus_message_set_serial (DBusMessage *message, dbus_uint32_t serial)
	Sets the serial number of a message.
void	_dbus_message_add_size_counter_link (DBusMessage *message, DBusList *link)
	Adds a counter to be incremented immediately with the size of this message, and decremented by the size of this message when this message if finalized.
dbus_bool_t	_dbus_message_add_size_counter (DBusMessage *message, DBusCounter *counter)
	Adds a counter to be incremented immediately with the size of this message, and decremented by the size of this message when this message if finalized.
void	_dbus_message_remove_size_counter (DBusMessage *message, DBusCounter *counter, DBusList **link_return)
	Removes a counter tracking the size of this message, and decrements the counter by the size of this message.
void	_dbus_message_lock (DBusMessage *message)
	Locks a message.
DBusMessageLoader *	_dbus_message_loader_new (void)
	Creates a new message loader.
DBusMessageLoader *	_dbus_message_loader_ref (DBusMessageLoader *loader)
	Increments the reference count of the loader.
void	_dbus_message_loader_unref (DBusMessageLoader *loader)
	Decrements the reference count of the loader and finalizes the loader when the count reaches zero.
void	_dbus_message_loader_get_buffer (DBusMessageLoader *loader, DBusString **buffer)
	Gets the buffer to use for reading data from the network.
void	_dbus_message_loader_return_buffer (DBusMessageLoader *loader, DBusString *buffer, int bytes_read)
	Returns a buffer obtained from _dbus_message_loader_get_buffer(), indicating to the loader how many bytes of the buffer were filled in.
dbus_bool_t	_dbus_message_loader_queue_messages (DBusMessageLoader *loader)
	Converts buffered data into messages, if we have enough data.
DBusMessage *	_dbus_message_loader_peek_message (DBusMessageLoader *loader)
	Peeks at first loaded message, returns NULL if no messages have been queued.
DBusMessage *	_dbus_message_loader_pop_message (DBusMessageLoader *loader)
	Pops a loaded message (passing ownership of the message to the caller).
DBusList *	_dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
	Pops a loaded message inside a list link (passing ownership of the message and link to the caller).
void	_dbus_message_loader_putback_message_link (DBusMessageLoader *loader, DBusList *link)
	Returns a popped message link, used to undo a pop.
dbus_bool_t	_dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
	Checks whether the loader is confused due to bad data.
void	_dbus_message_loader_set_max_message_size (DBusMessageLoader *loader, long size)
	Sets the maximum size message we allow.
long	_dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
	Gets the maximum allowed message size in bytes.
dbus_bool_t	dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
	Allocates an integer ID to be used for storing application-specific data on any DBusMessage.
void	dbus_message_free_data_slot (dbus_int32_t *slot_p)
	Deallocates a global ID for message data slots.
dbus_bool_t	dbus_message_set_data (DBusMessage *message, dbus_int32_t slot, void *data, DBusFreeFunction free_data_func)
	Stores a pointer on a DBusMessage, along with an optional function to be used for freeing the data when the data is set again, or when the message is finalized.
void *	dbus_message_get_data (DBusMessage *message, dbus_int32_t slot)
	Retrieves data previously set with dbus_message_set_data().
int	dbus_message_type_from_string (const char *type_str)
	Utility function to convert a machine-readable (not translated) string into a D-Bus message type.
const char *	dbus_message_type_to_string (int type)
	Utility function to convert a D-Bus message type into a machine-readable string (not translated).
dbus_bool_t	dbus_message_marshal (DBusMessage *msg, char **marshalled_data_p, int *len_p)
	Turn a DBusMessage into the marshalled form as described in the D-Bus specification.
DBusMessage *	dbus_message_demarshal (const char *str, int len, DBusError *error)
	Demarshal a D-Bus message from the format described in the D-Bus specification.

---

Detailed Description

DBusMessage private implementation details.

The guts of DBusMessage and its methods.

---

Define Documentation

#define ensure_byte_order

(

message

)

Value:

if (message->byte_order != DBUS_COMPILER_BYTE_ORDER)   \
   _dbus_message_byteswap (message)

byte-swap the message if it doesn't match our byte order.

Called only when we need the message in our own byte order, normally when reading arrays of integers or doubles. Otherwise should not be called since it would do needless work.

Definition at line 137 of file dbus-message.c.

#define INITIAL_LOADER_DATA_LEN   32

The initial buffer size of the message loader.

Todo:

this should be based on min header size plus some average body size, or something. Or rather, the min header size only, if we want to try to read only the header, store that in a DBusMessage, then read only the body and store that, etc., depends on how we optimize _dbus_message_loader_get_buffer() and what the exact message format is.

Definition at line 3295 of file dbus-message.c.

Referenced by _dbus_message_loader_new().

---

Typedef Documentation

DBusMessageLoader

The DBusMessageLoader object encapsulates the process of converting a byte stream into a series of DBusMessage.

It buffers the incoming bytes as efficiently as possible, and generates a queue of messages. DBusMessageLoader is typically used as part of a DBusTransport implementation. The DBusTransport then hands off the loaded messages to a DBusConnection, making the messages visible to the application.

Todo:

write tests for break-loader that a) randomly delete header fields and b) set string fields to zero-length and other funky values.

Definition at line 32 of file dbus-message-internal.h.

---

Function Documentation

dbus_bool_t _dbus_message_add_size_counter	(	DBusMessage *	message,
		DBusCounter *	counter
	)

Adds a counter to be incremented immediately with the size of this message, and decremented by the size of this message when this message if finalized.

Parameters:

	message	the message
	counter	the counter

Returns:

FALSE if no memory

Definition at line 229 of file dbus-message.c.

References _dbus_counter_ref(), _dbus_list_alloc_link(), _dbus_message_add_size_counter_link(), FALSE, NULL, and TRUE.

Referenced by _dbus_transport_queue_messages().

void _dbus_message_add_size_counter_link	(	DBusMessage *	message,
		DBusList *	link
	)

Adds a counter to be incremented immediately with the size of this message, and decremented by the size of this message when this message if finalized.

The link contains a counter with its refcount already incremented, but the counter itself not incremented. Ownership of link and counter refcount is passed to the message.

Parameters:

	message	the message
	link	link with counter as data

Definition at line 193 of file dbus-message.c.

References _dbus_counter_adjust(), _dbus_list_append_link(), DBusMessage::body, DBusList::data, DBusHeader::data, DBusMessage::header, NULL, DBusMessage::size_counter_delta, and DBusMessage::size_counters.

Referenced by _dbus_message_add_size_counter().

void _dbus_message_get_network_data	(	DBusMessage *	message,
		const DBusString **	header,
		const DBusString **	body
	)

Gets the data to be sent over the network for this message.

The header and then the body should be written out. This function is guaranteed to always return the same data once a message is locked (with _dbus_message_lock()).

Parameters:

	message	the message.
	header	return location for message header data.
	body	return location for message body data.

Definition at line 152 of file dbus-message.c.

References _dbus_assert, DBusMessage::body, DBusHeader::data, DBusMessage::header, and DBusMessage::locked.

dbus_bool_t _dbus_message_iter_get_args_valist	(	DBusMessageIter *	iter,
		DBusError *	error,
		int	first_arg_type,
		va_list	var_args
	)

Implementation of the varargs arg-getting functions.

dbus_message_get_args() is the place to go for complete documentation.

See also:

dbus_message_get_args

Parameters:

	iter	the message iter
	error	error to be filled in
	first_arg_type	type of the first argument
	var_args	return location for first argument, followed by list of type/location pairs

Returns:

FALSE if error was set

Definition at line 641 of file dbus-message.c.

References _dbus_assert, _dbus_strdup(), _dbus_type_reader_get_current_type(), _dbus_type_reader_get_element_type(), _dbus_type_reader_next(), _dbus_type_reader_read_basic(), _dbus_type_reader_read_fixed_multi(), _dbus_type_reader_recurse(), _dbus_type_to_string(), _dbus_warn(), DBUS_ERROR_INVALID_ARGS, dbus_free_string_array(), dbus_message_iter_get_arg_type(), dbus_new0, dbus_set_error(), DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID, dbus_type_is_basic(), dbus_type_is_fixed(), DBUS_TYPE_OBJECT_PATH, DBUS_TYPE_SIGNATURE, DBUS_TYPE_STRING, FALSE, NULL, and TRUE.

Referenced by dbus_message_get_args_valist().

void _dbus_message_loader_get_buffer	(	DBusMessageLoader *	loader,
		DBusString **	buffer
	)

Gets the buffer to use for reading data from the network.

Network data is read directly into an allocated buffer, which is then used in the DBusMessage, to avoid as many extra memcpy's as possible. The buffer must always be returned immediately using _dbus_message_loader_return_buffer(), even if no bytes are successfully read.

Todo:

this function can be a lot more clever. For example it can probably always return a buffer size to read exactly the body of the next message, thus avoiding any memory wastage or reallocs.

Todo:

we need to enforce a max length on strings in header fields.

Parameters:

	loader	the message loader.
	buffer	the buffer

Definition at line 3387 of file dbus-message.c.

References _dbus_assert, DBusMessageLoader::buffer_outstanding, DBusMessageLoader::data, and TRUE.

Referenced by dbus_message_demarshal().

dbus_bool_t _dbus_message_loader_get_is_corrupted

(

DBusMessageLoader *

loader

)

Checks whether the loader is confused due to bad data.

If messages are received that are invalid, the loader gets confused and gives up permanently. This state is called "corrupted."

Parameters:

loader

the loader

Returns:

TRUE if the loader is hosed.

Definition at line 3717 of file dbus-message.c.

References _dbus_assert, DBusMessageLoader::corrupted, DBusMessageLoader::corruption_reason, and DBUS_VALID.

Referenced by _dbus_transport_queue_messages(), and dbus_message_demarshal().

long _dbus_message_loader_get_max_message_size

(

DBusMessageLoader *

loader

)

Gets the maximum allowed message size in bytes.

Parameters:

loader

the loader

Returns:

max size in bytes

Definition at line 3750 of file dbus-message.c.

References DBusMessageLoader::max_message_size.

Referenced by _dbus_transport_get_max_message_size().

DBusMessageLoader* _dbus_message_loader_new

(

void

)

Creates a new message loader.

Returns NULL if memory can't be allocated.

Returns:

new loader, or NULL.

Definition at line 3304 of file dbus-message.c.

References _dbus_string_init(), _dbus_string_set_length(), DBusMessageLoader::corrupted, DBusMessageLoader::corruption_reason, DBusMessageLoader::data, dbus_free(), DBUS_MAXIMUM_MESSAGE_LENGTH, dbus_new0, DBUS_VALID, FALSE, INITIAL_LOADER_DATA_LEN, DBusMessageLoader::max_message_size, NULL, and DBusMessageLoader::refcount.

Referenced by _dbus_transport_init_base(), and dbus_message_demarshal().

DBusMessage* _dbus_message_loader_peek_message

(

DBusMessageLoader *

loader

)

Peeks at first loaded message, returns NULL if no messages have been queued.

Parameters:

loader

the loader.

Returns:

the next message, or NULL if none.

Definition at line 3658 of file dbus-message.c.

References DBusList::data, DBusMessageLoader::messages, and NULL.

Referenced by _dbus_transport_get_dispatch_status().

DBusMessage* _dbus_message_loader_pop_message

(

DBusMessageLoader *

loader

)

Pops a loaded message (passing ownership of the message to the caller).

Returns NULL if no messages have been queued.

Parameters:

loader

the loader.

Returns:

the next message, or NULL if none.

Definition at line 3675 of file dbus-message.c.

References _dbus_list_pop_first(), and DBusMessageLoader::messages.

Referenced by dbus_message_demarshal().

DBusList* _dbus_message_loader_pop_message_link

(

DBusMessageLoader *

loader

)

Pops a loaded message inside a list link (passing ownership of the message and link to the caller).

Returns NULL if no messages have been loaded.

Parameters:

loader

the loader.

Returns:

the next message link, or NULL if none.

Definition at line 3689 of file dbus-message.c.

References _dbus_list_pop_first_link(), and DBusMessageLoader::messages.

Referenced by _dbus_transport_queue_messages().

void _dbus_message_loader_putback_message_link	(	DBusMessageLoader *	loader,
		DBusList *	link
	)

Returns a popped message link, used to undo a pop.

Parameters:

	loader	the loader
	link	the link with a message in it

Definition at line 3701 of file dbus-message.c.

References _dbus_list_prepend_link(), and DBusMessageLoader::messages.

Referenced by _dbus_transport_queue_messages().

dbus_bool_t _dbus_message_loader_queue_messages

(

DBusMessageLoader *

loader

)

Converts buffered data into messages, if we have enough data.

If we don't have enough data, does nothing.

Todo:

we need to check that the proper named header fields exist for each message type.

Todo:

If a message has unknown type, we should probably eat it right here rather than passing it out to applications. However it's not an error to see messages of unknown type.

Parameters:

loader

the loader.

Returns:

TRUE if we had enough memory to finish.

Definition at line 3595 of file dbus-message.c.

References _dbus_assert, _dbus_header_have_message_untrusted(), _dbus_list_find_last(), DBusMessageLoader::corrupted, DBusMessageLoader::corruption_reason, DBusMessageLoader::data, dbus_message_unref(), DBUS_MINIMUM_HEADER_SIZE, DBUS_VALID, FALSE, DBusMessageLoader::max_message_size, NULL, and TRUE.

Referenced by _dbus_transport_get_dispatch_status(), and dbus_message_demarshal().

DBusMessageLoader* _dbus_message_loader_ref

(

DBusMessageLoader *

loader

)

Increments the reference count of the loader.

Parameters:

loader

the loader.

Returns:

the loader

Definition at line 3340 of file dbus-message.c.

References DBusMessageLoader::refcount.

void _dbus_message_loader_return_buffer	(	DBusMessageLoader *	loader,
		DBusString *	buffer,
		int	bytes_read
	)

Returns a buffer obtained from _dbus_message_loader_get_buffer(), indicating to the loader how many bytes of the buffer were filled in.

This function must always be called, even if no bytes were successfully read.

Parameters:

	loader	the loader.
	buffer	the buffer.
	bytes_read	number of bytes that were read into the buffer.

Definition at line 3408 of file dbus-message.c.

References _dbus_assert, DBusMessageLoader::buffer_outstanding, DBusMessageLoader::data, and FALSE.

Referenced by dbus_message_demarshal().

void _dbus_message_loader_set_max_message_size	(	DBusMessageLoader *	loader,
		long	size
	)

Sets the maximum size message we allow.

Parameters:

	loader	the loader
	size	the max message size in bytes

Definition at line 3731 of file dbus-message.c.

References DBUS_MAXIMUM_MESSAGE_LENGTH, and DBusMessageLoader::max_message_size.

Referenced by _dbus_transport_set_max_message_size().

void _dbus_message_loader_unref

(

DBusMessageLoader *

loader

)

Decrements the reference count of the loader and finalizes the loader when the count reaches zero.

Parameters:

loader

the loader.

Definition at line 3354 of file dbus-message.c.

References _dbus_list_clear(), _dbus_list_foreach(), _dbus_string_free(), DBusMessageLoader::data, dbus_free(), dbus_message_unref(), DBusMessageLoader::messages, NULL, and DBusMessageLoader::refcount.

Referenced by _dbus_transport_finalize_base(), _dbus_transport_init_base(), and dbus_message_demarshal().

void _dbus_message_lock

(

DBusMessage *

message

)

Locks a message.

Allows checking that applications don't keep a reference to a message in the outgoing queue and change it underneath us. Messages are locked when they enter the outgoing queue (dbus_connection_send_message()), and the library complains if the message is modified while locked.

Parameters:

message

the message to lock.

Definition at line 285 of file dbus-message.c.

References _dbus_assert, _dbus_header_update_lengths(), DBusMessage::body, dbus_message_get_signature(), DBusMessage::header, DBusMessage::locked, NULL, and TRUE.

void _dbus_message_remove_size_counter	(	DBusMessage *	message,
		DBusCounter *	counter,
		DBusList **	link_return
	)

Removes a counter tracking the size of this message, and decrements the counter by the size of this message.

Parameters:

	message	the message
	link_return	return the link used
	counter	the counter

Definition at line 253 of file dbus-message.c.

References _dbus_assert, _dbus_counter_adjust(), _dbus_counter_unref(), _dbus_list_find_last(), _dbus_list_free_link(), _dbus_list_unlink(), NULL, DBusMessage::size_counter_delta, and DBusMessage::size_counters.

Referenced by _dbus_connection_message_sent().

void _dbus_message_set_serial	(	DBusMessage *	message,
		dbus_uint32_t	serial
	)

Sets the serial number of a message.

This can only be done once on a message.

Parameters:

	message	the message
	serial	the serial

Definition at line 170 of file dbus-message.c.

References _dbus_assert, _dbus_header_set_serial(), dbus_message_get_serial(), DBusMessage::locked, and NULL.

Referenced by dbus_connection_send_with_reply().

dbus_bool_t dbus_message_allocate_data_slot

(

dbus_int32_t *

slot_p

)

Allocates an integer ID to be used for storing application-specific data on any DBusMessage.

The allocated ID may then be used with dbus_message_set_data() and dbus_message_get_data(). The passed-in slot must be initialized to -1, and is filled in with the slot ID. If the passed-in slot is not -1, it's assumed to be already allocated, and its refcount is incremented.

The allocated slot is global, i.e. all DBusMessage objects will have a slot with the given integer ID reserved.

Parameters:

slot_p

address of a global variable storing the slot

Returns:

FALSE on failure (no memory)

Definition at line 3773 of file dbus-message.c.

References _dbus_data_slot_allocator_alloc(), and _DBUS_LOCK_NAME.

DBusMessage* dbus_message_demarshal	(	const char *	str,
		int	len,
		DBusError *	error
	)

Demarshal a D-Bus message from the format described in the D-Bus specification.

Generally, this function is only useful for encapsulating D-Bus messages in a different protocol.

Parameters:

	str	the marshalled DBusMessage
	len	the length of str
	error	the location to save errors to

Returns:

NULL if there was an error

Definition at line 3982 of file dbus-message.c.

References _dbus_message_loader_get_buffer(), _dbus_message_loader_get_is_corrupted(), _dbus_message_loader_new(), _dbus_message_loader_pop_message(), _dbus_message_loader_queue_messages(), _dbus_message_loader_return_buffer(), _dbus_message_loader_unref(), _dbus_string_append_len(), DBUS_ERROR_INVALID_ARGS, dbus_set_error(), and NULL.

void dbus_message_free_data_slot

(

dbus_int32_t *

slot_p

)

Deallocates a global ID for message data slots.

dbus_message_get_data() and dbus_message_set_data() may no longer be used with this slot. Existing data stored on existing DBusMessage objects will be freed when the message is finalized, but may not be retrieved (and may only be replaced if someone else reallocates the slot). When the refcount on the passed-in slot reaches 0, it is set to -1.

Parameters:

slot_p

address storing the slot to deallocate

Definition at line 3792 of file dbus-message.c.

References _dbus_data_slot_allocator_free().

void* dbus_message_get_data	(	DBusMessage *	message,
		dbus_int32_t	slot
	)

Retrieves data previously set with dbus_message_set_data().

The slot must still be allocated (must not have been freed).

Parameters:

	message	the message
	slot	the slot to get data from

Returns:

the data, or NULL if not found

Definition at line 3849 of file dbus-message.c.

References _dbus_data_slot_list_get(), NULL, and DBusMessage::slot_list.

dbus_bool_t dbus_message_marshal	(	DBusMessage *	msg,
		char **	marshalled_data_p,
		int *	len_p
	)

Turn a DBusMessage into the marshalled form as described in the D-Bus specification.

Generally, this function is only useful for encapsulating D-Bus messages in a different protocol.

Parameters:

	msg	the DBusMessage
	marshalled_data_p	the location to save the marshalled form to
	len_p	the location to save the length of the marshalled form to

Returns:

FALSE if there was not enough memory

Definition at line 3935 of file dbus-message.c.

References _dbus_string_copy(), _dbus_string_free(), _dbus_string_init(), _dbus_string_steal_data(), DBusMessage::body, DBusHeader::data, FALSE, DBusMessage::header, NULL, and TRUE.

dbus_bool_t dbus_message_set_data	(	DBusMessage *	message,
		dbus_int32_t	slot,
		void *	data,
		DBusFreeFunction	free_data_func
	)

Stores a pointer on a DBusMessage, along with an optional function to be used for freeing the data when the data is set again, or when the message is finalized.

The slot number must have been allocated with dbus_message_allocate_data_slot().

Parameters:

	message	the message
	slot	the slot number
	data	the data to store
	free_data_func	finalizer function for the data

Returns:

TRUE if there was enough memory to store the data

Definition at line 3813 of file dbus-message.c.

References _dbus_data_slot_list_set(), FALSE, NULL, and DBusMessage::slot_list.

int dbus_message_type_from_string

(

const char *

type_str

)

Utility function to convert a machine-readable (not translated) string into a D-Bus message type.

   "method_call"    -> DBUS_MESSAGE_TYPE_METHOD_CALL
   "method_return"  -> DBUS_MESSAGE_TYPE_METHOD_RETURN
   "signal"         -> DBUS_MESSAGE_TYPE_SIGNAL
   "error"          -> DBUS_MESSAGE_TYPE_ERROR
   anything else    -> DBUS_MESSAGE_TYPE_INVALID

Definition at line 3877 of file dbus-message.c.

References DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_INVALID, DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_METHOD_RETURN, and DBUS_MESSAGE_TYPE_SIGNAL.

const char* dbus_message_type_to_string

(

int

type

)

Utility function to convert a D-Bus message type into a machine-readable string (not translated).

   DBUS_MESSAGE_TYPE_METHOD_CALL    -> "method_call"
   DBUS_MESSAGE_TYPE_METHOD_RETURN  -> "method_return"
   DBUS_MESSAGE_TYPE_SIGNAL         -> "signal"
   DBUS_MESSAGE_TYPE_ERROR          -> "error"
   DBUS_MESSAGE_TYPE_INVALID        -> "invalid"

Definition at line 3905 of file dbus-message.c.

References DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_METHOD_RETURN, and DBUS_MESSAGE_TYPE_SIGNAL.

---