adbus_Buffer Struct Reference

General purpose buffer and means to serialise dbus data with an associated signature. More...

Related Functions
(Note that these are not member functions.)
adbus_Buffer *	adbus_buf_new ()
	Creates a new buffer.
void	adbus_buf_free (adbus_Buffer *b)
	Frees a buffer.
char *	adbus_buf_data (const adbus_Buffer *b)
	Returns the current data in the buffer.
size_t	adbus_buf_size (const adbus_Buffer *b)
	Returns the size of the data in the buffer.
char *	adbus_buf_release (adbus_Buffer *b)
	Releases the internal buffer and returns it.
void	adbus_buf_reset (adbus_Buffer *b)
	Clears the internal buffer.
const char *	adbus_buf_sig (const adbus_Buffer *b, size_t *size)
	Returns the current signature.
const char *	adbus_buf_signext (const adbus_Buffer *b, size_t *size)
	Returns the tracked point in the signature.
void	adbus_buf_setsig (adbus_Buffer *b, const char *sig, int size)
	Sets the buffer signature.
void	adbus_buf_appendsig (adbus_Buffer *b, const char *sig, int size)
	Appends to the buffer signature.
void	adbus_buf_reserve (adbus_Buffer *b, size_t sz)
	Reserves a specified min amount of room in the buffer.
void	adbus_buf_remove (adbus_Buffer *b, size_t off, size_t num)
	Removes a chunk of data from the buffer.
void	adbus_buf_append (adbus_Buffer *b, const char *data, size_t sz)
	Appends a chunk of data to the buffer.
const char *	adbus_buf_line (adbus_Buffer *b, size_t *sz)
	Returns the next newline terminated line at the start of the buffer.
char *	adbus_buf_recvbuf (adbus_Buffer *b, size_t len)
	Reserves a buffer to directly append data.
void	adbus_buf_recvd (adbus_Buffer *b, size_t len, adbus_ssize_t recvd)
	Clears out the extra space not used by a adbus_buf_recvbuf().
void	adbus_buf_end (adbus_Buffer *b)
	Called to end a series of serialised arguments.
void	adbus_buf_bool (adbus_Buffer *b, adbus_Bool v)
	Serialises a boolean (dbus sig "b").
void	adbus_buf_u8 (adbus_Buffer *b, uint8_t v)
	Serialises a uint8_t (dbus sig "y").
void	adbus_buf_i16 (adbus_Buffer *b, int16_t v)
	Serialises a int16_t (dbus sig "n").
void	adbus_buf_u16 (adbus_Buffer *b, uint16_t v)
	Serialises a uint16_t (dbus sig "q").
void	adbus_buf_i32 (adbus_Buffer *b, int32_t v)
	Serialises a int32_t (dbus sig "i").
void	adbus_buf_u32 (adbus_Buffer *b, uint32_t v)
	Serialises a uint32_t (dbus sig "u").
void	adbus_buf_i64 (adbus_Buffer *b, int64_t v)
	Serialises a int64_t (dbus sig "x").
void	adbus_buf_u64 (adbus_Buffer *b, uint64_t v)
	Serialises a uint64_t (dbus sig "t").
void	adbus_buf_double (adbus_Buffer *b, double v)
	Serialises a double (dbus sig "d").
void	adbus_buf_string (adbus_Buffer *b, const char *str, int size)
	Serialises a string (dbus sig "s").
void	adbus_buf_objectpath (adbus_Buffer *b, const char *str, int size)
	Serialises an object path (dbus sig "o").
void	adbus_buf_signature (adbus_Buffer *b, const char *str, int size)
	Serialises a signature (dbus sig "g").
void	adbus_buf_beginvariant (adbus_Buffer *b, adbus_BufVariant *v, const char *sig, int size)
	Begins a variant scope (dbus sig "v").
void	adbus_buf_endvariant (adbus_Buffer *b, adbus_BufVariant *v)
	Ends a variant scope (dbus sig "v").
void	adbus_buf_beginarray (adbus_Buffer *b, adbus_BufArray *a)
	Begins an array scope (dbus sig "a").
void	adbus_buf_arrayentry (adbus_Buffer *b, adbus_BufArray *a)
	Begins an array entry (dbus sig "a").
void	adbus_buf_endarray (adbus_Buffer *b, adbus_BufArray *a)
	Ends an array scope (dbus sig "a").
void	adbus_buf_begindictentry (adbus_Buffer *b)
	Begins a dict entry (dbus sig "{").
void	adbus_buf_enddictentry (adbus_Buffer *b)
	Ends a dict entry (dbus sig "}").
void	adbus_buf_beginstruct (adbus_Buffer *b)
	Begins a struct (dbus sig "(").
void	adbus_buf_endstruct (adbus_Buffer *b)
	Ends a struct (dbus sig ")").
int	adbus_flip_value (char **data, size_t *size, const char **sig)
	Endian flips a single complete type.
int	adbus_flip_data (char *data, size_t size, const char *sig)
	Endian flips the entire buffer.

---

Detailed Description

General purpose buffer and means to serialise dbus data with an associated signature.

Using as a General Buffer

When being used as a general buffer data can be appended by using adbus_buf_append() or adbus_buf_recvbuf(); removed by using adbus_buf_remove(), adbus_buf_release(), or adbus_buf_reset(); and parsed with adbus_buf_line().

Serialising DBus Data

When being used for serialising dbus arguments, the signature must be set first with adbus_buf_setsig() or adbus_buf_appendsig() and then data can be serialised using the various adbus_buf_bool() etc functions.

The serialising functions all track the supplied signature and assert when the wrong serialise function is used. This tracked signature can then be pulled out via adbus_buf_signext(). This is useful when serialising variant or typeless data.

The dbus data types which are scoped (array, dict entries, structs and variants) have a begin and end function and if needed use a struct in the calling code to maintain their scoped data.

Arrays

Array scopes are special in that multiple array entries can be added in an array. These entries can be added by either calling adbus_buf_arrayentry() before each entry or by appending the entire array data via adbus_buf_append().

Warning:

Array data appended using adbus_buf_append() must have the correct alignment and have zero initialised padding.

Using adbus_buf_arrayentry() to serialise "ai" (an array of int32s):

  uint32_t data[] = {1, 2, 3};
  adbus_Array a;
  adbus_buf_reset(buf);
  adbus_buf_setsig(buf, "ai");
  adbus_buf_beginarray(buf, &a);
  for (int i = 0; i < 3; i++)
  {
      adbus_buf_arrayentry(buf, &a);
      adbus_buf_u32(buf, data[i]);
  }
  adbus_buf_endarray(buf, &a);

Or equivalently using adbus_buf_append():

  uint32_t data[] = {1, 2, 3};
  adbus_Array a;
  adbus_buf_reset(buf);
  adbus_buf_setsig(buf, "ai");
  adbus_buf_beginarray(buf, &a);
  adbus_buf_append(buf, data, sizeof(data));
  adbus_buf_endarray(buf, &a);

Dict Entries

Dict Entries can only be used as a scope directly inside an array. Thus the signature will always look like a{...}. The adbus_buf_begindictentry() call should occur after the adbus_buf_arrayentry().

For example to serialise "a{is}" (a map of int32 to string):

  typedef std::map<int, std::string> Map;
  Map map;
  adbus_Array a;
  adbus_buf_reset(buf);
  adbus_buf_setsig(buf, "a{is}");
  adbus_buf_beginarray(buf, &a);
  for (Map::const_iterator ii = map.begin(); ii != map.end(); ++ii)
  {
      adbus_buf_arrayentry(buf, &a);
      adbus_buf_begindictentry(buf);
      adbus_buf_i32(buf, ii->first);
      adbus_buf_string(buf, ii->second.c_str(), -1);
      adbus_buf_enddictentry(buf);
  }
  adbus_buf_endarray(buf, &a);

Structs

Structs are fairly straight forward. They simply have a begin and end function with no scoped data.

For example to serialise "(iis)" (a struct containing 2 int32s and a string):

  adbus_buf_reset(buf);
  adbus_buf_setsig(buf, "(iis)");
  adbus_buf_beginstruct(buf);
  adbus_buf_i32(buf, first_number);
  adbus_buf_i32(buf, second_number);
  adbus_buf_string(buf, string, -1);
  adbus_buf_endstruct(buf);

Variants

Variants have a scoped struct to hold the original signature value and a begin function which takes the signature of the variant data.

For example to serialise "v" with a variant signature of "s" (string):

  adbus_Variant v;
  adbus_buf_reset(buf);
  adbus_buf_setsig(buf, "v");
  adbus_buf_beginvariant(buf, &v, "s", -1);
  adbus_buf_string(buf, string, -1);
  adbus_buf_endvariant(buf, &v);

---

Friends And Related Function Documentation

const char * adbus_buf_line	(	adbus_Buffer *	b,
		size_t *	sz
	)			[related]

Returns the next newline terminated line at the start of the buffer.

Parameters:

[in]	b	Buffer to work on
[out]	sz	Length of the returned line.

This is mainly used for SASL auth protocol which is line based.

Warning:

The returned line will not be null terminated. Instead use the size out param to determine its size.

Returns:

NULL when there is no complete next line

char * adbus_buf_recvbuf	(	adbus_Buffer *	b,
		size_t	len
	)			[related]

Reserves a buffer to directly append data.

Parameters:

[in]	b	Buffer to work on
[in]	len	Minimum length of returned buffer.

This is most commonly used for getting a pointer to hand to recv style functions which write directly into the end of the provided buffer.

Warning:

You must call adbus_buf_recvd after receiving data to indicate how much was actually received before calling any other functions on the buffer.

See also:

adbus_buf_recvd

void adbus_buf_recvd	(	adbus_Buffer *	b,
		size_t	len,
		adbus_ssize_t	recvd
	)			[related]

Clears out the extra space not used by a adbus_buf_recvbuf().

Parameters:

[in]	b	Buffer to work on
[in]	len	Length supplied to adbus_buf_recvbuf().
[in]	recvd	Actual amount of data received.

This should be called after receiving data into a buffer gotten via adbus_buf_recvbuf().

See also:

adbus_buf_recvbuf

char * adbus_buf_release

(

adbus_Buffer *

b

)

[related]

Releases the internal buffer and returns it.

After releasing the internal buffer, the user can do as they please with it, but must free it themselves. Note that since this will release the internal buffer, you will want to get the buffer size before releasing.

Warning:

To free the buffer you must use the same version of free as the library itself. For this reason use of this function is discouraged.

void adbus_buf_reserve	(	adbus_Buffer *	b,
		size_t	sz
	)			[related]

Reserves a specified min amount of room in the buffer.

This should only be used as a hint when the amount of room needed is known before adding the data. To actually reserve room at the end of the buffer to then right directly into use adbus_buf_recvbuf and adbus_buf_recvd.

See also:

adbus_buf_recvbuf, adbus_buf_recvd

void adbus_buf_reset

(

adbus_Buffer *

b

)

[related]

Clears the internal buffer.

This does not free the internal buffer and thus is much better to use if you want to reuse the buffer than freeing and newing a new buffer.

A common idiom is to simply clear the buffer right before using it, but not bothering to clear it after you are finished using it.

const char * adbus_buf_signext	(	const adbus_Buffer *	b,
		size_t *	size
	)			[related]

Returns the tracked point in the signature.

As data is serialised into the buffer, the serialise functions will track along the signature. This returns the current point and thus the next expected field.

This can be very useful for binding to dynamic languages as you can use the buffer to track the required serialised signature, and then call signext to figure out which serialise function to call next.

---

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

• adbus/rbuffer.c
• adbus/riterator.c