Entity

Enumerations
enum	e_entity_type { ,   entity_type_sequence = 1, entity_type_reference = 2, entity_type_int = 3, entity_type_float = 4,   entity_type_double = 5, entity_type_cstring = 6, entity_type_octet = 7, entity_type_ip4_address = 8,   entity_type_ip6_address = 9, entity_type_mac_address = 10, entity_type_boolean = 11 }
	Type tags used in hpi_entity structures. More...
enum	e_entity_role {   entity_role_null = 0, entity_role_value = 1, entity_role_classname = 2, entity_role_units = 3,   entity_role_flags = 4, entity_role_range = 5, entity_role_mapping = 6, entity_role_enum = 7 ,   entity_role_value_constraint = 11, entity_role_parameter_port = 12, entity_role_block = 13, entity_role_label = 14,   entity_role_key = 15, entity_role_value_label = 16 }
	Role tags used in hpi_entity structures. More...
enum	e_entity_flag_values {   entity_flag_writeable = 1, entity_flag_readable = 2, entity_flag_volatile = 4, entity_flag_volatile_info = 8,   entity_flag_requires_restart = 16 }
	Flag values used with entity_role_flags. More...

Functions
enum e_entity_role	HPI_Entity_GetRole (struct hpi_entity *entity)
	Return the role of the entity. More...
const char *	HPI_Entity_GetTypeName (struct hpi_entity *entity)
	Return the typename of the entity. More...
const char *	HPI_Entity_GetRoleName (struct hpi_entity *entity)
hpi_err_t	HPI_Entity_FindNext (struct hpi_entity *container_entity, enum e_entity_type type, enum e_entity_role role, int recursive_flag, struct hpi_entity **current_match)
	Search for an entity with the given type and role in a container entity. More...
void	HPI_Entity_Free (struct hpi_entity *entity)
	Free an hpi_entity allocated by HPI_Universal_* and HPI_Entity_* functions. More...
hpi_err_t	HPI_Entity_AllocAndPack (const enum e_entity_type type, const size_t item_count, const enum e_entity_role role, const void *value, const size_t value_size, struct hpi_entity **pentity)
	Allocate and initialize an entity with the provided parameters. More...
hpi_err_t	HPI_Entity_CopyValueFrom (struct hpi_entity *entity, enum e_entity_type type, size_t item_count, void *value_dst_p, size_t value_size)
	Copies item_count items from the Entity's value array into *value_dst_p. More...
hpi_err_t	HPI_Entity_Unpack (struct hpi_entity *entity, enum e_entity_type *type, size_t *item_count, enum e_entity_role *role, void **value)
	Extracts information from an entity into the specified locations. More...

Detailed Description

Enumeration Type Documentation

e_entity_type

enum e_entity_type

Type tags used in hpi_entity structures.

The value of an entity is an array of a single type.

Enumerator
entity_type_sequence	Sequence of potentially heterogeneous entities. Conceptually similar to C struct.
entity_type_reference	Reference to another entity.
entity_type_int	A 32 bit integer.
entity_type_float	An ieee754 binary 32 bit float.
entity_type_double	An ieee754 binary 64 bit double.
entity_type_cstring	ASCII character. Note An array of these (i.e. a string) may or may not be zero terminated within the encoded entity
entity_type_octet	An octet (8 bits)
entity_type_ip4_address	4 byte IP4 address
entity_type_ip6_address	16 byte IP6 address
entity_type_mac_address	6 byte ethernet MAC address
entity_type_boolean	Array of booleans packed as one boolean per octet, using 'T' or 'F' or 'x'.

e_entity_role

enum e_entity_role

Role tags used in hpi_entity structures.

Conceptually similar to C struct member names.

Enumerator
entity_role_null	no specific role
entity_role_value	value of addressed object
entity_role_classname	the name of addressed object
entity_role_units	A string representing the value units E.g. "dB", "Hz"
entity_role_flags	Entity flags A bitfield composed from values from e_entity_flag_values.
entity_role_range	The range of a value For numeric values, the range is [minimum, maximum, step].
entity_role_mapping	A mapping between sets of values of different types For instance mapping integers to strings. Encoded as two items, first with entity_role_key, second with entity_role_value
entity_role_enum	A sequence of allowed values for the item with entity_role_value.
entity_role_value_constraint	Sequence of entities describing constraints on the value Typically entity_role_range, entity_role_enum.
entity_role_parameter_port	Identifies a sequence representing a parameter port.
entity_role_block	Identifies a sequence representing a block.
entity_role_label	A label.
entity_role_key	Identifies the key part in entity_role_mapping.
entity_role_value_label	Identifies a mapping between values and labels.

e_entity_flag_values

enum e_entity_flag_values

Flag values used with entity_role_flags.

Enumerator
entity_flag_writeable	The entity value may be written (changed)
entity_flag_readable	The entity has a value that can be read.
entity_flag_volatile	The entity value can change apart from being written by a controller.
entity_flag_volatile_info	The entity info can change apart from being written by a controller.
entity_flag_requires_restart	Control change doesn't take effect until PC (or device) is restarted.

Function Documentation

HPI_Entity_GetRole()

enum e_entity_role HPI_Entity_GetRole

(

struct hpi_entity *

entity

)

Return the role of the entity.

Parameters

entity

Pointer to the entity

References entity_role_null.

HPI_Entity_GetTypeName()

const char* HPI_Entity_GetTypeName

(

struct hpi_entity *

entity

)

Return the typename of the entity.

Parameters

entity

Pointer to the entity

HPI_Entity_GetRoleName()

const char* HPI_Entity_GetRoleName

(

struct hpi_entity *

entity

)

Parameters

entity

Pointer to the entity

HPI_Entity_FindNext()

hpi_err_t HPI_Entity_FindNext	(	struct hpi_entity *	container_entity,
		enum e_entity_type	type,
		enum e_entity_role	role,
		int	recursive_flag,
		struct hpi_entity **	current_match
	)

Search for an entity with the given type and role in a container entity.

Search for an entity with the given type and role in container_entity. The search starts with the first entity inside the container_entity. If container_entity is not a sequence then the function will return immediately. The variable pointed by current_match will be updated with the address of the next Entity or set to NULL if no more entities are found. If current_match is not NULL upon call then the search resumes from the entity following current_match. The recursive_flag is honored so if current match is a sequence and recursive_flag is non-zero then searching will start with the first item in the sequence.

Parameters

container_entity	Pointer to the container entity to be searched.
type	Entity type selector value or entity_type_null. If a non-null type is specified then the returned match will have this type. If a null type is specified then the type of the entity is ignored when searching.
role	Entity role selector value or entity_role_null. If a non-null role is specified then the returned match will have this type. If a null role is specified then the role of the entity is ignored when searching.
current_match	Pointer to the variable where the pointer to the next matching entity will be copied. If no matching entity is found *current_match is set to NULL.
recursive_flag	Indicates the next entity should be obtained using a depth-first search. When the recursive_flag is set, the search starts at the current position in the entity tree and proceeds through the list of entity objects. Every time a sequence is encountered the new sequence is searched until the bottom of the tree is reached at which point the search backtracks.

For example, the tree below would be searched in order A,B,C,D,E,F,G,H if the recursive_flag is set. If the recursive_flag is not set the search order becomes A,B,C,H.

|------[A - entity of type sequence]
|------[B]
|------[C- entity of type sequence]
|      |---[D]
|      |---[E- entity of type sequence]
|            |---[F]
|            |---[G]
|
|------[H]

Returns

0 on success, or one of the HPI_ERROR_CODES.

References HPI_ERROR_MEMORY_ALLOC.

HPI_Entity_Free()

void HPI_Entity_Free

(

struct hpi_entity *

entity

)

Free an hpi_entity allocated by HPI_Universal_* and HPI_Entity_* functions.

Parameters

entity

Pointer to the entity to be freed

Referenced by HPI_Object_GetValue(), and HPI_Object_SetValue().

HPI_Entity_AllocAndPack()

hpi_err_t HPI_Entity_AllocAndPack	(	const enum e_entity_type	type,
		const size_t	item_count,
		const enum e_entity_role	role,
		const void *	value,
		const size_t	value_size,
		struct hpi_entity **	pentity
	)

Allocate and initialize an entity with the provided parameters.

Parameters

type	Entity type.
item_count	Number of instances of type contained in the value array.
role	Entity role.
value_size	Size in bytes of variable pointed to by value.
value	Pointer to an array of type with at least item_count elements.
pentity	Location where a pointer to the newly allocated buffer containing the entity is saved. The buffer must be freed by the caller using HPI_Entity_Free() even when the call returns an error.

Returns

0 on success, or one of the HPI_ERROR_CODES.

int integer = 0;
uint8_t ip4[4] = {192, 168, 0, 123};
struct hpi_entity *address, *enableflag;

HPI_Entity_AllocAndPack(entity_type_int, 1, entity_role_value, integer, &enableflag);
hpi_err_t HPI_SubSys_OptionSet(ss, HPI_SUBSYS_OPT_NET_BROADCAST, enableflag);
HPI_Entity_Free(enableflag);


HPI_Entity_AllocAndPack(entity_type_ip4_address, 1, entity_role_value, ip4, &address);
hpi_err_t HPI_SubSys_OptionSet(ss, HPI_SUBSYS_OPT_NET_ADDR, address);
HPI_Entity_Free(address);

Referenced by HPI_Object_SetValue().

HPI_Entity_CopyValueFrom()

hpi_err_t HPI_Entity_CopyValueFrom	(	struct hpi_entity *	entity,
		enum e_entity_type	type,
		size_t	item_count,
		void *	value_dst_p,
		size_t	value_size
	)

Copies item_count items from the Entity's value array into *value_dst_p.

If type is different from the type of the entity no value is copied and HPI_ERROR_ENTITY_TYPE_MISMATCH is returned.

If the item_count is larger than the size of the Entity's value array then no value is copied and HPI_ERROR_ENTITY_ITEM_COUNT is returned.

When type is entity_type_cstring, a zero terminator is appended to the copied bytes.

Parameters

entity	Pointer to the entity to copy values from.
type	Type of the variable pointed by value_dst_p.
item_count	Number of items to copy. This should match the storage associated with value_dst_p.
value_dst_p	Pointer to output buffer
value_size	Size in bytes of variable pointed to by value.

Returns

0 on success, or one of the HPI_ERROR_CODES.

int integer;
struct hpi_entity *enableflag;

HPI_SubSys_OptionGet(ss, HPI_SUBSYS_OPT_NET_BROADCAST, &enableflag);
HPI_Entity_CopyValueFrom(enableflag, entity_type_int, 1, &integer);
HPI_Entity_Free(enableflag);

References HPI_ERROR_ENTITY_TYPE_MISMATCH.

Referenced by HPI_Object_GetValue().

HPI_Entity_Unpack()

hpi_err_t HPI_Entity_Unpack	(	struct hpi_entity *	entity,
		enum e_entity_type *	type,
		size_t *	item_count,
		enum e_entity_role *	role,
		void **	value
	)

Extracts information from an entity into the specified locations.

Parameters

entity	The entity being unpacked.
type	Pointer to the variable where the type of the entity is copied to.
item_count	Pointer to the variable where the number of instances of type contained in the entity is copied to.
role	Pointer to the variable where the role of the entity is copied to.
value	Pointer to the location where a pointer to the value array of the entity is updated. Note: the value array of the entity is not copied, a pointer to its location is copied into the variable pointed by value.

Returns

0 on success, or one of the HPI_ERROR_CODES.

References HPI_ERROR_MEMORY_ALLOC.