Options

Generic options object to manipulate system settings. More...

Typedefs
typedef int	reme_options_t
	Handle referencing an options object.
reme_error_t	reme_options_create (reme_context_t c, reme_options_t *o)
	Create a new options binding.
reme_error_t	reme_options_destroy (reme_context_t c, reme_options_t *o)
	Destroy a previously created options object.
reme_error_t	reme_options_set (reme_context_t c, reme_options_t o, const char *field_name, const char *value)
	Set a specific options field.
reme_error_t	reme_options_get (reme_context_t c, reme_options_t o, const char *field_name, const char **value, int *length)
	Get a specific repeated options field.
reme_error_t	reme_options_get_repeated (reme_context_t c, reme_options_t o, const char *field_name, int repeated_index, const char **value, int *length)
	Get a specific repeated options field.
reme_error_t	reme_options_get_repeated_count (reme_context_t c, reme_options_t o, const char *field_name, int *length)
	Return the number of elements in a repeated field.
reme_error_t	reme_options_bind_message (reme_context_t c, reme_options_t o, const char *field_name, reme_options_t o_nested)
	Bind options object to a nested message.
reme_error_t	reme_options_bind_repeated_message (reme_context_t c, reme_options_t o, const char *field_name, int repeated_index, reme_options_t o_nested)
	Bind options object to a nested repeated message.
reme_error_t	reme_options_copy (reme_context_t c, reme_options_t o_src, reme_options_t o_dst)
	Copy the content of the source options to the destination options.
reme_error_t	reme_options_load_from_file (reme_context_t c, reme_options_t o, const char *filename)
	Set options by loading a human readable options representation from file.
reme_error_t	reme_options_save_to_file (reme_context_t c, reme_options_t o, const char *filename)
	Save options in a human readable file format.
reme_error_t	reme_options_save_to_string (reme_context_t c, reme_options_t o, const char **message, int *length)
	Get options as string using a human readable serialization.
reme_error_t	reme_options_set_bytes (reme_context_t c, reme_options_t o, const void *message, int length)
	Set options by reading a binary options representation.
reme_error_t	reme_options_get_bytes (reme_context_t c, reme_options_t o, const void **message, int *length)
	Get options by serializing them in a binary options representation.

Detailed Description

Generic options object to manipulate system settings.

This module provides methods to interact and manipulate parameters and options generic way. Once a reme_options_t is created it is empty, as it does not represent any specific options. In order to manipulate specific options, you need to bind it to a specific options using a specific function that usually carries bind in its function name. The page Options Bindings lists all known binders. Each binder documents the available parameters in the method's detail section using Google Protocol Buffer format.

Once the options object is bound, it directly manipulates the bound options. You can query values using reme_options_get, manipulate values using reme_options_set, or export/import options from and to files using reme_options_save_to_file and reme_options_load_from_file.

See Accessing and Modifying Options for more details and examples.

Typedef Documentation

typedef int reme_options_t

Handle referencing an options object.

A reme_options_t references a specific options class. Internally ReconstructMe SDK uses Google's protocol buffers to represent options and parameters. Protocol buffers a language-neutral, platform-neutral, extensible mechanism for serializing structured data.

In order to manipulate these protocol buffer options you have two options:

• use the lazy dynamic interface and manipulate variables through a reflection like mechanism.

  See Also

  reme_options_set

  reme_options_get

• use the typesafe interface and generate a structure from the protobuf specification file using the protobuf compiler. Interact with this class and pass ReconstructMe SDK a serialized string to its content.

  See Also

  reme_options_set_bytes

  reme_options_get_bytes

  https://developers.google.com/protocol-buffers/

Function Documentation

reme_error_t reme_options_create	(	reme_context_t	c,
		reme_options_t *	o
	)

Create a new options binding.

Creates an empty options binding.

Parameters

c	A valid context object
o	A pointer that will receive the options handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_options_destroy	(	reme_context_t	c,
		reme_options_t *	o
	)

Destroy a previously created options object.

Parameters

c	A pointer to a valid context object
o	A mutable pointer to a valid options handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_set	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		const char *	value
	)

Set a specific options field.

This method uses a reflection like mechanism to set the specified field value. Use the '.' character to separate nested fields. If any field encountered is repeated the first element is used.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
value	Value String representation of the value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_options_get	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		const char **	value,
		int *	length
	)

Get a specific repeated options field.

This method uses a reflection like mechanism to get the specified field value. Use the '.' character to separate nested fields. If any field encountered is repeated the first element is used.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
value	Mutable pointer to receive the option value
length	Length of option value in characters.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp.

reme_error_t reme_options_get_repeated	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int	repeated_index,
		const char **	value,
		int *	length
	)

Get a specific repeated options field.

This method uses a reflection like mechanism to get the specified field value. Use the '.' character to separate nested fields. The repeated_index only affects the last part of the field description. Any parent repeated messages are accessed with index zero.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
repeated_index	When the target field is repeated the command applies to the i-th field.
value	Mutable pointer to receive the option value
length	Length of option value in characters.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_get_repeated_count	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int *	length
	)

Return the number of elements in a repeated field.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
length	Number of elements in repeated field. If field is not repeated, returns 1.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp.

reme_error_t reme_options_bind_message	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		reme_options_t	o_nested
	)

Bind options object to a nested message.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field containing the nested message
o_nested	A valid options object recieving the binding.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_error_t reme_options_bind_repeated_message	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int	repeated_index,
		reme_options_t	o_nested
	)

Bind options object to a nested repeated message.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field containing the nested message
repeated_index	When the target message is repeated the command applies to the i-th field.
o_nested	A valid options object recieving the binding.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp.

reme_error_t reme_options_copy	(	reme_context_t	c,
		reme_options_t	o_src,
		reme_options_t	o_dst
	)

Copy the content of the source options to the destination options.

This method requires the two option sets involved to be of the same type.

Parameters

c	A valid context object
o_src	A valid options object to copy from
o_dst	A valid options object to copy to

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_error_t reme_options_load_from_file	(	reme_context_t	c,
		reme_options_t	o,
		const char *	filename
	)

Set options by loading a human readable options representation from file.

This method uses protobuf's text format parser to read in the content of the file. This text format is very similar to json.

Parameters

c	A valid context object
o	A valid options object
filename	Path to file.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp, example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_sensor_multi_independent.cpp.

reme_error_t reme_options_save_to_file	(	reme_context_t	c,
		reme_options_t	o,
		const char *	filename
	)

Save options in a human readable file format.

This method uses protobuf's text format serializer to write in the content of the file. The output is similar to json.

Parameters

c	A valid context object
o	A valid options object
filename	Path to file.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, and example_reconstructmesdk_options.cpp.

reme_error_t reme_options_save_to_string	(	reme_context_t	c,
		reme_options_t	o,
		const char **	message,
		int *	length
	)

Get options as string using a human readable serialization.

This method uses protobuf's text format serializer to write in the content of the file. The output is similar to json.

Parameters

c	A valid context object
o	A valid options object
message	A mutable pointer that will receive the content of the message
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_error_t reme_options_set_bytes	(	reme_context_t	c,
		reme_options_t	o,
		const void *	message,
		int	length
	)

Set options by reading a binary options representation.

This method uses protobuf's standard serialization format (binary) to read in the desired options value.

Parameters

c	A valid context object
o	A valid options object
message	A valid pointer to the serialized message
length	The length of the serialized message in bytes.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_type_safe.cpp.

reme_error_t reme_options_get_bytes	(	reme_context_t	c,
		reme_options_t	o,
		const void **	message,
		int *	length
	)

Get options by serializing them in a binary options representation.

This method uses protobuf's standard serialization format (binary) to serialize the current state of option values.

Parameters

c	A valid context object
o	A valid options object
message	A mutable pointer that will receive the address of the serialized message
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

Examples:

example_reconstructmesdk_options_type_safe.cpp.