Main Page | Modules | Data Structures | File List | Data Fields | Related Pages

DBusMessage implementation details
[D-BUS internal implementation details]

DBusMessage private implementation details. More...

Data Structures

struct  HeaderField
 Cached information about a header field in the message. More...

struct  DBusMessage
 Internals of DBusMessage. More...

struct  DBusMessageRealIter
 Internals of DBusMessageIter. More...

struct  DBusMessageLoader
 Implementation details of DBusMessageLoader. More...


Defines

#define BYTE_ORDER_OFFSET   0
 Offset to byte order from start of header.

#define TYPE_OFFSET   1
 Offset to type from start of header.

#define FLAGS_OFFSET   2
 Offset to flags from start of header.

#define VERSION_OFFSET   3
 Offset to version from start of header.

#define HEADER_LENGTH_OFFSET   4
 Offset to header length from start of header.

#define BODY_LENGTH_OFFSET   8
 Offset to body length from start of header.

#define CLIENT_SERIAL_OFFSET   12
 Offset to client serial from start of header.

#define MAX_BYTES_OVERHEAD_TO_APPEND_A_STRING   (1 + 1 + 3 + 1 + 8)
#define verify_header_fields(x)
#define MAX_SANE_MESSAGE_SIZE   (_DBUS_INT_MAX/16)
 The maximum sane message size.

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

#define DBUS_MINIMUM_HEADER_SIZE   16
 The smallest header size that can occur.


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_MESSAGE, DBUS_MESSAGE_ITER_TYPE_ARRAY, DBUS_MESSAGE_ITER_TYPE_DICT }

Functions

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_int32_t serial)
 Sets the serial number of a message.

dbus_bool_t dbus_message_set_reply_serial (DBusMessage *message, dbus_uint32_t reply_serial)
 Sets the reply serial of a message (the client serial of the message this is a reply to).

dbus_uint32_t dbus_message_get_serial (DBusMessage *message)
 Returns the serial of a message or 0 if none has been specified.

dbus_uint32_t dbus_message_get_reply_serial (DBusMessage *message)
 Returns the serial that the message is a reply to or 0 if none.

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.

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.


Detailed Description

DBusMessage private implementation details.

The guts of DBusMessage and its methods.


Define Documentation

#define DBUS_MINIMUM_HEADER_SIZE   16
 

The smallest header size that can occur.

(It won't be valid)

Definition at line 4877 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 4772 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 965 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 929 of file dbus-message.c.

References _dbus_counter_adjust(), _dbus_list_append_link(), _dbus_string_get_length(), DBusMessage::body, DBusList::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 156 of file dbus-message.c.

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

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.

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

Parameters:
loader the message loader.
buffer the buffer

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

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

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

References DBusMessageLoader::corrupted.

Referenced by _dbus_transport_queue_messages().

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

References _dbus_string_init(), _dbus_string_set_length(), DBusMessageLoader::data, dbus_free(), dbus_new0, INITIAL_LOADER_DATA_LEN, DBusMessageLoader::max_message_size, NULL, and DBusMessageLoader::refcount.

Referenced by _dbus_transport_init_base().

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

References _dbus_list_pop_first(), and DBusMessageLoader::messages.

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

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

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

References _dbus_assert, _dbus_string_get_const_data_len(), _dbus_string_get_length(), _dbus_unpack_uint32(), BYTE_ORDER_OFFSET, DBusMessageLoader::corrupted, DBusMessageLoader::data, dbus_uint32_t, FALSE, DBusMessageLoader::max_message_size, MAX_SANE_MESSAGE_SIZE, TRUE, TYPE_OFFSET, and VERSION_OFFSET.

Referenced by _dbus_transport_get_dispatch_status().

DBusMessageLoader* _dbus_message_loader_ref DBusMessageLoader loader  ) 
 

Increments the reference count of the loader.

Parameters:
loader the loader.
Returns:
the loader

Definition at line 4816 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 5220 of file dbus-message.c.

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

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

References DBusMessageLoader::max_message_size, and MAX_SANE_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 4830 of file dbus-message.c.

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

Referenced by _dbus_transport_finalize_base(), and _dbus_transport_init_base().

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

References _dbus_marshal_set_uint32(), _dbus_string_get_length(), DBusMessage::body, BODY_LENGTH_OFFSET, DBusMessage::byte_order, DBusMessage::header, HEADER_LENGTH_OFFSET, DBusMessage::locked, 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 989 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_int32_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 849 of file dbus-message.c.

References _dbus_assert, _dbus_marshal_set_uint32(), CLIENT_SERIAL_OFFSET, dbus_int32_t, dbus_message_get_serial(), and DBusMessage::locked.

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

References _dbus_data_slot_allocator_alloc(), _DBUS_LOCK_NAME, and dbus_int32_t.

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

References _dbus_data_slot_allocator_free(), and dbus_int32_t.

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

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

dbus_uint32_t dbus_message_get_reply_serial DBusMessage message  ) 
 

Returns the serial that the message is a reply to or 0 if none.

Parameters:
message the message
Returns:
the reply serial

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

References DBusMessage::reply_serial.

Referenced by _dbus_connection_queue_received_message_link(), _dbus_pending_call_complete_and_unlock(), and dbus_connection_dispatch().

dbus_uint32_t dbus_message_get_serial DBusMessage message  ) 
 

Returns the serial of a message or 0 if none has been specified.

The message's serial number is provided by the application sending the message and is used to identify replies to this message. All messages received on a connection will have a serial, but messages you haven't sent yet may return 0.

Parameters:
message the message
Returns:
the client serial

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

References DBusMessage::client_serial.

Referenced by _dbus_message_set_serial(), dbus_connection_send_with_reply(), dbus_message_new_error(), and dbus_message_new_method_return().

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

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

dbus_bool_t dbus_message_set_reply_serial DBusMessage message,
dbus_uint32_t  reply_serial
 

Sets the reply serial of a message (the client serial of the message this is a reply to).

Parameters:
message the message
reply_serial the client serial
Returns:
FALSE if not enough memory

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

References _dbus_assert, dbus_uint32_t, FALSE, DBusMessage::locked, DBusMessage::reply_serial, and TRUE.

Referenced by dbus_message_new_error(), and dbus_message_new_method_return().

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


Generated on Sun Mar 21 03:52:07 2004 for D-BUS by doxygen 1.3.6-20040222