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...

struct	DBusMessageIter_1_10_0
	Layout of a DBusMessageIter on the stack in dbus 1.10.0. More...

struct	DBusVariant
	An opaque data structure containing the serialized form of any single D-Bus message item, whose signature is a single complete type. More...

Macros
#define	CHANGED_STAMP_BITS 21
	How many bits are in the changed_stamp used to validate iterators. More...

#define	_dbus_enable_message_cache() (TRUE)

#define	ensure_byte_order(message) _dbus_message_byteswap (message)
	byte-swap the message if it doesn't match our byte order. More...

#define	MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
	Avoid caching huge messages. More...

#define	MAX_MESSAGE_CACHE_SIZE 5
	Avoid caching too many messages. More...

#define	INITIAL_LOADER_DATA_LEN 32
	The initial buffer size of the message loader. More...

Typedefs
typedef struct DBusMessageRealIter	DBusMessageRealIter
	typedef for internals of message iterator More...

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

Enumerations
enum	{ DBUS_MESSAGE_ITER_TYPE_READER = 3 , DBUS_MESSAGE_ITER_TYPE_WRITER = 7 }

Functions
DBUS_PRIVATE_EXPORT 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. More...

unsigned int	_dbus_message_get_n_unix_fds (DBusMessage *message)
	Gets the number of unix fds attached to this message. More...

void	_dbus_message_trace_ref (DBusMessage message, int old_refcount, int new_refcount, const char why)

	_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. More...

void	_dbus_message_get_unix_fds (DBusMessage message, const int fds, unsigned n_fds)
	Gets the unix fds to be sent over the network for this message. More...

dbus_bool_t	_dbus_message_remove_unknown_fields (DBusMessage *message)
	Remove every header field not known to this version of dbus. More...

void	dbus_message_set_serial (DBusMessage *message, dbus_uint32_t serial)
	Sets the serial number of a message. More...

void	_dbus_message_add_counter_link (DBusMessage message, DBusList link)
	Adds a counter to be incremented immediately with the size/unix fds of this message, and decremented by the size/unix fds of this message when this message if finalized. More...

dbus_bool_t	_dbus_message_add_counter (DBusMessage message, DBusCounter counter)
	Adds a counter to be incremented immediately with the size/unix fds of this message, and decremented by the size/unix fds of this message when this message if finalized. More...

void	_dbus_message_remove_counter (DBusMessage message, DBusCounter counter)
	Removes a counter tracking the size/unix fds of this message, and decrements the counter by the size/unix fds of this message. More...

void	dbus_message_lock (DBusMessage *message)
	Locks a message. More...

void	dbus_message_iter_init_closed (DBusMessageIter *iter)
	Initialize iter as if with DBUS_MESSAGE_ITER_INIT_CLOSED. More...

DBusMessageLoader *	_dbus_message_loader_new (void)
	Creates a new message loader. More...

DBusMessageLoader *	_dbus_message_loader_ref (DBusMessageLoader *loader)
	Increments the reference count of the loader. More...

void	_dbus_message_loader_unref (DBusMessageLoader *loader)
	Decrements the reference count of the loader and finalizes the loader when the count reaches zero. More...

void	_dbus_message_loader_get_buffer (DBusMessageLoader loader, DBusString buffer, int max_to_read, dbus_bool_t *may_read_fds)
	Gets the buffer to use for reading data from the network. More...

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

dbus_bool_t	_dbus_message_loader_queue_messages (DBusMessageLoader *loader)
	Converts buffered data into messages, if we have enough data. More...

DBusMessage *	_dbus_message_loader_peek_message (DBusMessageLoader *loader)
	Peeks at first loaded message, returns NULL if no messages have been queued. More...

DBusMessage *	_dbus_message_loader_pop_message (DBusMessageLoader *loader)
	Pops a loaded message (passing ownership of the message to the caller). More...

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). More...

void	_dbus_message_loader_putback_message_link (DBusMessageLoader loader, DBusList link)
	Returns a popped message link, used to undo a pop. More...

dbus_bool_t	_dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
	Checks whether the loader is confused due to bad data. More...

DBusValidity	_dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
	Checks what kind of bad data confused the loader. More...

void	_dbus_message_loader_set_max_message_size (DBusMessageLoader *loader, long size)
	Sets the maximum size message we allow. More...

long	_dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
	Gets the maximum allowed message size in bytes. More...

void	_dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader, long n)
	Sets the maximum unix fds per message we allow. More...

long	_dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
	Gets the maximum allowed number of unix fds per message. More...

int	_dbus_message_loader_get_pending_fds_count (DBusMessageLoader *loader)
	Return how many file descriptors are pending in the loader. More...

void	_dbus_message_loader_set_pending_fds_function (DBusMessageLoader loader, void(callback)(void ), void data)
	Register a function to be called whenever the number of pending file descriptors in the loader change. More...

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. More...

void	dbus_message_free_data_slot (dbus_int32_t *slot_p)
	Deallocates a global ID for message data slots. More...

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. More...

void *	dbus_message_get_data (DBusMessage *message, dbus_int32_t slot)
	Retrieves data previously set with dbus_message_set_data(). More...

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. More...

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). More...

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. More...

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. More...

int	dbus_message_demarshal_bytes_needed (const char *buf, int len)
	Returns the number of bytes required to be in the buffer to demarshal a D-Bus message. More...

void	dbus_message_set_allow_interactive_authorization (DBusMessage *message, dbus_bool_t allow)
	Sets a flag indicating that the caller of the method is prepared to wait for interactive authorization to take place (for instance via Polkit) before the actual method is processed. More...

dbus_bool_t	dbus_message_get_allow_interactive_authorization (DBusMessage *message)
	Returns whether the flag controlled by dbus_message_set_allow_interactive_authorization() has been set. More...

DBusVariant *	_dbus_variant_read (DBusMessageIter *reader)
	Copy a single D-Bus message item from reader into a newly-allocated DBusVariant. More...

const char *	_dbus_variant_get_signature (DBusVariant *self)
	Return the signature of the item stored in self. More...

dbus_bool_t	_dbus_variant_write (DBusVariant self, DBusMessageIter writer)
	Copy the single D-Bus message item from self into writer. More...

int	_dbus_variant_get_length (DBusVariant *self)

const DBusString *	_dbus_variant_peek (DBusVariant *self)

void	_dbus_variant_free (DBusVariant *self)

Detailed Description

DBusMessage private implementation details.

The guts of DBusMessage and its methods.

Macro Definition Documentation

◆ _dbus_enable_message_cache

#define _dbus_enable_message_cache ( ) (TRUE)

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

◆ CHANGED_STAMP_BITS

#define CHANGED_STAMP_BITS 21

How many bits are in the changed_stamp used to validate iterators.

Definition at line 90 of file dbus-message-private.h.

◆ ensure_byte_order

#define ensure_byte_order ( message ) _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 218 of file dbus-message.c.

◆ INITIAL_LOADER_DATA_LEN

#define INITIAL_LOADER_DATA_LEN 32

The initial buffer size of the message loader.

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

◆ MAX_MESSAGE_CACHE_SIZE

#define MAX_MESSAGE_CACHE_SIZE 5

Avoid caching too many messages.

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

◆ MAX_MESSAGE_SIZE_TO_CACHE

#define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE

Avoid caching huge messages.

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

Typedef Documentation

◆ DBusMessageLoader

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.

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

◆ DBusMessageRealIter

typedef struct DBusMessageRealIter DBusMessageRealIter

typedef for internals of message iterator

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

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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

Function Documentation

◆ _dbus_message_add_counter()

dbus_bool_t _dbus_message_add_counter	(	DBusMessage *	message,
		DBusCounter *	counter
	)

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

This function may be called with locks held. As a result, the counter's notify function is not called; the caller is expected to either call _dbus_counter_notify() on the counter when they are no longer holding locks, or take the same action that would be taken by the notify function.

Parameters

message	the message
counter	the counter

Returns: FALSE if no memory

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

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

Referenced by _dbus_transport_queue_messages().

◆ _dbus_message_add_counter_link()

void _dbus_message_add_counter_link	(	DBusMessage *	message,
		DBusList *	link
	)

Adds a counter to be incremented immediately with the size/unix fds of this message, and decremented by the size/unix fds 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.

This function may be called with locks held. As a result, the counter's notify function is not called; the caller is expected to either call _dbus_counter_notify() on the counter when they are no longer holding locks, or take the same action that would be taken by the notify function.

Parameters

message	the message
link	link with counter as data

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

References _dbus_counter_adjust_size(), _dbus_counter_adjust_unix_fd(), _dbus_list_append_link(), DBusMessage::body, DBusMessage::counters, DBusList::data, DBusHeader::data, DBusMessage::header, NULL, and DBusMessage::size_counter_delta.

Referenced by _dbus_message_add_counter().

◆ _dbus_message_get_n_unix_fds()

unsigned int _dbus_message_get_n_unix_fds ( DBusMessage * message )

Gets the number of unix fds attached to this message.

Parameters

message the message

Returns: the number of file descriptors

Definition at line 40 of file dbus-message-util.c.

◆ _dbus_message_get_network_data()

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 231 of file dbus-message.c.

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

◆ _dbus_message_get_unix_fds()

void _dbus_message_get_unix_fds	(	DBusMessage *	message,
		const int **	fds,
		unsigned *	n_fds
	)

Gets the unix fds to be sent over the network for this message.

This function is guaranteed to always return the same data once a message is locked (with dbus_message_lock()).

Parameters

message	the message.
fds	return location of unix fd array
n_fds	return number of entries in array

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

References _dbus_assert, DBusMessage::locked, and NULL.

◆ _dbus_message_iter_get_args_valist()

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 826 of file dbus-message.c.

References _dbus_assert, _dbus_close(), _dbus_dup(), _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_INCONSISTENT_MESSAGE, DBUS_ERROR_INVALID_ARGS, DBUS_ERROR_NOT_SUPPORTED, 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_UNIX_FD, FALSE, DBusMessageRealIter::message, NULL, DBusMessageRealIter::reader, TRUE, DBusMessageRealIter::u, and DBusBasicValue::u32.

Referenced by dbus_message_get_args_valist().

◆ _dbus_message_loader_get_buffer()

void _dbus_message_loader_get_buffer	(	DBusMessageLoader *	loader,
		DBusString **	buffer,
		int *	max_to_read,
		dbus_bool_t *	may_read_fds
	)

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.

Parameters

loader	the message loader.
buffer	the buffer

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

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

Referenced by dbus_message_demarshal().

◆ _dbus_message_loader_get_corruption_reason()

DBusValidity _dbus_message_loader_get_corruption_reason ( DBusMessageLoader * loader )

Checks what kind of bad data confused the loader.

Parameters

loader the loader

Returns: why the loader is hosed, or DBUS_VALID if it isn't.

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

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

◆ _dbus_message_loader_get_is_corrupted()

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 4796 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().

◆ _dbus_message_loader_get_max_message_size()

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 4844 of file dbus-message.c.

References DBusMessageLoader::max_message_size.

Referenced by _dbus_transport_get_max_message_size().

◆ _dbus_message_loader_get_max_message_unix_fds()

long _dbus_message_loader_get_max_message_unix_fds ( DBusMessageLoader * loader )

Gets the maximum allowed number of unix fds per message.

Parameters

loader the loader

Returns: max unix fds

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

References DBusMessageLoader::max_message_unix_fds.

Referenced by _dbus_transport_get_max_message_unix_fds().

◆ _dbus_message_loader_get_pending_fds_count()

int _dbus_message_loader_get_pending_fds_count ( DBusMessageLoader * loader )

Return how many file descriptors are pending in the loader.

Parameters

loader the loader

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

Referenced by _dbus_transport_get_pending_fds_count().

◆ _dbus_message_loader_new()

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 4159 of file dbus-message.c.

References DBusMessageLoader::corrupted, DBusMessageLoader::corruption_reason, DBUS_MAXIMUM_MESSAGE_LENGTH, dbus_new0, DBUS_VALID, FALSE, DBusMessageLoader::max_message_size, DBusMessageLoader::max_message_unix_fds, NULL, and DBusMessageLoader::refcount.

Referenced by _dbus_transport_init_base(), and dbus_message_demarshal().

◆ _dbus_message_loader_peek_message()

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 4737 of file dbus-message.c.

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

◆ _dbus_message_loader_pop_message()

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 4754 of file dbus-message.c.

References _dbus_list_pop_first(), and DBusMessageLoader::messages.

Referenced by dbus_message_demarshal().

◆ _dbus_message_loader_pop_message_link()

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 4768 of file dbus-message.c.

References _dbus_list_pop_first_link(), and DBusMessageLoader::messages.

Referenced by _dbus_transport_queue_messages().

◆ _dbus_message_loader_putback_message_link()

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 4780 of file dbus-message.c.

References _dbus_list_prepend_link(), and DBusMessageLoader::messages.

Referenced by _dbus_transport_queue_messages().

◆ _dbus_message_loader_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.

Parameters

loader the loader.

Returns: TRUE if we had enough memory to finish.

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

References _dbus_assert, _dbus_header_have_message_untrusted(), DBusMessageLoader::corrupted, DBusMessageLoader::data, DBUS_MINIMUM_HEADER_SIZE, DBUS_VALID, and DBusMessageLoader::max_message_size.

Referenced by dbus_message_demarshal().

◆ _dbus_message_loader_ref()

DBusMessageLoader * _dbus_message_loader_ref ( DBusMessageLoader * loader )

Increments the reference count of the loader.

Parameters

loader the loader.

Returns: the loader

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

References DBusMessageLoader::refcount.

◆ _dbus_message_loader_return_buffer()

void _dbus_message_loader_return_buffer	(	DBusMessageLoader *	loader,
		DBusString *	buffer
	)

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.

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

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

Referenced by dbus_message_demarshal().

◆ _dbus_message_loader_set_max_message_size()

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 4825 of file dbus-message.c.

References DBUS_MAXIMUM_MESSAGE_LENGTH, and DBusMessageLoader::max_message_size.

Referenced by _dbus_transport_set_max_message_size().

◆ _dbus_message_loader_set_max_message_unix_fds()

void _dbus_message_loader_set_max_message_unix_fds	(	DBusMessageLoader *	loader,
		long	n
	)

Sets the maximum unix fds per message we allow.

Parameters

loader	the loader
n	the max number of unix fds in a message

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

References DBUS_MAXIMUM_MESSAGE_UNIX_FDS, and DBusMessageLoader::max_message_unix_fds.

Referenced by _dbus_transport_set_max_message_unix_fds().

◆ _dbus_message_loader_set_pending_fds_function()

void _dbus_message_loader_set_pending_fds_function	(	DBusMessageLoader *	loader,
		void()(void )	callback,
		void *	data
	)

Register a function to be called whenever the number of pending file descriptors in the loader change.

Parameters

loader	the loader
callback	the callback
data	the data for the callback

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

Referenced by _dbus_transport_set_pending_fds_function().

◆ _dbus_message_loader_unref()

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 4221 of file dbus-message.c.

References _dbus_list_clear_full(), _dbus_string_free(), DBusMessageLoader::data, dbus_free(), dbus_message_unref(), DBusMessageLoader::messages, and DBusMessageLoader::refcount.

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

◆ _dbus_message_remove_counter()

void _dbus_message_remove_counter	(	DBusMessage *	message,
		DBusCounter *	counter
	)

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

Parameters

message	the message
counter	the counter

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

References _dbus_assert, _dbus_counter_adjust_size(), _dbus_counter_adjust_unix_fd(), _dbus_counter_notify(), _dbus_counter_unref(), _dbus_list_find_last(), _dbus_list_remove_link(), DBusMessage::counters, NULL, and DBusMessage::size_counter_delta.

Referenced by _dbus_connection_message_sent_unlocked().

◆ _dbus_message_remove_unknown_fields()

dbus_bool_t _dbus_message_remove_unknown_fields ( DBusMessage * message )

Remove every header field not known to this version of dbus.

Parameters

message the message

Returns: FALSE if no memory

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

References _dbus_header_remove_unknown_fields(), and DBusMessage::header.

◆ _dbus_message_trace_ref()

void _dbus_message_trace_ref	(	DBusMessage *	message,
		int	old_refcount,
		int	new_refcount,
		const char *	why
	)

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

◆ _dbus_variant_free()

void _dbus_variant_free ( DBusVariant * self )

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

◆ _dbus_variant_get_length()

int _dbus_variant_get_length ( DBusVariant * self )

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

◆ _dbus_variant_get_signature()

const char * _dbus_variant_get_signature ( DBusVariant * self )

Return the signature of the item stored in self.

It is a single complete type.

Parameters

self	the variant

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

References _dbus_assert, and NULL.

◆ _dbus_variant_peek()

const DBusString * _dbus_variant_peek ( DBusVariant * self )

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

◆ _dbus_variant_read()

DBusVariant * _dbus_variant_read ( DBusMessageIter * reader )

Copy a single D-Bus message item from reader into a newly-allocated DBusVariant.

For example, if a message contains three string arguments, and reader points to the second string, the resulting DBusVariant will have signature DBUS_TYPE_STRING_AS_STRING and contain only that second string.

Parameters

reader An iterator over message items, pointing to one item to copy

Returns: The variant, or NULL if out of memory

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

References _dbus_assert, FALSE, DBusMessageRealIter::iter_type, and NULL.

◆ _dbus_variant_write()

dbus_bool_t _dbus_variant_write	(	DBusVariant *	self,
		DBusMessageIter *	writer
	)

Copy the single D-Bus message item from self into writer.

For example, if writer points into the body of an empty message and self has signature DBUS_TYPE_STRING_AS_STRING, then the message will have signature DBUS_TYPE_STRING_AS_STRING after this function returns

Parameters

self	the variant
writer	the place to write the contents of the variant

Returns: TRUE on success, FALSE if out of memory

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

References _dbus_assert, and NULL.

◆ dbus_message_allocate_data_slot()

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 4932 of file dbus-message.c.

References _dbus_data_slot_allocator_alloc().

◆ dbus_message_demarshal()

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 5155 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(), DBusMessageLoader::corruption_reason, DBUS_ERROR_INVALID_ARGS, dbus_set_error(), DBUS_VALIDITY_UNKNOWN_OOM_ERROR, and NULL.

◆ dbus_message_demarshal_bytes_needed()

int dbus_message_demarshal_bytes_needed	(	const char *	buf,
		int	len
	)

Returns the number of bytes required to be in the buffer to demarshal a D-Bus message.

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

Parameters

buf	data to be marshalled
len	the length of `buf`

Returns: -1 if there was no valid data to be demarshalled, 0 if there wasn't enough data to determine how much should be demarshalled. Otherwise returns the number of bytes to be demarshalled

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

References _dbus_assert, _dbus_header_have_message_untrusted(), _dbus_string_free(), _dbus_string_init_const_len(), DBUS_MAXIMUM_MESSAGE_LENGTH, DBUS_MINIMUM_HEADER_SIZE, and DBUS_VALID.

◆ dbus_message_free_data_slot()

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 4950 of file dbus-message.c.

References _dbus_data_slot_allocator_free().

◆ dbus_message_get_allow_interactive_authorization()

dbus_bool_t dbus_message_get_allow_interactive_authorization ( DBusMessage * message )

Returns whether the flag controlled by dbus_message_set_allow_interactive_authorization() has been set.

Parameters

message the message

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

References _dbus_header_get_flag(), DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION, FALSE, DBusMessage::header, and NULL.

◆ dbus_message_get_data()

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 5007 of file dbus-message.c.

References _dbus_data_slot_list_get(), and NULL.

◆ dbus_message_iter_init_closed()

void dbus_message_iter_init_closed ( DBusMessageIter * iter )

Initialize iter as if with DBUS_MESSAGE_ITER_INIT_CLOSED.

The only valid operation for such an iterator is dbus_message_iter_abandon_container_if_open(), which does nothing.

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

References NULL.

◆ dbus_message_lock()

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. This function may also called externally, for applications wrapping D-Bus in another protocol.

Parameters

message the message to lock.

Definition at line 419 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.

Referenced by dbus_message_marshal().

◆ dbus_message_marshal()

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 5093 of file dbus-message.c.

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

◆ dbus_message_set_allow_interactive_authorization()

void dbus_message_set_allow_interactive_authorization	(	DBusMessage *	message,
		dbus_bool_t	allow
	)

Sets a flag indicating that the caller of the method is prepared to wait for interactive authorization to take place (for instance via Polkit) before the actual method is processed.

The flag is FALSE by default; that is, by default the other end is expected to make any authorization decisions non-interactively and promptly. It may use the error DBUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED to signal that authorization failed, but could have succeeded if this flag had been used.

For messages whose type is not DBUS_MESSAGE_TYPE_METHOD_CALL, this flag is meaningless and should not be set.

On the protocol level this toggles DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION.

Parameters

message	the message
allow	TRUE if interactive authorization is acceptable

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

References _dbus_header_toggle_flag(), DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION, DBusMessage::header, DBusMessage::locked, and NULL.

◆ dbus_message_set_data()

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 4971 of file dbus-message.c.

References _dbus_data_slot_list_set(), FALSE, and NULL.

◆ dbus_message_set_serial()

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.

DBusConnection will automatically set the serial to an appropriate value when the message is sent; this function is only needed when encapsulating messages in another protocol, or otherwise bypassing DBusConnection.

Parameters

message	the message
serial	the serial

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

References _dbus_header_set_serial(), DBusMessage::header, DBusMessage::locked, and NULL.

◆ dbus_message_type_from_string()

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 5035 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.

◆ dbus_message_type_to_string()

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 5063 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.

Referenced by _dbus_connection_message_sent_unlocked().

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ _dbus_enable_message_cache

◆ CHANGED_STAMP_BITS

◆ ensure_byte_order

◆ INITIAL_LOADER_DATA_LEN

◆ MAX_MESSAGE_CACHE_SIZE

◆ MAX_MESSAGE_SIZE_TO_CACHE

Typedef Documentation

◆ DBusMessageLoader

◆ DBusMessageRealIter

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ _dbus_message_add_counter()

◆ _dbus_message_add_counter_link()

◆ _dbus_message_get_n_unix_fds()

◆ _dbus_message_get_network_data()

◆ _dbus_message_get_unix_fds()

◆ _dbus_message_iter_get_args_valist()

◆ _dbus_message_loader_get_buffer()

◆ _dbus_message_loader_get_corruption_reason()

◆ _dbus_message_loader_get_is_corrupted()

◆ _dbus_message_loader_get_max_message_size()

◆ _dbus_message_loader_get_max_message_unix_fds()

◆ _dbus_message_loader_get_pending_fds_count()

◆ _dbus_message_loader_new()

◆ _dbus_message_loader_peek_message()

◆ _dbus_message_loader_pop_message()

◆ _dbus_message_loader_pop_message_link()

◆ _dbus_message_loader_putback_message_link()

◆ _dbus_message_loader_queue_messages()

◆ _dbus_message_loader_ref()

◆ _dbus_message_loader_return_buffer()

◆ _dbus_message_loader_set_max_message_size()

◆ _dbus_message_loader_set_max_message_unix_fds()

◆ _dbus_message_loader_set_pending_fds_function()

◆ _dbus_message_loader_unref()

◆ _dbus_message_remove_counter()

◆ _dbus_message_remove_unknown_fields()

◆ _dbus_message_trace_ref()

◆ _dbus_variant_free()

◆ _dbus_variant_get_length()

◆ _dbus_variant_get_signature()

◆ _dbus_variant_peek()

◆ _dbus_variant_read()

◆ _dbus_variant_write()

◆ dbus_message_allocate_data_slot()

◆ dbus_message_demarshal()

◆ dbus_message_demarshal_bytes_needed()

◆ dbus_message_free_data_slot()

◆ dbus_message_get_allow_interactive_authorization()

◆ dbus_message_get_data()

◆ dbus_message_iter_init_closed()

◆ dbus_message_lock()

◆ dbus_message_marshal()

◆ dbus_message_set_allow_interactive_authorization()

◆ dbus_message_set_data()

◆ dbus_message_set_serial()

◆ dbus_message_type_from_string()

◆ dbus_message_type_to_string()