D-Bus  1.9.0
Data Structures | Macros | Typedefs | Enumerations | Functions
DBusMessage 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...
 

Macros

#define CHANGED_STAMP_BITS   21
 How many bits are in the changed_stamp used to validate iterators.
 
#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.
 
#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. More...
 

Typedefs

typedef struct DBusMessageRealIter DBusMessageRealIter
 typedef for internals of message iterator
 
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_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...
 
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...
 
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...
 
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)
 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_get_unix_fds (DBusMessageLoader *loader, int **fds, unsigned *max_n_fds)
 Gets the buffer to use for reading unix fds from the network. More...
 
void _dbus_message_loader_return_unix_fds (DBusMessageLoader *loader, int *fds, unsigned n_fds)
 Returns a buffer obtained from _dbus_message_loader_get_unix_fds(). 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...
 
DBusMessagedbus_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...
 

Detailed Description

DBusMessage private implementation details.

The guts of DBusMessage and its methods.

Macro Definition Documentation

#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 195 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 3854 of file dbus-message.c.

Referenced by _dbus_message_loader_new().

Typedef Documentation

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 48 of file dbus-message-internal.h.

Function Documentation

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
messagethe message
counterthe counter
Returns
FALSE if no memory

Definition at line 329 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().

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
messagethe message
linklink with counter as data

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

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

Referenced by _dbus_message_add_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
messagethe message.
headerreturn location for message header data.
bodyreturn location for message body data.

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

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

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
messagethe message.
fdsreturn location of unix fd array
n_fdsreturn number of entries in array

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

References _dbus_assert, DBusMessage::locked, and NULL.

dbus_bool_t _dbus_message_iter_get_args_valist ( DBusMessageIter iter,
DBusError error,
int  first_arg_type,
va_list  var_args 
)
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
loaderthe message loader.
bufferthe buffer

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

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

Referenced by dbus_message_demarshal().

DBusValidity _dbus_message_loader_get_corruption_reason ( DBusMessageLoader loader)

Checks what kind of bad data confused the loader.

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

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

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

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
loaderthe loader
Returns
TRUE if the loader is hosed.

Definition at line 4424 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
loaderthe loader
Returns
max size in bytes

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

References DBusMessageLoader::max_message_size.

Referenced by _dbus_transport_get_max_message_size().

long _dbus_message_loader_get_max_message_unix_fds ( DBusMessageLoader loader)

Gets the maximum allowed number of unix fds per message.

Parameters
loaderthe loader
Returns
max unix fds

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

References DBusMessageLoader::max_message_unix_fds.

Referenced by _dbus_transport_get_max_message_unix_fds().

int _dbus_message_loader_get_pending_fds_count ( DBusMessageLoader loader)

Return how many file descriptors are pending in the loader.

Parameters
loaderthe loader

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

Referenced by _dbus_transport_get_pending_fds_count().

dbus_bool_t _dbus_message_loader_get_unix_fds ( DBusMessageLoader loader,
int **  fds,
unsigned *  max_n_fds 
)

Gets the buffer to use for reading unix fds from the network.

This works similar to _dbus_message_loader_get_buffer()

Parameters
loaderthe message loader.
fdsthe array to read fds into
max_n_fdshow many fds to read at most
Returns
TRUE on success, FALSE on OOM

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

References _dbus_assert, _dbus_assert_not_reached, dbus_realloc(), FALSE, DBusMessageLoader::max_message_unix_fds, and TRUE.

DBusMessageLoader* _dbus_message_loader_new ( void  )
DBusMessage* _dbus_message_loader_peek_message ( DBusMessageLoader loader)

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

Parameters
loaderthe loader.
Returns
the next message, or NULL if none.

Definition at line 4365 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
loaderthe loader.
Returns
the next message, or NULL if none.

Definition at line 4382 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
loaderthe loader.
Returns
the next message link, or NULL if none.

Definition at line 4396 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
loaderthe loader
linkthe link with a message in it

Definition at line 4408 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
loaderthe loader.
Returns
TRUE if we had enough memory to finish.

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

References _dbus_assert, _dbus_header_have_message_untrusted(), _dbus_list_find_last(), _dbus_string_get_length(), DBusMessageLoader::corrupted, DBusMessageLoader::corruption_reason, DBusMessageLoader::data, dbus_message_unref(), DBUS_MINIMUM_HEADER_SIZE, DBUS_VALID, FALSE, DBusMessageLoader::max_message_size, DBusMessageLoader::messages, 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
loaderthe loader.
Returns
the loader

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

References DBusMessageLoader::refcount.

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
loaderthe loader.
bufferthe buffer.

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

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

Referenced by dbus_message_demarshal().

void _dbus_message_loader_return_unix_fds ( DBusMessageLoader loader,
int *  fds,
unsigned  n_fds 
)

Returns a buffer obtained from _dbus_message_loader_get_unix_fds().

This works similar to _dbus_message_loader_return_buffer()

Parameters
loaderthe message loader.
fdsthe array fds were read into
n_fdshow many fds were read

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

References _dbus_assert, _dbus_assert_not_reached, and FALSE.

void _dbus_message_loader_set_max_message_size ( DBusMessageLoader loader,
long  size 
)

Sets the maximum size message we allow.

Parameters
loaderthe loader
sizethe max message size in bytes

Definition at line 4453 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_set_max_message_unix_fds ( DBusMessageLoader loader,
long  n 
)

Sets the maximum unix fds per message we allow.

Parameters
loaderthe loader
nthe max number of unix fds in a message

Definition at line 4484 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().

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
loaderthe loader
callbackthe callback
datathe data for the callback

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

Referenced by _dbus_transport_set_pending_fds_function().

void _dbus_message_loader_unref ( DBusMessageLoader loader)

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

Parameters
loaderthe loader.

Definition at line 3925 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_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
messagethe message
counterthe counter

Definition at line 352 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_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_paddress of a global variable storing the slot
Returns
FALSE on failure (no memory)

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

References _dbus_data_slot_allocator_alloc().

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
strthe marshalled DBusMessage
lenthe length of str
errorthe location to save errors to
Returns
NULL if there was an error

Definition at line 4783 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(), and NULL.

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
bufdata to be marshalled
lenthe 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 4841 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.

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_paddress storing the slot to deallocate

Definition at line 4578 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
messagethe message
slotthe slot to get data from
Returns
the data, or NULL if not found

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

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

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
messagethe message to lock.

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

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

Referenced by 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
msgthe DBusMessage
marshalled_data_pthe location to save the marshalled form to
len_pthe location to save the length of the marshalled form to
Returns
FALSE if there was not enough memory

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

References _dbus_string_copy(), _dbus_string_free(), _dbus_string_get_length(), _dbus_string_init(), _dbus_string_steal_data(), DBusMessage::body, DBusHeader::data, dbus_message_lock(), FALSE, DBusMessage::header, DBusMessage::locked, 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
messagethe message
slotthe slot number
datathe data to store
free_data_funcfinalizer function for the data
Returns
TRUE if there was enough memory to store the data

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

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

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
messagethe message
serialthe serial

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

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

Referenced by dbus_connection_send_with_reply().

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.

1 "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
2 "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
3 "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4 "error" -> DBUS_MESSAGE_TYPE_ERROR
5 anything else -> DBUS_MESSAGE_TYPE_INVALID

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

1 DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
2 DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
3 DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4 DBUS_MESSAGE_TYPE_ERROR -> "error"
5 DBUS_MESSAGE_TYPE_INVALID -> "invalid"

Definition at line 4691 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(), _dbus_connection_queue_received_message_link(), and dbus_connection_dispatch().