adbus_Message Struct Reference

Container for parsed messages. More...

Data Fields
const char *	data
	Beginning of message data (must be 8 byte aligned).
size_t	size
	Size of message data.
const char *	argdata
	Beginning of argument data.
size_t	argsize
	Size of argument data.
adbus_MessageType	type
	Type of message.
uint8_t	flags
	Message flags.
uint32_t	serial
	Message serial - used to correlate method calls with replies.
const char *	signature
	Argument signature or NULL if not present.
size_t	signatureSize
	Length of adbus_Message::signature field.
const uint32_t *	replySerial
	Pointer to reply serial value of NULL if not present.
const char *	path
	Object path header field or NULL if not present.
size_t	pathSize
	Length of path field.
const char *	interface
	Interface header field or NULL if not present.
size_t	interfaceSize
	Length of interface field.
const char *	member
	Member header field or NULL if not present.
size_t	memberSize
	Length of member field.
const char *	error
	Error name header field or NULL if not present.
size_t	errorSize
	Length of error field.
const char *	destination
	Destination header field or NULL if not present.
size_t	destinationSize
	Length of destination field.
const char *	sender
	Sender header field or NULL if not present.
size_t	senderSize
	Length of sender field.
adbus_Argument *	arguments
	Array of unpacked arguments.
size_t	argumentsSize
	Size of arguments field.
Related Functions
(Note that these are not member functions.)
size_t	adbus_parse_size (const char *data, size_t size)
	Figures out the size of a message.
int	adbus_parse (adbus_Message *m, char *data, size_t size)
	Fills out an adbus_Message by parsing the data.
int	adbus_parseargs (adbus_Message *m)
	Parse the arguments in a message.
void	adbus_freeargs (adbus_Message *m)
	Frees the argument vector allocated by adbus_parse_args().
void	adbus_clonedata (adbus_Message *from, adbus_Message *to)
	Clones the message data in from into to.

---

Detailed Description

Container for parsed messages.

A message structure can be filled out by using adbus_parse() or it may be filled out manually. When filling out manually all fields except arguments are required to be set if they are in the message (otherwise they should be zero intialised). Most places that require arguments to be set should call adbus_parseargs() before using it.

Warning:

adbus_parseargs() allocates some space on the heap to store the arguments vector. Call adbus_freeargs() to free the arguments vector when finished using them.

For example to parse some incoming data and dispatch using adbus_conn_dispatch() (this is just a simple version of adbus_conn_parse()):

  // These initialised somewhere else
  static adbus_Buffer* buf;
  static adbus_Connect* connection;
  int ParseData(char* data, size_t sz)
  {
      // Copy the data into a buffer to ensure its 8 byte aligned
      adbus_buf_append(buf, data, sz);
      size_t msgsz = 0;
      while (1)
      {
          char* msgdata = adbus_buf_data(buf);
          size_t bufdata = adbus_buf_size(buf);
          msgsz = adbus_parse_size(msgdata, bufdata);
          // Need more data
          if (msgsz == 0 || msgsz > bufdata)
              return 0;
          
          adbus_Message m = {};
          
          // Check for parse errors
          if (adbus_parse(&m, msgdata, msgsz))
              return -1;

          // adbus_conn_dispatch() will return an error on a parse error
          // detected further down
          int ret = adbus_conn_dispatch(connection, &m);
          adbus_freeargs(&m);
          if (ret)
              return ret;
      }
  }

---

Friends And Related Function Documentation

void adbus_clonedata	(	adbus_Message *	from,
		adbus_Message *	to
	)			[related]

Clones the message data in from into to.

Afterwards the message needs to be freed via adbus_freedata.

int adbus_parse	(	adbus_Message *	m,
		char *	data,
		size_t	size
	)			[related]

Fills out an adbus_Message by parsing the data.

Parameters:

[in]	m	The message structure to fill out.
[in]	data	Data to parse. This must be 8 byte aligned.
[in]	size	The size of the message. This must be the size of the message exactly.

Parses a message and fills out the message structure. It will endian flip the data if it is not native (hence char* instead of const char*). The pointers in the message structure will point into the passed data.

Due to the 8 byte alignment the size normally needs to be known beforehand to copy the data into an 8 byte aligned buffer. adbus_parse_size() can be used to figure out the message size.

See also:

adbus_parse_size()

size_t adbus_parse_size	(	const char *	data,
		size_t	size
	)			[related]

Figures out the size of a message.

The data does not need to be aligned.

Returns:

The message size or 0 if there is insufficient data to figure out the message size.

int adbus_parseargs

(

adbus_Message *

m

)

[related]

Parse the arguments in a message.

This should be called after filling out the message struct using adbus_parse() or manually and will fill out the arguments and argumentsSize fields. These fields only tell you about string arguments and should only be used for matching match rules.

Warning:

The argument vector filled out in the message structure is allocated on the heap. You must use adbus_freeargs() after using the message to free this.

---

Field Documentation

adbus_Message::arguments

Array of unpacked arguments.

This should only be used for matching against match rules. For proper unpacking use adbus_Iterator.

---

The documentation for this struct was generated from the following files:

• include/c/adbus.h
• adbus/parse.c