AudioScience HPI Version_4.15.
Enumerations | Functions

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 }
 

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.
const char * HPI_Entity_GetTypeName (struct hpi_entity *entity)
 Return the typename of the entity.
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.
void HPI_Entity_Free (struct hpi_entity *entity)
 Free an hpi_entity allocated by HPI_Universal_* and HPI_Entity_* functions.
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.
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.
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.

Enumeration Type Documentation

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'.

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.

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.


Function Documentation

enum e_entity_role HPI_Entity_GetRole ( struct hpi_entity *  entity)

Return the role of the entity.

Parameters:
entityPointer to the entity

References entity_role_null.

Referenced by HPI_Object_BlockParameters(), and HPI_Object_GetRole().

const char* HPI_Entity_GetTypeName ( struct hpi_entity *  entity)

Return the typename of the entity.

Parameters:
entityPointer to the entity
const char* HPI_Entity_GetRoleName ( struct hpi_entity *  entity)
Parameters:
entityPointer to the 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.

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_entityPointer to the container entity to be searched.
typeEntity 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.
roleEntity 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_matchPointer 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_flagIndicates 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_ENTITY_ITEM_COUNT, and HPI_ERROR_MEMORY_ALLOC.

Referenced by HPI_Object_BlockParameters(), and HPI_Object_GetInfo().

void HPI_Entity_Free ( struct hpi_entity *  entity)

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

Parameters:
entityPointer to the entity to be freed

Referenced by HPI_Object_BlockParameters(), HPI_Object_GetInfo(), HPI_Object_GetRole(), HPI_Object_GetValue(), and HPI_Object_SetValue().

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:
typeEntity type.
item_countNumber of instances of _type_ contained in the _value_ array.
roleEntity role.
value_sizeSize in bytes of variable pointed to by value.
valuePointer to an array of _type_ with at least _item_count_ elements.
pentityLocation 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);

References HPI_ERROR_ENTITY_ITEM_COUNT, and HPI_ERROR_MEMORY_ALLOC.

Referenced by HPI_Object_SetValue().

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:
entityPointer to the entity to copy values from.
typeType of the variable pointed by value_dst_p.
item_countNumber of items to copy. This should match the storage associated with value_dst_p.
value_dst_pPointer to output buffer
value_sizeSize 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 entity_type_cstring, HPI_ERROR_ENTITY_ITEM_COUNT, and HPI_ERROR_ENTITY_TYPE_MISMATCH.

Referenced by HPI_Object_GetValue().

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:
entityThe entity being unpacked.
typePointer to the variable where the type of the entity is copied to.
item_countPointer to the variable where the number of instances of _type_ contained in the entity is copied to.
rolePointer to the variable where the role of the entity is copied to.
valuePointer 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 entity_type_sequence, and HPI_ERROR_MEMORY_ALLOC.

Referenced by HPI_Object_BlockParameters(), and HPI_Object_GetInfo().