Bag

User defined key-value maps with fast serialization. More...

Typedefs
typedef int	reme_bag_t
	Handle referencing a bag object. More...
typedef int	reme_bag_builder_t
	Handle referencing a bag builder object. More...
reme_error_t	reme_bag_create (reme_context_t c, reme_bag_t *b)
	Create a bag. More...
reme_error_t	reme_bag_destroy (reme_context_t c, reme_bag_t *b)
	Destroy a previously created bag object. More...
reme_error_t	reme_bag_has_key (reme_context_t c, reme_bag_t b, const char *key, bool *available)
	Test if a certain key is present in the map. More...
reme_error_t	reme_bag_get_int (reme_context_t c, reme_bag_t b, const char *key, int *value)
	Read a value. More...
reme_error_t	reme_bag_get_real (reme_context_t c, reme_bag_t b, const char *key, float *value)
	Read a value. More...
reme_error_t	reme_bag_get_bool (reme_context_t c, reme_bag_t b, const char *key, bool *value)
	Read a value. More...
reme_error_t	reme_bag_get_string (reme_context_t c, reme_bag_t b, const char *key, const char **value)
	Read a value. More...
reme_error_t	reme_bag_get_bytes (reme_context_t c, reme_bag_t b, const char *key, const void **value, int *length)
	Read a value. More...
reme_error_t	reme_bag_get_image (reme_context_t c, reme_bag_t b, const char *key, reme_image_t value)
	Read a value. More...
reme_error_t	reme_bag_get_sensor_config (reme_context_t c, reme_bag_t b, const char *key, reme_sensor_t s)
	Read a value. More...
reme_error_t	reme_bag_get_transform (reme_context_t c, reme_bag_t b, const char *key, const float **values)
	Read a value. More...
reme_error_t	reme_bag_get_surface (reme_context_t c, reme_bag_t b, const char *key, reme_surface_t s)
	Read a value. More...
reme_error_t	reme_bag_builder_create (reme_context_t c, reme_bag_builder_t *bb)
	Create a bag builder. More...
reme_error_t	reme_bag_builder_destroy (reme_context_t c, reme_bag_builder_t *bb)
	Destroy a previously created bag object. More...
reme_error_t	reme_bag_builder_clear (reme_context_t c, reme_bag_builder_t bb)
	Clear bag builder. More...
reme_error_t	reme_bag_builder_set_int (reme_context_t c, reme_bag_builder_t bb, const char *key, int value)
	Add a value. More...
reme_error_t	reme_bag_builder_set_bool (reme_context_t c, reme_bag_builder_t bb, const char *key, bool value)
	Add a value. More...
reme_error_t	reme_bag_builder_set_real (reme_context_t c, reme_bag_builder_t bb, const char *key, float value)
	Add a value. More...
reme_error_t	reme_bag_builder_set_string (reme_context_t c, reme_bag_builder_t bb, const char *key, const char *value)
	Add a value. More...
reme_error_t	reme_bag_builder_set_bytes (reme_context_t c, reme_bag_builder_t bb, const char *key, const void *value, int valueLength)
	Add a value. More...
reme_error_t	reme_bag_builder_set_image (reme_context_t c, reme_bag_builder_t bb, const char *key, reme_image_t value, bool compress)
	Add a value. More...
reme_error_t	reme_bag_builder_set_sensor_config (reme_context_t c, reme_bag_builder_t bb, const char *key, reme_sensor_t s)
	Add a value. More...
reme_error_t	reme_bag_builder_set_transform (reme_context_t c, reme_bag_builder_t bb, const char *key, float *values)
	Add a value. More...
reme_error_t	reme_bag_builder_set_surface (reme_context_t c, reme_bag_builder_t bb, const char *key, reme_surface_t s)
	Add a value. More...
reme_error_t	reme_bag_builder_finalize (reme_context_t c, reme_bag_builder_t bb, reme_bag_t b)
	Finalizes the building process and creates a serialized bag. More...

Detailed Description

User defined key-value maps with fast serialization.

The Bag module provides methods for creating user defined key-values maps that support fast serialization and deserialization. They are commonly used transmit and receive data through Remote.

The object reme_bag_t represents a read-only key-value map with fast read access. To fill reme_bag_t objects use reme_bag_builder_t. On a low level reme_bag_t provides storage support for scalar types (int, real, bool), strings and byte arrays. Moreover, convenience methods are provides to read/write reme_image_t objects, transforms, reme_sensor_t configurations.

In order to fill a reme_bag_t with values, you will need an instance of reme_bag_builder_t and reme_bag_t as shown below.

    reme_bag_builder_t bb;
    reme_bag_builder_create(c, &bb);

    reme_bag_t bag;
    reme_bag_create(c, &bag);

You can the use the reme_bag_builder_t methods to set values

            reme_bag_builder_set_string(c, bb, "aString", "Hello World");
            reme_bag_builder_set_int(c, bb, "aInt", 10);           

Once you are done setting values you are ready to build the read-only reme_bag_t structure

            reme_bag_builder_finalize(c, bb, bag);

Note that calling reme_bag_builder_finalize will reset the reme_bag_builder_t to empty state. When you want to read from the bag, you can use the methods of reme_bag_t as shown below.

            int i;
            const char *str = 0;

            reme_bag_get_int(c, bag, "aInt", &i);
            reme_bag_get_string(c, bag, "aString", &str);
            printf("int: %d, string: %s\n", i, str);

Typedef Documentation

reme_bag_t

typedef int reme_bag_t

Handle referencing a bag object.

A reme_bag_t references a serialized immutable user-defined key-value map. It is commonly used to transfer data via remoting to other services.

reme_bag_builder_t

typedef int reme_bag_builder_t

Handle referencing a bag builder object.

A reme_bag_builder_t allows you to build reme_bag_t objects. Its functions allow you to set key-value pairs with overloads for integers, strings, reals and other value types.

Function Documentation

reme_bag_create()

reme_error_t reme_bag_create	(	reme_context_t	c,
		reme_bag_t *	b
	)

Create a bag.

A bag is a serialized immutable key-value map.

Parameters

c	A valid context object
b	A pointer to receive the created bag object handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_destroy()

reme_error_t reme_bag_destroy	(	reme_context_t	c,
		reme_bag_t *	b
	)

Destroy a previously created bag object.

Parameters

c	A pointer to a valid context object
b	A mutable pointer to a valid bag handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_has_key()

reme_error_t reme_bag_has_key	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		bool *	available
	)

Test if a certain key is present in the map.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
available	Whether or not key is present in map.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_get_int()

reme_error_t reme_bag_get_int	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		int *	value
	)

Read a value.

Reads an integer value from the bag.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	read value

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp.

reme_bag_get_real()

reme_error_t reme_bag_get_real	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		float *	value
	)

Read a value.

Reads an real value from the bag.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	read value

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_get_bool()

reme_error_t reme_bag_get_bool	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		bool *	value
	)

Read a value.

Reads an boolean value from the bag.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	read value

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_get_string()

reme_error_t reme_bag_get_string	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		const char **	value
	)

Read a value.

Reads an null-terminated string value from the bag. Note that the caller does not own the memory read and thus shall not free the memory.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	a mutable pointer to a null terminated string.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_get_bytes()

reme_error_t reme_bag_get_bytes	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		const void **	value,
		int *	length
	)

Read a value.

Reads a byte array from the bag. Note that the caller does not own the memory read and thus shall not free the memory.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	A mutable pointer that will receive the address of the byte array.
length	A pointer that will receive the length of the serialized message in bytes

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_get_image()

reme_error_t reme_bag_get_image	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		reme_image_t	value
	)

Read a value.

Reads an image from the bag. Note that the caller does not own the image memory read and thus shall not free the memory.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
value	A valid image object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_get_sensor_config()

reme_error_t reme_bag_get_sensor_config	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		reme_sensor_t	s
	)

Read a value.

Reads sensor depth intrinsics from the bag and sets it at provided sensor. Note, the sensor has to be of type "external".

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_get_transform()

reme_error_t reme_bag_get_transform	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		const float **	values
	)

Read a value.

Reads a 4x4 matrix. Note that the caller does not own the matrix memory read and thus shall not free the memory.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
values	A mutable pointer to the matrix data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_get_surface()

reme_error_t reme_bag_get_surface	(	reme_context_t	c,
		reme_bag_t	b,
		const char *	key,
		reme_surface_t	s
	)

Read a value.

Reads a reme_surface_t from the bag.

Parameters

c	A valid context object
b	A valid bag object
key	Key to read from
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_create()

reme_error_t reme_bag_builder_create	(	reme_context_t	c,
		reme_bag_builder_t *	bb
	)

Create a bag builder.

A bag builder is used to create a serializable bag of key-value pairs.

Parameters

c	A valid context object
bb	A pointer to receive the created bag builder object handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_destroy()

reme_error_t reme_bag_builder_destroy	(	reme_context_t	c,
		reme_bag_builder_t *	bb
	)

Destroy a previously created bag object.

Parameters

c	A pointer to a valid context object
bb	A mutable pointer to a valid bag builder handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_clear()

reme_error_t reme_bag_builder_clear	(	reme_context_t	c,
		reme_bag_builder_t	bb
	)

Clear bag builder.

Clears the bag builder and resets it to empty state. Will reuse allocated memory for further bag creations.

Parameters

c	A valid context object
bb	A valid bag builder object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_set_int()

reme_error_t reme_bag_builder_set_int	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		int	value
	)

Add a value.

Adds a new integer value. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp.

reme_bag_builder_set_bool()

reme_error_t reme_bag_builder_set_bool	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		bool	value
	)

Add a value.

Adds a boolean value. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_set_real()

reme_error_t reme_bag_builder_set_real	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		float	value
	)

Add a value.

Adds a real value. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_set_string()

reme_error_t reme_bag_builder_set_string	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		const char *	value
	)

Add a value.

Adds a null-terminated string value. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_set_bytes()

reme_error_t reme_bag_builder_set_bytes	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		const void *	value,
		int	valueLength
	)

Add a value.

Adds a new byte array to the bag. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	value to set
valueLength	number of bytes in array

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_set_image()

reme_error_t reme_bag_builder_set_image	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		reme_image_t	value,
		bool	compress
	)

Add a value.

Adds a image to the bag. In case the key is already taken, this method does not overwrite the previous value.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
value	A valid image object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_set_sensor_config()

reme_error_t reme_bag_builder_set_sensor_config	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		reme_sensor_t	s
	)

Add a value.

Adds sensor configuration parameters to the bag.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
s	A valid, opened sensor from which to read the intrinsics

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_set_transform()

reme_error_t reme_bag_builder_set_transform	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		float *	values
	)

Add a value.

Adds 4x4 Transform to the bag.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
values	16 float values representing the 4x4 matrix. See Transform

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_bag_builder_set_surface()

reme_error_t reme_bag_builder_set_surface	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		const char *	key,
		reme_surface_t	s
	)

Add a value.

Adds a surface to the bag.

Parameters

c	A valid context object
bb	A valid bag builder object
key	Key to associate value with
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_reconstruction.cpp.

reme_bag_builder_finalize()

reme_error_t reme_bag_builder_finalize	(	reme_context_t	c,
		reme_bag_builder_t	bb,
		reme_bag_t	b
	)

Finalizes the building process and creates a serialized bag.

Call this method once you are done adding values. This will create and optimized serialized bag ready for remote transmission and will reset the bag builder to empty state.

Parameters

c	A valid context object
bb	A valid bag builder object
b	A valid bag object to receive the serialized memory

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_remote_intro.cpp, and example_reconstructmesdk_remote_reconstruction.cpp.