Update interface for files downloading. More...

#include <global-hal.h>
#include <stdbool.h>
#include <virgil/iot/storage_hal/storage_hal.h>
#include <virgil/iot/status_code/status_code.h>
#include <virgil/iot/provision/provision.h>

Data Structures
struct	vs_update_file_type_t
	File type information. More...

struct	vs_update_interface_t
	Update interface context. More...

Macros
#define	VS_UPDATE_DEFAULT_DESC_BUF_SZ (49)
	Min size of buffer for description string. More...

#define	VS_UPDATE_FILE_VERSION_STR_STATIC(VER_PTR) vs_update_file_version_str(VER_PTR, NULL, 0)
	Wrapper for vs_update_file_version_str to use static buffer. More...

#define	VS_UPDATE_FILE_TYPE_STR_STATIC(TYPE_PTR) vs_update_file_type_str(TYPE_PTR, NULL, 0)
	Wrapper for vs_update_file_type_str to use static buffer. More...

Typedefs
typedef vs_status_e(*	vs_update_get_header_size_cb_t) (void context, vs_update_file_type_t file_type, uint32_t *header_size)
	Get file type header size. More...

typedef vs_status_e(*	vs_update_get_file_size_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, uint32_t file_size)
	Get file size. More...

typedef vs_status_e(*	vs_update_has_footer_cb_t) (void context, vs_update_file_type_t file_type, bool *has_footer)
	Checks that such file type has footer. More...

typedef vs_status_e(*	vs_update_inc_data_offset_cb_t) (void context, vs_update_file_type_t file_type, uint32_t current_offset, uint32_t loaded_data_size, uint32_t *next_offset)
	Increment data offset. More...

typedef vs_status_e(*	vs_update_get_header_cb_t) (void context, vs_update_file_type_t file_type, void header_buffer, uint32_t buffer_size, uint32_t header_size)
	Get file header. More...

typedef vs_status_e(*	vs_update_get_data_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, void data_buffer, uint32_t buffer_size, uint32_t *data_size, uint32_t data_offset)
	Get file data. More...

typedef vs_status_e(*	vs_update_get_footer_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, void footer_buffer, uint32_t buffer_size, uint32_t *footer_size)
	Get footer. More...

typedef vs_status_e(*	vs_update_set_header_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, uint32_t header_size, uint32_t file_size)
	Set header. More...

typedef vs_status_e(*	vs_update_set_data_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, const void file_data, uint32_t data_size, uint32_t data_offset)
	Set data. More...

typedef vs_status_e(*	vs_update_set_footer_cb_t) (void context, vs_update_file_type_t file_type, const void file_header, const void file_footer, uint32_t footer_size)
	Set footer. More...

typedef void(*	vs_update_delete_object_cb_t) (void context, vs_update_file_type_t file_type)
	Delete object of defined type. More...

typedef vs_status_e(*	vs_update_verify_object_cb_t) (void context, vs_update_file_type_t file_type)
	Verify object of defined type. More...

typedef void(*	vs_update_free_item_cb_t) (void context, vs_update_file_type_t file_type)
	Free item during update destruction. More...

Enumerations
enum	vs_update_file_type_id_t { VS_UPDATE_FIRMWARE, VS_UPDATE_TRUST_LIST, VS_UPDATE_USER_FILES = 256 }
	File types. More...

Functions
bool	vs_update_equal_file_type (vs_update_file_type_t file_type, const vs_update_file_type_t unknown_file_type)
	Compare two files types. More...

vs_status_e	vs_update_compare_version (const vs_file_version_t update_ver, const vs_file_version_t current_ver)
	Compare two files versions. More...

const char *	vs_update_file_version_str (const vs_file_version_t version, char opt_buf, size_t buf_sz)
	Print file version into memory buffer. More...

const char *	vs_update_file_type_str (const vs_update_file_type_t file_type, char opt_buf, size_t buf_sz)
	Print file type description into memory buffer. More...

Detailed Description

Update interface for files downloading.

This file declares the vs_update_interface_t interface that is used for files downloading by client and sending by server. If you want to download/upload your own file type, you have to implement function callbacks for this interface. There are also some utilities for Update library.

Update Module usage

See vs_firmware_update_ctx source code and vs_tl_update_ctx one for update context implementation examples.

Macro Definition Documentation

◆ VS_UPDATE_DEFAULT_DESC_BUF_SZ

#define VS_UPDATE_DEFAULT_DESC_BUF_SZ (49)

Min size of buffer for description string.

◆ VS_UPDATE_FILE_TYPE_STR_STATIC

#define VS_UPDATE_FILE_TYPE_STR_STATIC ( TYPE_PTR ) vs_update_file_type_str(TYPE_PTR, NULL, 0)

Wrapper for vs_update_file_type_str to use static buffer.

◆ VS_UPDATE_FILE_VERSION_STR_STATIC

#define VS_UPDATE_FILE_VERSION_STR_STATIC ( VER_PTR ) vs_update_file_version_str(VER_PTR, NULL, 0)

Wrapper for vs_update_file_version_str to use static buffer.

Typedef Documentation

◆ vs_update_delete_object_cb_t

typedef void(* vs_update_delete_object_cb_t) (void *context, vs_update_file_type_t *file_type)

Delete object of defined type.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_free_item_cb_t

typedef void(* vs_update_free_item_cb_t) (void *context, vs_update_file_type_t *file_type)

Free item during update destruction.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.

◆ vs_update_get_data_cb_t

typedef vs_status_e(* vs_update_get_data_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, void *data_buffer, uint32_t buffer_size, uint32_t *data_size, uint32_t data_offset)

Get file data.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	Current file header. Cannot be NULL.
[in]	data_buffer	Data buffer. Cannot be NULL.
[in]	buffer_size	Data size. Cannot be zero.
[out]	data_size	Data buffer to store read data size. Cannot be NULL.
[in]	data_offset	Data offset. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_get_file_size_cb_t

typedef vs_status_e(* vs_update_get_file_size_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, uint32_t *file_size)

Get file size.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	File header.
[out]	file_size	Output buffer to store file size. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_get_footer_cb_t

typedef vs_status_e(* vs_update_get_footer_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, void *footer_buffer, uint32_t buffer_size, uint32_t *footer_size)

Get footer.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	Current file header. Cannot be NULL.
[out]	footer_buffer	Output footer buffer. Cannot be NULL.
[in]	buffer_size	Buffer size. Cannot be zero.
[out]	footer_size	Size of the footer to be read. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_get_header_cb_t

typedef vs_status_e(* vs_update_get_header_cb_t) (void *context, vs_update_file_type_t *file_type, void *header_buffer, uint32_t buffer_size, uint32_t *header_size)

Get file header.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[out]	header_buffer	Output buffer to save file header. Cannot be NULL.
[in]	buffer_size	Buffer size. Cannot be zero.
[out]	header_size	Output buffer to save header size. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_get_header_size_cb_t

typedef vs_status_e(* vs_update_get_header_size_cb_t) (void *context, vs_update_file_type_t *file_type, uint32_t *header_size)

Get file type header size.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[out]	header_size	Output buffer for current file type header size. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_has_footer_cb_t

typedef vs_status_e(* vs_update_has_footer_cb_t) (void *context, vs_update_file_type_t *file_type, bool *has_footer)

Checks that such file type has footer.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[out]	has_footer	Output boolean footer to store true if current file type has footer. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_inc_data_offset_cb_t

typedef vs_status_e(* vs_update_inc_data_offset_cb_t) (void *context, vs_update_file_type_t *file_type, uint32_t current_offset, uint32_t loaded_data_size, uint32_t *next_offset)

Increment data offset.

This implementation returns next file offset in subsequent load calls.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	current_offset	File offset for loading before this call.
[in]	loaded_data_size	Data size that has been loaded before this call.
[out]	next_offset	Output buffer to store offset for next call. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_set_data_cb_t

typedef vs_status_e(* vs_update_set_data_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, const void *file_data, uint32_t data_size, uint32_t data_offset)

Set data.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	Current file header. Cannot be NULL.
[in]	file_data	Data to be saved. Cannot be NULL.
[in]	data_size	Data size. Cannot be NULL.
[in]	data_offset	Data offset from the file beginning. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_set_footer_cb_t

typedef vs_status_e(* vs_update_set_footer_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, const void *file_footer, uint32_t footer_size)

Set footer.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	Current file header. Cannot be NULL.
[in]	file_footer	Current file footer. Cannot be NULL.
[in]	footer_size	Footer size. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_set_header_cb_t

typedef vs_status_e(* vs_update_set_header_cb_t) (void *context, vs_update_file_type_t *file_type, const void *file_header, uint32_t header_size, uint32_t *file_size)

Set header.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.
[in]	file_header	Current file header. Cannot be NULL.
[in]	header_size	Header size to be saved. Cannot be NULL.
[out]	file_size	Output buffer to store current file size. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

◆ vs_update_verify_object_cb_t

typedef vs_status_e(* vs_update_verify_object_cb_t) (void *context, vs_update_file_type_t *file_type)

Verify object of defined type.

Parameters

[in]	context	File context.
[in]	file_type	Current file type. Cannot be NULL.

Returns: VS_CODE_OK in case of success or error code.

Enumeration Type Documentation

◆ vs_update_file_type_id_t

enum vs_update_file_type_id_t

File types.

Enumerator
VS_UPDATE_FIRMWARE	Firmware files for different manufactures and device types.
VS_UPDATE_TRUST_LIST	Trust List files.
VS_UPDATE_USER_FILES	User file types must have an identifier that is not lower than this code.

Function Documentation

◆ vs_update_compare_version()

vs_status_e vs_update_compare_version	(	const vs_file_version_t *	update_ver,
		const vs_file_version_t *	current_ver
	)

Compare two files versions.

Parameters

update_ver	File to update. Cannot be NULL.
current_ver	Current file version. Cannot be NULL.

Returns: VS_CODE_OK if update_ver file is newer than current_ver file.; VS_CODE_OLD_VERSION if update_ver file is not newer than current_ver file.; Other vs_status_e in case of error.

◆ vs_update_equal_file_type()

bool vs_update_equal_file_type	(	vs_update_file_type_t *	file_type,
		const vs_update_file_type_t *	unknown_file_type
	)

Compare two files types.

Parameters

file_type	Known file type. Cannot be NULL.
unknown_file_type	Unknown file type. Cannot be NULL.

Returns: true if file types are equal and false otherwise

◆ vs_update_file_type_str()

const char* vs_update_file_type_str	(	const vs_update_file_type_t *	file_type,
		char *	opt_buf,
		size_t	buf_sz
	)

Print file type description into memory buffer.

Parameters

file_type	File type. Cannot be NULL.
opt_buf	Optional pointer to a buffer for an output of a description string. Can be NULL, in this case internal static buffer is used.
buf_sz	Size of #opt_buf. It makes sense with nonull opt_buff param.

Returns: Pointer to a buffer with the string.

◆ vs_update_file_version_str()

const char* vs_update_file_version_str	(	const vs_file_version_t *	version,
		char *	opt_buf,
		size_t	buf_sz
	)

Print file version into memory buffer.

Parameters

version	File version structure. Cannot be NULL.
opt_buf	Optional pointer to a buffer for an output of a version string. Can be NULL, in this case internal static buffer is used.
buf_sz	Size of #opt_buf. It makes sense with nonull opt_buff param.

Returns: Pointer to a buffer with the string.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Update Module usage

Macro Definition Documentation

◆ VS_UPDATE_DEFAULT_DESC_BUF_SZ

◆ VS_UPDATE_FILE_TYPE_STR_STATIC

◆ VS_UPDATE_FILE_VERSION_STR_STATIC

Typedef Documentation

◆ vs_update_delete_object_cb_t

◆ vs_update_free_item_cb_t

◆ vs_update_get_data_cb_t

◆ vs_update_get_file_size_cb_t

◆ vs_update_get_footer_cb_t

◆ vs_update_get_header_cb_t

◆ vs_update_get_header_size_cb_t

◆ vs_update_has_footer_cb_t

◆ vs_update_inc_data_offset_cb_t

◆ vs_update_set_data_cb_t

◆ vs_update_set_footer_cb_t

◆ vs_update_set_header_cb_t

◆ vs_update_verify_object_cb_t

Enumeration Type Documentation

◆ vs_update_file_type_id_t

Function Documentation

◆ vs_update_compare_version()

◆ vs_update_equal_file_type()

◆ vs_update_file_type_str()

◆ vs_update_file_version_str()