Read and write templates. More...

Data Structures
struct	roc_template_pipe_type
	A cross-language cross-computer mechanism for streaming templates and media. More...

Typedefs
typedef struct roc_template_pipe_type *	roc_template_pipe
	Mechanism for streaming templates.

Functions
roc_error	roc_read_template (FILE file, roc_template template_)
	Read a template from a file pointer. More...

roc_error	roc_read_template_fd (int fd, roc_template *template_)
	Read a template from a file descriptor. More...

roc_error	roc_read_template_fd_ext (int fd, roc_template *template_, bool read_md, bool read_fv, bool read_tn)
	Generalized version of roc_read_template_fd. More...

roc_error	roc_write_template (FILE *file, const roc_template template_)
	Write a template to a file pointer. More...

roc_error	roc_write_template_fd (int fd, const roc_template template_)
	Write a template to a file descriptor. More...

roc_error	roc_get_metadata (const roc_template template_, const char key, roc_string value)
	Retrieve the value for a metadata key. More...

roc_error	roc_set_metadata (roc_template template_, const char key, const char *value)
	Add, update, or remove a single key/value pair in the metadata of a template. More...

roc_error	roc_set_metadata_object (roc_template template_, const char json_object)
	Extend the metadata of a template with additional key/value pairs. More...

roc_error	roc_realloc_metadata (roc_template *template_, uint32_t md_size)
	Re-allocate metadata space to allow later in-place editing. More...

roc_error	roc_clear_metadata (roc_template *template_)
	Clear template metadata. More...

roc_error	roc_clear_thumbnail (roc_template *template_)
	Clear template thumbnail. More...

roc_error	roc_clear_feature_vector (roc_template *template_, roc_algorithm_id representations)
	Clear template feature vector. More...

roc_error	roc_get_metadata_double (const roc_template template_, const char key, double value)
	Retrieve the value for a metadata key of type `double`. More...

roc_error	roc_set_metadata_double (roc_template template_, const char key, double value)
	Add, update, or remove a single key/value pair in the metadata of a template of type `double`. More...

roc_error	roc_to_base64 (const uint8_t input_byte_array, size_t length, roc_string str)
	Convert a binary buffer to a Base64 string. More...

roc_error	roc_from_base64 (const char str, roc_buffer buffer, size_t *buffer_length)
	Convert a Base64 string to a binary buffer. More...

roc_error	roc_open_template_pipe (const char template_pipe_file, bool append, bool keep_alive, bool replay_on_failure, const char sender_id, roc_template_pipe *template_pipe)
	Open a connection to a server to send templates. More...

roc_error	roc_template_pipe_transmit (roc_template_pipe template_pipe, const roc_template template_)
	Transmit a template. More...

roc_error	roc_template_pipe_transmit_event (roc_template_pipe template_pipe, const roc_event event)
	Transmit an event. More...

roc_error	roc_template_pipe_transmit_data (roc_template_pipe template_pipe, const uint8_t *data, size_t length, roc_hash key)
	Transmit a key/value pair. More...

roc_error	roc_template_pipe_transmit_image (roc_template_pipe template_pipe, const uint8_t *data, size_t length, roc_media_id media_id, roc_camera_id camera_id, roc_time timestamp)
	Transmit an image. More...

roc_error	roc_template_pipe_transmit_video (roc_template_pipe template_pipe, const uint8_t *data, size_t length, roc_media_id media_id, roc_camera_id camera_id, roc_time start, roc_time stop)
	Transmit a video. More...

roc_error	roc_template_pipe_transmit_log (roc_template_pipe template_pipe, const char *message)
	Send logging information. More...

roc_error	roc_set_template_pipe_log_callback (roc_template_pipe template_pipe)
	Initialize roc_template_pipe_log_callback for use as a roc_log_callback in roc_set_logging.

void	roc_template_pipe_log_callback (const char *message)
	roc_log_callback callback function for use by roc_set_logging. More...

size_t	roc_pending_transmissions ()
	Obtain the total number of pending transmissions across all open remote connections. More...

roc_error	roc_template_pipe_transmit_status (roc_template_pipe template_pipe, roc_stream_tracker_status_array status, size_t status_count, bool done, size_t pending_transmissions, float gpu_utilization_percent, float gpu_memory_used_percent)
	Send statuses per-camera-stream. More...

roc_error	roc_close_template_pipe (roc_template_pipe *template_pipe)
	Deallocate a roc_template_pipe. More...

roc_error	roc_decode_protobuf_template (const uint8_t input_byte_array, size_t length, roc_template template_)
	Decode a Protobuf Template. More...

roc_error	roc_encode_protobuf_template (const roc_template template_, roc_buffer buffer, size_t buffer_length)
	Encode a Protobuf Template. More...

Detailed Description

Read and write templates.

Copy a template with roc_copy_template. Serialize and deserialze templates to memory buffers with roc_flatten and roc_unflatten. Read and write templates using file pointers with roc_read_template and roc_write_template, or file descriptors with roc_read_template_fd and roc_write_template_fd. Read and write template metadata with roc_get_metadata and roc_set_metadata or roc_get_metadata_double and roc_set_metadata_double.

Data Structure Documentation

◆ roc_template_pipe_type

struct roc_template_pipe_type

A cross-language cross-computer mechanism for streaming templates and media.

To receive templates, inherit from this class and implement the transmit function.

Public Member Functions
virtual roc_error	transmit (const roc_template &template_)=0
	Send (caller) / recieve (callee) a roc_template.

virtual roc_error	transmit_event (const roc_event &event)
	Send (caller) / recieve (callee) a roc_event.

virtual roc_error	transmit_data (const uint8_t *data, size_t length, roc_hash key)
	Send (caller) / recieve (callee) key/value data.

virtual roc_error	transmit_image (const uint8_t *data, size_t length, roc_media_id media_id, roc_camera_id camera, roc_time timestamp)
	Send (caller) / recieve (callee) image data.

virtual roc_error	transmit_video (const uint8_t *data, size_t length, roc_media_id media_id, roc_camera_id camera, roc_time start, roc_time stop)
	Send (caller) / recieve (callee) video data.

virtual roc_error	transmit_log (const char *message)
	Send (caller) / recieve (callee) logging information.

virtual roc_error	transmit_status (roc_stream_tracker_status_array status, size_t status_count, bool done, size_t pending_transmissions, float gpu_utilization_percent, float gpu_memory_used_percent)
	Send (caller) / recieve (callee) stream statuses.

Function Documentation

◆ roc_read_template()

roc_error roc_read_template	(	FILE *	file,
		roc_template *	template_
	)

Read a template from a file pointer.

Use this function to read from a roc_gallery_file. On success, file will be advanced to the end of template_. If the end-of-file (EOF) is reached before reading a complete template, roc_template::algorithm_id will be set to ROC_NO_ALGORITHM_OPTIONS and this function will return without error. If some bytes were read before the EOF was reached then file will be reset to its original position and the EOF indicator will be cleared, otherwise the EOF indicator will remain indicating the end of the gallery file was successfully reached.

Free template_ after use with roc_free_template.

Warning: On Windows it is not recommended to pass C runtime objects across library boundaries, therefore this function may not work. See roc_gallery_file for alternatives.

Example: roc_template template_;
FILE *file = fopen("templates.t", "rb");
roc_read_template(file, &template_);

Parameters

[in]	file	File to read from.
[out]	template_	Pointer to unallocated template to construct.

Remarks: This function is reentrant.

See also: roc_write_template

◆ roc_read_template_fd()

roc_error roc_read_template_fd	(	int	fd,
		roc_template *	template_
	)

Read a template from a file descriptor.

Use this function to read from a roc_gallery_file. On success, file will be advanced to the end of template_. If the end-of-file (EOF) is reached before reading a complete template, roc_template::algorithm_id will be set to ROC_NO_ALGORITHM_OPTIONS, file will be reset to its original position, and the function will return without error.

Free template_ after use with roc_free_template.

Example: roc_template template_;
int fd = open("templates.t", O_RDONLY);
roc_read_template_fd(fd, &template_);

Parameters

[in]	fd	File descriptor to read from.
[out]	template_	Pointer to unallocated template to construct.

Remarks: This function is reentrant.

See also: roc_write_template_fd roc_read_template_fd_ext

◆ roc_read_template_fd_ext()

roc_error roc_read_template_fd_ext	(	int	fd,
		roc_template *	template_,
		bool	read_md,
		bool	read_fv,
		bool	read_tn
	)

Generalized version of roc_read_template_fd.

Improve read speed by skipping the parts of the template that aren't needed.

Parameters

[in]	fd	File descriptor to read from.
[out]	template_	Pointer to unallocated template to construct.
[in]	read_md	Read the metadata.
[in]	read_fv	Read the feature vector.
[in]	read_tn	Read thumbnail.

Remarks: This function is reentrant.

See also: roc_read_template_fd

◆ roc_write_template()

roc_error roc_write_template	(	FILE *	file,
		const roc_template	template_
	)

Write a template to a file pointer.

Use this function to write to a roc_gallery_file. On success, file will be advanced to the end of template_.

Warning: On Windows it is not recommended to pass C runtime objects across library boundaries, therefore this function may not work. See roc_gallery_file for alternatives.

Example: roc_template template_ = ...;
FILE *file = fopen("templates.t", "wb");
roc_write_template(file, template_);

Parameters

[in]	file	File to write to.
[out]	template_	Template to write.

Remarks: This function is reentrant.

See also: roc_read_template

◆ roc_write_template_fd()

roc_error roc_write_template_fd	(	int	fd,
		const roc_template	template_
	)

Write a template to a file descriptor.

Use this function to write to a roc_gallery_file. On success, file will be advanced to the end of template_.

Example: roc_template template_ = ...;
int fd = fopen("templates.t", O_WRONLY);
roc_write_template_fd(fd, template_);

Parameters

[in]	fd	File descriptor to write to.
[out]	template_	Template to write.

Remarks: This function is reentrant.

See also: roc_read_template_fd

◆ roc_get_metadata()

roc_error roc_get_metadata	(	const roc_template	template_,
		const char *	key,
		roc_string *	value
	)

Retrieve the value for a metadata key.

If key does not exist then value will be set to NULL. For values of type double, see roc_get_metadata_double.

Template metadata is JSON formatted, see Metadata for details.

Free value after use with roc_free_string.

Example: roc_template template_ = ...;
roc_string value;
roc_get_metadata(template_, "LeftEyeX", &value);

Parameters

[in]	template_	Template to retrieve the metadata value from.
[in]	key	Key to retrieve the value of.
[out]	value	Value corresponding to the key.

See also: roc_set_metadata

◆ roc_set_metadata()

roc_error roc_set_metadata	(	roc_template *	template_,
		const char *	key,
		const char *	value
	)

Add, update, or remove a single key/value pair in the metadata of a template.

If value is NULL then key will be removed from the metadata. After this function returns, the roc_template::md field of template_ will point to a new string. This function does not modify other metadata entries. For values of type double, see roc_get_metadata_double.

Template metadata is JSON formatted, see Metadata for details.

Example: roc_template template_ = ...;
roc_set_metadata(template_, "LeftEyeX", "127");

Parameters

[in,out]	template_	Template to update the metadata of.
[in]	key	Metadata key to set.
[in]	value	Metadata value to set the key to.

Remarks: This function is reentrant.

See also: roc_get_metadata roc_realloc_metadata roc_clear_metadata roc_set_metadata_object

◆ roc_set_metadata_object()

roc_error roc_set_metadata_object	(	roc_template *	template_,
		const char *	json_object
	)

Extend the metadata of a template with additional key/value pairs.

Each key/value pair in the JSON object json_object will be added to the template metadata.

Example: roc_template template_ = ...;
roc_set_metadata(template_, "{ \"Key1\": \"Value1\", \"Key2\": \"Value2\" }");

Parameters

[in,out]	template_	Template to update the metadata of.
[in]	json_object	JSON object to extend `template_` with.

Remarks: This function is reentrant.

See also: roc_set_metadata

◆ roc_realloc_metadata()

roc_error roc_realloc_metadata	(	roc_template *	template_,
		uint32_t	md_size
	)

Re-allocate metadata space to allow later in-place editing.

Parameters

[in,out]	template_	Template to update the metadata of.
[in]	md_size	New metadata buffer size.

Remarks: This function is reentrant.

See also: roc_set_metadata

◆ roc_clear_metadata()

roc_error roc_clear_metadata ( roc_template * template_ )

Clear template metadata.

After this function is called, roc_template::md will be NULL and roc_template::md_size will be 0.

Parameters

[in,out] template_ Template to clear metadata.

Remarks: This function is reentrant.

See also: roc_set_metadata roc_clear_thumbnail roc_clear_feature_vector

◆ roc_clear_thumbnail()

roc_error roc_clear_thumbnail ( roc_template * template_ )

Clear template thumbnail.

After this function is called, roc_template::tn will be NULL and roc_template::tn_size will be 0.

Parameters

[in,out] template_ Template to clear thumbnail.

Remarks: This function is reentrant.

See also: roc_clear_metadata roc_clear_feature_vector

◆ roc_clear_feature_vector()

roc_error roc_clear_feature_vector	(	roc_template *	template_,
		roc_algorithm_id	representations
	)

Clear template feature vector.

After this function is called, roc_template::fv and roc_template::algorithm_id will be updated to omit all representations in representations.

Parameters

[in,out]	template_	Template to remove representations from.
[in]	representations	Representations to remove.

Remarks: This function is reentrant.

See also: roc_clear_metadata roc_clear_thumbnail

◆ roc_get_metadata_double()

roc_error roc_get_metadata_double	(	const roc_template	template_,
		const char *	key,
		double *	value
	)

Retrieve the value for a metadata key of type double.

A convenient alternative to roc_get_metadata for numerical values. Works for both integer and floating-point values. If key does not exist then value will be set to NAN.

Example: roc_template template_ = ...;
double value;
roc_get_metadata_double(template_, "LeftEyeX", &value);

Parameters

[in]	template_	Template to retrieve the metadata value from.
[in]	key	Key to retrieve the value of.
[out]	value	Value corresponding to the key.

See also: roc_set_metadata_double

◆ roc_set_metadata_double()

roc_error roc_set_metadata_double	(	roc_template *	template_,
		const char *	key,
		double	value
	)

Add, update, or remove a single key/value pair in the metadata of a template of type double.

A convenient alternative to roc_set_metadata for numerical values. Works for both integer and floating-point values. If value is NAN then key will be removed from the metadata.

Example: roc_template template_ = ...;
roc_set_metadata_double(template_, "LeftEyeX", 127);

Parameters

[in,out]	template_	Template to update the metadata of.
[in]	key	Metadata key to set.
[in]	value	Metadata value to set the key to.

Remarks: This function is reentrant.

See also: roc_get_metadata_double

◆ roc_to_base64()

roc_error roc_to_base64	(	const uint8_t *	input_byte_array,
		size_t	length,
		roc_string *	str
	)

Convert a binary buffer to a Base64 string.

The Base64 conversion uses the URL-safe encoding convention, meaning - instead of +, and _ instead of /.

Free str after use with roc_free_string.

Example: uint8_t *input_byte_array = ...;
size_t length = ...;
roc_string str;
roc_to_base64(input_byte_array, length, &str);

Parameters

[in]	input_byte_array	Binary buffer to convert.
[in]	length	Length of `input_byte_array`.
[out]	str	Base64 string encoding of `input_byte_array`.

Remarks: This function is reentrant.

See also: roc_from_base64

◆ roc_from_base64()

roc_error roc_from_base64	(	const char *	str,
		roc_buffer *	buffer,
		size_t *	buffer_length
	)

Convert a Base64 string to a binary buffer.

Free buffer after use with roc_free_buffer.

Example: const char *str = ...;
roc_buffer buffer;
size_t buffer_length;
roc_from_base64(str, &buffer, &buffer_length);

Parameters

[in]	str	Base64 string to convert.
[out]	buffer	Binary decoding of `str`.
[out]	buffer_length	Length of `buffer`.

Remarks: This function is reentrant.

See also: roc_to_base64

◆ roc_open_template_pipe()

roc_error roc_open_template_pipe	(	const char *	template_pipe_file,
		bool	append,
		bool	keep_alive,
		bool	replay_on_failure,
		const char *	sender_id,
		roc_template_pipe *	template_pipe
	)

Open a connection to a server to send templates.

Similar to roc_open_gallery, template_pipe_file can be either a local file or server url. If template_pipe_file is NULL, templates are written to STDOUT. If template_pipe_file is a local directory it is interpreted as a roc_database and only roc_template_pipe::transmit_data are recorded using roc_database_add_data.

Free template_pipe after usage with roc_close_template_pipe.

Parameters

[in]	template_pipe_file	Location to write templates to.
[in]	append	For local files, controls opening in write or append mode.
[in]	keep_alive	Ignore transmission errors and re-establish the connection.
[in]	replay_on_failure	Replay transmissions that fail.
[in]	sender_id	Unique ID of sender.
[out]	template_pipe	Template pipe to initialize.

Remarks: This function is reentrant.

◆ roc_template_pipe_transmit()

roc_error roc_template_pipe_transmit	(	roc_template_pipe	template_pipe,
		const roc_template	template_
	)

Transmit a template.

Parameters

[in]	template_pipe	Pipe to transmit the template over.
[in]	template_	Template to transmit.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_event()

roc_error roc_template_pipe_transmit_event	(	roc_template_pipe	template_pipe,
		const roc_event	event
	)

Transmit an event.

Parameters

[in]	template_pipe	Pipe to transmit the event over.
[in]	event	Event to transmit.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_data()

roc_error roc_template_pipe_transmit_data	(	roc_template_pipe	template_pipe,
		const uint8_t *	data,
		size_t	length,
		roc_hash	key
	)

Transmit a key/value pair.

Parameters

[in]	template_pipe	Pipe to transmit the data over.
[in]	data	Data to transmit.
[in]	length	Length of `data`.
[in]	key	roc_hash_calc_sha1 of `data`.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_image()

roc_error roc_template_pipe_transmit_image	(	roc_template_pipe	template_pipe,
		const uint8_t *	data,
		size_t	length,
		roc_media_id	media_id,
		roc_camera_id	camera_id,
		roc_time	timestamp
	)

Transmit an image.

Parameters

[in]	template_pipe	Pipe to transmit the image over.
[in]	data	Image data to transmit.
[in]	length	Length of `data`.
[in]	media_id	roc_hash_calc_sha1 of `data`.
[in]	camera_id	Camera unique identifier.
[in]	timestamp	Image timestamp.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_video()

roc_error roc_template_pipe_transmit_video	(	roc_template_pipe	template_pipe,
		const uint8_t *	data,
		size_t	length,
		roc_media_id	media_id,
		roc_camera_id	camera_id,
		roc_time	start,
		roc_time	stop
	)

Transmit a video.

Parameters

[in]	template_pipe	Pipe to transmit the video over.
[in]	data	Video data to transmit.
[in]	length	Length of `data`.
[in]	media_id	roc_hash_calc_sha1 of `data`.
[in]	camera_id	Camera unique identifier.
[in]	start	Video start time.
[in]	stop	Video stop time.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_log()

roc_error roc_template_pipe_transmit_log	(	roc_template_pipe	template_pipe,
		const char *	message
	)

Send logging information.

Parameters

[in]	template_pipe	Pipe to send logging information.
[in]	message	Message to send.

Remarks: This function is thread-safe.

◆ roc_template_pipe_log_callback()

void roc_template_pipe_log_callback ( const char * message )

roc_log_callback callback function for use by roc_set_logging.

Initialize before use with roc_set_template_pipe_log_callback.

◆ roc_pending_transmissions()

size_t roc_pending_transmissions ( )

Obtain the total number of pending transmissions across all open remote connections.

Remarks: This function is thread-safe.

◆ roc_template_pipe_transmit_status()

roc_error roc_template_pipe_transmit_status	(	roc_template_pipe	template_pipe,
		roc_stream_tracker_status_array	status,
		size_t	status_count,
		bool	done,
		size_t	pending_transmissions,
		float	gpu_utilization_percent,
		float	gpu_memory_used_percent
	)

Send statuses per-camera-stream.

Parameters

[in]	template_pipe	Pipe to send status information.
[in]	status	roc_stream_tracker_status_array object.
[in]	status_count	Number of stream entries in `status`.
[in]	done	True if all streams have finished processing.
[in]	pending_transmissions	Total amount of templates, images, recordings, etc. that have been queued to be sent, but not sent yet.
[in]	gpu_utilization_percent	Average GPU utilization over the last 30 seconds.
[in]	gpu_memory_used_percent	Average GPU memory used over the last 30 seconds.

Remarks: This function is thread-safe.

◆ roc_close_template_pipe()

roc_error roc_close_template_pipe ( roc_template_pipe * template_pipe )

Deallocate a roc_template_pipe.

Closes the connection to the server and deallocates template_pipe.

Parameters

[in] template_pipe Template pipe to deallocate.

Remarks: This function is reentrant.

◆ roc_decode_protobuf_template()

roc_error roc_decode_protobuf_template	(	const uint8_t *	input_byte_array,
		size_t	length,
		roc_template *	template_
	)

Decode a Protobuf Template.

Free template after use with roc_free_template.

Parameters

[in]	input_byte_array	Protobuf Template buffer.
[in]	length	Length of `input_byte_array`.
[out]	template_	Output of roc_template conversion.

Remarks: This function is reentrant.

◆ roc_encode_protobuf_template()

roc_error roc_encode_protobuf_template	(	const roc_template	template_,
		roc_buffer *	buffer,
		size_t *	buffer_length
	)

Encode a Protobuf Template.

Free buffer after use with roc_free_buffer.

Parameters

[in]	template_	Input for roc_template conversion.
[out]	buffer	Output Protobuf Template buffer.
[out]	buffer_length	Length of `output_byte_array`.

Remarks: This function is reentrant.

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ roc_template_pipe_type

Public Member Functions

Function Documentation

◆ roc_read_template()

◆ roc_read_template_fd()

◆ roc_read_template_fd_ext()

◆ roc_write_template()

◆ roc_write_template_fd()

◆ roc_get_metadata()

◆ roc_set_metadata()

◆ roc_set_metadata_object()

◆ roc_realloc_metadata()

◆ roc_clear_metadata()

◆ roc_clear_thumbnail()

◆ roc_clear_feature_vector()

◆ roc_get_metadata_double()

◆ roc_set_metadata_double()

◆ roc_to_base64()

◆ roc_from_base64()

◆ roc_open_template_pipe()

◆ roc_template_pipe_transmit()

◆ roc_template_pipe_transmit_event()

◆ roc_template_pipe_transmit_data()

◆ roc_template_pipe_transmit_image()

◆ roc_template_pipe_transmit_video()

◆ roc_template_pipe_transmit_log()

◆ roc_template_pipe_log_callback()

◆ roc_pending_transmissions()

◆ roc_template_pipe_transmit_status()

◆ roc_close_template_pipe()

◆ roc_decode_protobuf_template()

◆ roc_encode_protobuf_template()