Dynamic BPA descriptor. More...

#include <BPSecLib_Public.h>

Collaboration diagram for BSL_HostDescriptors_t:

Data Fields
void *	user_data
	User data pointer for callbacks.

int(*	get_sec_src_eid_fn )(void user_data, BSL_HostEID_t result)
	Host BPA function to get its security source EID.

void(*	eid_init )(void user_data, BSL_HostEID_t result)
	Host BPA function to initialize/allocate an EID type.

void(*	eid_deinit )(void user_data, BSL_HostEID_t eid)
	Host BPA function to deinit/free an EID type.

int(*	bundle_metadata_fn )(const BSL_BundleRef_t bundle_ref, BSL_PrimaryBlock_t result_primary_block)
	Host BPA function to populate a Primary Block struct.

int(*	block_metadata_fn )(const BSL_BundleRef_t bundle_ref, uint64_t block_num, BSL_CanonicalBlock_t result_block)
	Host BPA function to populate a Canonical Block struct for a given block number.

int(*	block_create_fn )(BSL_BundleRef_t bundle_ref, uint64_t block_type_code, uint64_t result_block_num)
	Host BPA function to create a new canonical block with the given type, returning result in the output pointer.

int(*	block_remove_fn )(BSL_BundleRef_t *bundle_ref, uint64_t block_num)
	Host BPA function to remove a given canonical block from the bundle.

int(*	block_realloc_btsd_fn )(BSL_BundleRef_t *bundle_ref, uint64_t block_num, size_t bytesize)
	Host BPA function to reallocate a canonical block's BTSD, keeping existing data in-place.

struct BSL_SeqReader_s (	block_read_btsd_fn )(const BSL_BundleRef_t *bundle_ref, uint64_t block_num)
	Host BPA function do create a new sequential reader on a single block-type-specific data.

struct BSL_SeqWriter_s (	block_write_btsd_fn )(BSL_BundleRef_t *bundle_ref, uint64_t block_num, size_t total_size)
	Host BPA function do create a new sequential writer on a single block-type-specific data.

int(*	bundle_delete_fn )(BSL_BundleRef_t *bundle_ref, BSL_ReasonCode_t reason)
	Host BPA function to delete Bundle with a reason code.

int(*	eid_to_cbor )(const BSL_HostEID_t eid, BSL_Data_t encoded_bytes)
	Host BPA function to encode an EID to CBOR.

int(*	eid_from_cbor )(const BSL_Data_t encoded_bytes, BSL_HostEID_t eid)
	Host BPA function to decode an EID from CBOR.

int(*	eid_from_text )(BSL_HostEID_t eid, const char text, void *user_data)
	Host BPA function to parse an EID from a C-string.

int(*	eidpat_init )(BSL_HostEIDPattern_t pat, void user_data)
	Host BPA function to initialize an EID pattern type.

void(*	eidpat_deinit )(BSL_HostEIDPattern_t pat, void user_data)
	Host BPA function to deinit an EID pattern type.

int(*	eidpat_from_text )(BSL_HostEIDPattern_t pat, const char text, void *user_data)
	Host BPA function to parse an EID pattern from a C-string.

bool(*	eidpat_match )(const BSL_HostEIDPattern_t pat, const BSL_HostEID_t eid, void *user_data)
	Host BPA function that returns true if the given EID matched an EID pattern.

bool(*	log_is_enabled_for )(int severity)
	Called to check if logging is enabled for at least a specific severity.

void(*	log_event )(const struct timeval timestamp, int severity, const char filename, int lineno, const char funcname, const char format, va_list args)
	Called for each log event from the BSL and its PP and SC instances.

BSL_DynMemHostDescriptors_t	dyn_mem_desc
	Optionally set dynamic memory management callbacks. Defaults to libc calls if unset.

Detailed Description

Dynamic BPA descriptor.

@caution All functions in this structure must be thread safe, as they can be called by any number of BSL instances across any threads.

Field Documentation

◆ block_create_fn

int(* BSL_HostDescriptors_t::block_create_fn) (BSL_BundleRef_t *bundle_ref, uint64_t block_type_code, uint64_t *result_block_num)

Host BPA function to create a new canonical block with the given type, returning result in the output pointer.

Referenced by BSL_BundleCtx_CreateBlock(), and BSL_HostDescriptors_Set().

◆ block_metadata_fn

int(* BSL_HostDescriptors_t::block_metadata_fn) (const BSL_BundleRef_t *bundle_ref, uint64_t block_num, BSL_CanonicalBlock_t *result_block)

Host BPA function to populate a Canonical Block struct for a given block number.

Referenced by BSL_BundleCtx_GetBlockMetadata(), and BSL_HostDescriptors_Set().

◆ block_read_btsd_fn

struct BSL_SeqReader_s *(* BSL_HostDescriptors_t::block_read_btsd_fn) (const BSL_BundleRef_t *bundle_ref, uint64_t block_num)

Host BPA function do create a new sequential reader on a single block-type-specific data.

Parameters

[in]	bundle_ref	The bundle to read data from.
	block_num	The specific block number to read BTSD from.

Returns: A pointer to a reader struct or NULL if the reader cannot be configured for any reason.

Referenced by BSL_BundleCtx_ReadBTSD().

◆ block_realloc_btsd_fn

int(* BSL_HostDescriptors_t::block_realloc_btsd_fn) (BSL_BundleRef_t *bundle_ref, uint64_t block_num, size_t bytesize)

Host BPA function to reallocate a canonical block's BTSD, keeping existing data in-place.

Deprecated:: use sequential writer to do this

Referenced by BSL_BundleCtx_ReallocBTSD(), and BSL_HostDescriptors_Set().

◆ block_remove_fn

int(* BSL_HostDescriptors_t::block_remove_fn) (BSL_BundleRef_t *bundle_ref, uint64_t block_num)

Host BPA function to remove a given canonical block from the bundle.

Referenced by BSL_BundleCtx_ReallocBTSD(), BSL_BundleCtx_RemoveBlock(), and BSL_HostDescriptors_Set().

◆ block_write_btsd_fn

struct BSL_SeqWriter_s *(* BSL_HostDescriptors_t::block_write_btsd_fn) (BSL_BundleRef_t *bundle_ref, uint64_t block_num, size_t total_size)

Host BPA function do create a new sequential writer on a single block-type-specific data.

The writer will call BSL_SeqWriter_Destroy() when it is finished.

Note: The BPA must double-buffer to allow a reader and writer on the same block.

Parameters

[in]	bundle_ref	The bundle to read data from.
	block_num	The specific block number to write BTSD into.
	total_size	A hint as to the total size that will be written.

Returns: A pointer to a reader struct or NULL if the reader cannot be configured for any reason.

Referenced by BSL_BundleCtx_WriteBTSD().

◆ bundle_delete_fn

int(* BSL_HostDescriptors_t::bundle_delete_fn) (BSL_BundleRef_t *bundle_ref, BSL_ReasonCode_t reason)

Host BPA function to delete Bundle with a reason code.

This can be called multiple times per-bundle with different reason codes

Referenced by BSL_BundleCtx_DeleteBundle().

◆ bundle_metadata_fn

int(* BSL_HostDescriptors_t::bundle_metadata_fn) (const BSL_BundleRef_t *bundle_ref, BSL_PrimaryBlock_t *result_primary_block)

Host BPA function to populate a Primary Block struct.

Referenced by BSL_BundleCtx_GetBundleMetadata(), and BSL_HostDescriptors_Set().

◆ dyn_mem_desc

BSL_DynMemHostDescriptors_t BSL_HostDescriptors_t::dyn_mem_desc

Optionally set dynamic memory management callbacks. Defaults to libc calls if unset.

Referenced by BSL_calloc(), BSL_free(), BSL_HostDescriptors_Set(), BSL_malloc(), BSL_realloc(), and suiteSetUp().

◆ eid_deinit

void(* BSL_HostDescriptors_t::eid_deinit) (void *user_data, BSL_HostEID_t *eid)

Host BPA function to deinit/free an EID type.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEID_Deinit().

◆ eid_from_cbor

int(* BSL_HostDescriptors_t::eid_from_cbor) (const BSL_Data_t *encoded_bytes, BSL_HostEID_t *eid)

Host BPA function to decode an EID from CBOR.

Parameters

[in]	encoded_bytes	Input encoded bytes. Initialized and deinitialized by BSL. The encoded EID must contain a CBOR array head.
[in,out]	eid	EID value to encode.

Returns: 0 if successful

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEID_DecodeFromCBOR().

◆ eid_from_text

int(* BSL_HostDescriptors_t::eid_from_text) (BSL_HostEID_t *eid, const char *text, void *user_data)

Host BPA function to parse an EID from a C-string.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEID_DecodeFromText().

◆ eid_init

void(* BSL_HostDescriptors_t::eid_init) (void *user_data, BSL_HostEID_t *result)

Host BPA function to initialize/allocate an EID type.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEID_Init().

◆ eid_to_cbor

int(* BSL_HostDescriptors_t::eid_to_cbor) (const BSL_HostEID_t *eid, BSL_Data_t *encoded_bytes)

Host BPA function to encode an EID to CBOR.

Parameters

[in]	eid	EID value to encode.
[in,out]	encoded_bytes	Output encoded bytes. Initialized and deinitialized by BSL. The encoded EID must contain a CBOR array head. If set to NULL, function should return needed size of encoded CBOR bytestring without actually copying data into param.

Returns: Number of bytes CBOR encoded EID must be

Referenced by BSL_HostEID_EncodeToCBOR().

◆ eidpat_deinit

void(* BSL_HostDescriptors_t::eidpat_deinit) (BSL_HostEIDPattern_t *pat, void *user_data)

Host BPA function to deinit an EID pattern type.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEIDPattern_Deinit().

◆ eidpat_from_text

int(* BSL_HostDescriptors_t::eidpat_from_text) (BSL_HostEIDPattern_t *pat, const char *text, void *user_data)

Host BPA function to parse an EID pattern from a C-string.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEIDPattern_DecodeFromText().

◆ eidpat_init

int(* BSL_HostDescriptors_t::eidpat_init) (BSL_HostEIDPattern_t *pat, void *user_data)

Host BPA function to initialize an EID pattern type.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEIDPattern_Init().

◆ eidpat_match

bool(* BSL_HostDescriptors_t::eidpat_match) (const BSL_HostEIDPattern_t *pat, const BSL_HostEID_t *eid, void *user_data)

Host BPA function that returns true if the given EID matched an EID pattern.

Referenced by BSL_HostDescriptors_Set(), and BSL_HostEIDPattern_IsMatch().

◆ get_sec_src_eid_fn

int(* BSL_HostDescriptors_t::get_sec_src_eid_fn) (void *user_data, BSL_HostEID_t *result)

Host BPA function to get its security source EID.

Referenced by BSL_Host_GetSecSrcEID(), and BSL_HostDescriptors_Set().

◆ log_event

void(* BSL_HostDescriptors_t::log_event) (const struct timeval *timestamp, int severity, const char *filename, int lineno, const char *funcname, const char *format, va_list args)

Called for each log event from the BSL and its PP and SC instances.

All input text strings must be copied by the callback if they are referenced outside of that callback.

Note: If not provided by the host, this defaults to writing synchronously to stderr.

Parameters

	timestamp	The timestamp of the original event.
	severity	The severity from a subset of the POSIX syslog values. This value has already been filtered by log_is_enabled_for.
[in]	filename	The originating file name, which may include directory parts.
[in]	lineno	The originating file line number.
[in]	funcname	The originating function name.
[in]	format	The log message format string.
	args	Values for the format string.

Referenced by BSL_LogEvent().

◆ log_is_enabled_for

bool(* BSL_HostDescriptors_t::log_is_enabled_for) (int severity)

Called to check if logging is enabled for at least a specific severity.

Note: If not provided by the host, this defaults to always-true.

Parameters

severity The severity from a subset of the POSIX syslog values.

Returns: True if logging will occur for that severity level.

Referenced by BSL_LogIsEnabledFor().

◆ user_data

void* BSL_HostDescriptors_t::user_data

User data pointer for callbacks.

Referenced by BSL_Host_GetSecSrcEID(), BSL_HostEID_DecodeFromText(), BSL_HostEID_Deinit(), BSL_HostEID_Init(), BSL_HostEIDPattern_DecodeFromText(), BSL_HostEIDPattern_Deinit(), BSL_HostEIDPattern_Init(), BSL_HostEIDPattern_IsMatch(), and MockBPA_Agent_Descriptors().

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

src/BPSecLib_Public.h

Data Fields

Detailed Description

Field Documentation

◆ block_create_fn

◆ block_metadata_fn

◆ block_read_btsd_fn

◆ block_realloc_btsd_fn

◆ block_remove_fn

◆ block_write_btsd_fn

◆ bundle_delete_fn

◆ bundle_metadata_fn

◆ dyn_mem_desc

◆ eid_deinit

◆ eid_from_cbor

◆ eid_from_text

◆ eid_init

◆ eid_to_cbor

◆ eidpat_deinit

◆ eidpat_from_text

◆ eidpat_init

◆ eidpat_match

◆ get_sec_src_eid_fn

◆ log_event

◆ log_is_enabled_for

◆ user_data