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  DBusMessage
 Internals of DBusMessage. More...

struct  DBusMessageLoader
 Implementation details of DBusMessageLoader. More...

struct  DBusMessageRealIter
 Internals of DBusMessageIter. More...

struct  HeaderField
 Cached information about a header field in the message. 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 + 4 + 1 + 8)
 The maximum number of bytes of overhead to append to a string (fieldcode + typecode + alignment + length + nul + headerpadding).

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

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


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


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

void _dbus_message_set_serial (DBusMessage *message, dbus_int32_t serial)
 Sets the serial number of a message. More...

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

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

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

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

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

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

void _dbus_message_lock (DBusMessage *message)
 Locks a message. 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)
 Gets the buffer to use for reading data from the network. More...

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

dbus_bool_t _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
 Converts buffered data into messages. 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...

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

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

dbus_bool_t _dbus_message_test (const char *test_data_dir)

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


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

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

References DBusMessage::body, DBusList::data, DBusMessage::header, DBusMessage::size_counter_delta, and DBusMessage::size_counters.

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

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

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

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

References DBusMessageLoader::corrupted.

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

References DBusMessageLoader::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 4763 of file dbus-message.c.

References DBusMessageLoader::data, DBusMessageLoader::max_message_size, and DBusMessageLoader::refcount.

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

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

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

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

References DBusMessageLoader::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 5592 of file dbus-message.c.

References DBusMessageLoader::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 5441 of file dbus-message.c.

References DBusMessageLoader::corrupted, DBusMessageLoader::data, and DBusMessageLoader::max_message_size.

DBusMessageLoader* _dbus_message_loader_ref DBusMessageLoader   loader
 

Increments the reference count of the loader.

Parameters:
loader  the loader.
Returns:
the loader

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

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

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

References DBusMessageLoader::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 4812 of file dbus-message.c.

References DBusMessageLoader::data, DBusMessageLoader::messages, and DBusMessageLoader::refcount.

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

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

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

References DBusMessage::size_counter_delta, and DBusMessage::size_counters.

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

References DBusMessage::byte_order, DBusMessage::client_serial, DBusMessage::header, and DBusMessage::locked.

dbus_bool_t _dbus_message_test const char *    test_data_dir
 

Unit test for DBusMessage.

Returns:
TRUE on success.

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

References DBusMessage::body, DBusMessage::client_serial, DBusMessage::header, DBusMessage::header_padding, DBusError::message, and DBusMessage::reply_serial.

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

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

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

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

References DBusMessage::reply_serial.

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

References DBusMessage::client_serial.

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

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

References DBusMessage::locked, and DBusMessage::reply_serial.

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


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15