adbus_MsgFactory Struct Reference

Packs up messages for sending. More...

Related Functions
(Note that these are not member functions.)
adbus_State *	adbus_state_new (void)
	Creates a new state object.
adbus_MsgFactory *	adbus_msg_new (void)
	Creates a new message factory.
void	adbus_msg_free (adbus_MsgFactory *m)
	Frees a message factory.
void	adbus_msg_reset (adbus_MsgFactory *m)
	Resets the message factory for reuse.
int	adbus_msg_build (adbus_MsgFactory *m, adbus_Message *msg)
	Builds the message and sets the fields in the message struct.
int	adbus_msg_send (adbus_MsgFactory *m, adbus_Connection *c)
	Builds and then sends a message.
const char *	adbus_msg_path (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the object path header field.
const char *	adbus_msg_interface (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the interface header field.
const char *	adbus_msg_sender (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the sender header field.
const char *	adbus_msg_destination (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the destination header field.
const char *	adbus_msg_member (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the member header field.
const char *	adbus_msg_error (const adbus_MsgFactory *m, size_t *len)
	Returns the current value of the error name header field.
adbus_MessageType	adbus_msg_type (const adbus_MsgFactory *m)
	Returns the current value of the message type field.
uint8_t	adbus_msg_flags (const adbus_MsgFactory *m)
	Returns the current value of the message type field.
int64_t	adbus_msg_serial (const adbus_MsgFactory *m)
	Returns the current value of the serial field.
adbus_Bool	adbus_msg_reply (const adbus_MsgFactory *m, uint32_t *serial)
	Returns whether the message has a reply serial and the reply serial itself.
void	adbus_msg_settype (adbus_MsgFactory *m, adbus_MessageType type)
	Sets the message type.
void	adbus_msg_setserial (adbus_MsgFactory *m, uint32_t serial)
	Sets the message serial.
void	adbus_msg_setflags (adbus_MsgFactory *m, uint8_t flags)
	Sets the message flags.
void	adbus_msg_setreply (adbus_MsgFactory *m, uint32_t reply)
	Sets the message reply serial.
void	adbus_msg_setpath (adbus_MsgFactory *m, const char *path, int size)
	Sets the message object path field.
void	adbus_msg_setinterface (adbus_MsgFactory *m, const char *interface, int size)
	Sets the message interface field.
void	adbus_msg_setmember (adbus_MsgFactory *m, const char *member, int size)
	Sets the message member field.
void	adbus_msg_seterror (adbus_MsgFactory *m, const char *error, int size)
	Sets the message error name field.
void	adbus_msg_setdestination (adbus_MsgFactory *m, const char *destination, int size)
	Sets the message destination field.
void	adbus_msg_setsender (adbus_MsgFactory *m, const char *sender, int size)
	Sets the message sender field.
adbus_Buffer *	adbus_msg_argbuffer (adbus_MsgFactory *m)
	Returns the message argument buffer.
	adbus_msg_appendsig(m, t, s)
	Appends to the argument signature (see adbus_buf_appendsig()).
	adbus_msg_setsig(m, t, s)
	Sets the argument signature (see adbus_buf_setsig()).
	adbus_msg_append(m, d, s)
	Appends argument data (see adbus_buf_append()).
	adbus_msg_end(m)
	Finalises argument data (see adbus_buf_end()).
	adbus_msg_bool(m, v)
	Appends a boolean to the argument data (see adbus_buf_bool()).
	adbus_msg_u8(m, v)
	Appends a uint8_t to the argument data (see adbus_buf_u8()).
	adbus_msg_i16(m, v)
	Appends a int16_t to the argument data (see adbus_buf_i16()).
	adbus_msg_u16(m, v)
	Appends a uint16_t to the argument data (see adbus_buf_u16()).
	adbus_msg_i32(m, v)
	Appends a int32_t to the argument data (see adbus_buf_i32()).
	adbus_msg_u32(m, v)
	Appends a uint32_t to the argument data (see adbus_buf_u32()).
	adbus_msg_i64(m, v)
	Appends a int64_t to the argument data (see adbus_buf_i64()).
	adbus_msg_u64(m, v)
	Appends a uint64_t to the argument data (see adbus_buf_u64()).
	adbus_msg_double(m, v)
	Appends a double to the argument data (see adbus_buf_double()).
	adbus_msg_string(m, v, s)
	Appends a string to the argument data (see adbus_buf_string()).
	adbus_msg_objectpath(m, v, s)
	Appends an object path to the argument data (see adbus_buf_objectpath()).
	adbus_msg_beginarray(m, a)
	Begins an array scope in the argument data (see adbus_buf_beginarray()).
	adbus_msg_arrayentry(m, a)
	Begins an array entry in the argument data (see adbus_buf_arrayentry()).
	adbus_msg_endarray(m, a)
	Ends an array scope in the argument data (see adbus_buf_endarray()).
	adbus_msg_beginstruct(m)
	Begins a struct array scope in the argument data (see adbus_buf_beginstruct()).
	adbus_msg_endstruct(m)
	Ends a struct array scope in the argument data (see adbus_buf_endstruct()).
	adbus_msg_begindictentry(m)
	Begins a dict entry scope in the argument data (see adbus_buf_begindictentry()).
	adbus_msg_enddictentry(m)
	Ends a dict entry scope in the argument data (see adbus_buf_enddictentry()).
	adbus_msg_beginvariant(m, v, t, s)
	Begins a variant scope in the argument data (see adbus_buf_beginvariant()).
	adbus_msg_endvariant(m, v)
	Ends a variant scope in the argument data (see adbus_buf_endvariant()).

---

Detailed Description

Packs up messages for sending.

The general workflow is:

1. Setup all of the various header fields
2. Add arguments
3. Build a message into a message struct

Steps 1 and 2 can be intermixed.

After that you can immediately send it off using adbus_conn_send() or with adbus_msg_send() (this also builds the message) or clone the data to send it later.

Warning:

After adbus_msg_build() the pointers in the message struct point into the factories buffers so it should be used immediately (or the data cloned) before calling any further factory functions.

For example to send a method call to request the service "com.example":

  // Initialised elsewhere
  static adbus_MsgFactory* msg;
  static adbus_Connection* connection;

  adbus_msg_clear(msg);

  // Setting up the header
  adbus_msg_settype(msg, ADBUS_MSG_METHOD);
  adbus_msg_setflags(msg, ADBUS_MSG_NO_REPLY);
  adbus_msg_setserial(msg, adbus_conn_serial(connection));
  adbus_msg_setdestination(msg, "org.freedesktop.DBus", -1);
  adbus_msg_setpath(msg, "/org/freedesktop/DBus", -1);
  adbus_msg_setinterface(msg, "org.freedesktop.DBus", -1);
  adbus_msg_setmember(msg, "RequestName", -1);

  // Adding the arguments
  adbus_msg_setsig(msg, "su", -1);
  adbus_msg_string(msg, "com.example", -1);
  adbus_msg_u32(msg, 0);

  // Send the message
  adbus_conn_send(msg, connection);

To clone and send the message on another thread:

  adbus_Message* m = (adbus_Message*) calloc(sizeof(adbus_Message), 1);
  adbus_msg_build(msg, m);
  adbus_clonedata(m);
  SendToOtherThread(m);

  // .... on the other thread
  void ReceiveMessage(adbus_Message* m)
  {
      adbus_conn_send(connection, m);
      adbus_freedata(m);
      free(m);
  }

---

Friends And Related Function Documentation

adbus_Buffer * adbus_msg_argbuffer

(

adbus_MsgFactory *

m

)

[related]

Returns the message argument buffer.

This should only be used whilst building a message to append arguments. After the message is built it may not be valid.

If you are directly adding arguments,it is better to use the adbus_msg_ family of functions (eg adbus_msg_bool()). This is exported for use by general purpose serialisers that convert from a different typing scheme.

int adbus_msg_build	(	adbus_MsgFactory *	m,
		adbus_Message *	msg
	)			[related]

Builds the message and sets the fields in the message struct.

Parameters:

[in]	m	The message factory
[in]	msg	A zero initialised message struct to fill out

Returns:

0 on success

non zero on error

This will not fill out the arguments and argumentsSize fields.

Will assert if the required header fields for the given message type are not set.

Warning:

The pointers set in the message struct point into the message factory buffers. So any changes to the factory may invalidate the message struct.

const char * adbus_msg_destination	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the destination header field.

Returns:

NULL if the field is not set

const char * adbus_msg_error	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the error name header field.

Returns:

NULL if the field is not set

const char * adbus_msg_interface	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the interface header field.

Returns:

NULL if the field is not set

const char * adbus_msg_member	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the member header field.

Returns:

NULL if the field is not set

const char * adbus_msg_path	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the object path header field.

Returns:

NULL if the field is not set

adbus_Bool adbus_msg_reply	(	const adbus_MsgFactory *	m,
		uint32_t *	serial
	)			[related]

Returns whether the message has a reply serial and the reply serial itself.

Returns:

1 if the message has a reply serial (and then serial will be set to the reply serial)

const char * adbus_msg_sender	(	const adbus_MsgFactory *	m,
		size_t *	len
	)			[related]

Returns the current value of the sender header field.

Returns:

NULL if the field is not set

void adbus_msg_setserial	(	adbus_MsgFactory *	m,
		uint32_t	serial
	)			[related]

Sets the message serial.

The message serial should be unique for the connection. These can be generated from adbus_conn_serial().

See also:

adbus_conn_serial()

---

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

• adbus/message.c
• include/c/adbus.h
• adbus/state.c