Detailed Description

Structures for properties which are available, or required.

Terms

Required Property Index : the 0 based index of the property in the names the caller gave when the data set was created, which is the index every read by position takes. A reload does not change it. A name the data does not have keeps its index, and reads as a property the data set does not have. When the caller named no property, it is the index of the property in the list of available properties, which a reload can change.

Available Index : the 0 based index of the property in the list of available properties, which holds the properties the data has in ascending order of name. Not the same as the required property index when the caller named properties.

Property Index : the 0 based index of the property in the source used to create the required properties. Not the same as the required property index.

Results : the structure used to contain the data associated with the available required properties.

Source : the source of property names. Typically a call back method to return properties from the data structure used by the aspect engine.

Introduction

Aspect engine performance can often be improved by limiting the properties that can be returned from the engine. As this is a performance feature shared across different types of aspect engine the utility functions are stored in the common C files.

Required properties could be specified at initialisation as a character separated string, as an array of strings or from an existing set of properties already obtained from these methods. In all scenarios it is desirable to be able to query the properties and find their indexes in the source data structure using a consistent set of methods.

Creation

fiftyoneDegreesPropertiesCreate is used to create a consistent set of required properties. The structure passed must have one of the follow set.

Separated string of property names. Valid separators include space, comma and pipe.
An array of strings.
Existing properties results from a previous creation operation. This method is used when a data set is being reloaded due to a change in the underlying data. The new results are created from the names the caller gave the first time, so a property the previous data did not have is available once the new data has it, and a caller that named no property gets every property of the new data.

Creation also requires a method to retrieve the name of the properties from the underlying data source. A method pointer conforming to fiftyoneDegreesPropertiesGetMethod must be provided to retrieve the property name string item for a given property index up to the maximum count. The call back is used to avoid any hard dependency between the data structure and the properties methods.

Unlike standard collection item retrieval the properties methods will not know the underlying collection implement or reference from which the item was obtained from. Therefore the implementation of get MUST set the collection field of the collection item.

Some, or all, of the required properties may not be present in the underlying data source. A missing property is left out of the available properties, and keeps its required property index, which reads as a property the data set does not have. The number of required property indexes is given by fiftyoneDegreesPropertiesGetRequiredPropertyCount, and the name at each by fiftyoneDegreesPropertiesGetNameFromRequiredIndex. The count field and the items of the results are the available properties, which are in available index order, so a caller pairing them with required property indexes reads the wrong properties.

Whilst the property names can be provided as string(s) the property names referenced from the properties results are collection items from a strings collection. The properties methods are responsible for releasing the references to these strings when the properties results are freed.

The available properties are in ascending order of the property name, so a binary search quickly finds a property from its name.

Free

When the properties results are finished with, the fiftyoneDegreesPropertiesFree method must be used. This will also free the collection items used to reference the property name strings using the collection field of the item to obtain the source collection. This collection must have been set by the get method used at creation.

Operation

Several methods are available which can be used to convert from an input such as a property name or required property index to a property index in the data structure. The method names are self-explanatory.

Where possible using integer property or required property indexes is preferable to the string representation of the property as this improves performance.

Collaboration diagram for Properties:

Structs
struct	fiftyoneDegreesEvidencePropertyIndexArray
	Array of items of type fiftyoneDegreesEvidencePropertyIndex used to easily access and track the size of the array. More...
struct	fiftyoneDegreesPropertyAvailable
	Used to access the property item quickly without the need to search. More...
struct	fiftyoneDegreesPropertyNamed
	A property name the caller gave, in the place the caller gave it. More...
struct	fiftyoneDegreesPropertyAvailableArray
	Array of items of type fiftyoneDegreesPropertyAvailable used to easily access and track the size of the array. More...
struct	fiftyoneDegreesPropertiesRequired
	Defines a set of properties which are required by a caller. More...

Macros
#define	FIFTYONE_DEGREES_PROPERTIES_SEPARATORS "\|, "
	Characters which separate the names in a required properties string.
#define	FIFTYONE_DEGREES_PROPERTIES_INLINE static inline
	The functions below are inline, so they add no name to the library.

Typedefs
typedef uint32_t	fiftyoneDegreesEvidencePropertyIndex
	Index in the properties collection to a property which is required to get evidence for another property.
typedef fiftyoneDegreesEvidencePropertyIndexArray	fiftyoneDegreesEvidenceProperties
	Array of properties which are required to fetch additional evidence for a specific property.
typedef fiftyoneDegreesPropertyAvailableArray	fiftyoneDegreesPropertiesAvailable
	Array of properties which are available in a data set.
typedef const fiftyoneDegreesString (	fiftyoneDegreesPropertiesGetMethod) (void state, uint32_t index, fiftyoneDegreesCollectionItem item)
	Returns a string for the property at the index provided or NULL if there is no property available at the index.
typedef uint32_t(*	fiftyoneDegreesEvidencePropertiesGetMethod) (void state, fiftyoneDegreesPropertyAvailable property, fiftyoneDegreesEvidenceProperties *evidenceProperties)
	Populates the evidence properties structure with the indexes of the properties required by the property provided, and returns the number of property indexes which were added.

Functions
fiftyoneDegreesPropertiesAvailable *	fiftyoneDegreesPropertiesCreate (fiftyoneDegreesPropertiesRequired properties, void state, fiftyoneDegreesPropertiesGetMethod getPropertyMethod, fiftyoneDegreesEvidencePropertiesGetMethod getEvidencePropertiesMethod)
	Creates a properties result instance for use with future property operations.
int	fiftyoneDegreesPropertiesGetPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable available, const char propertyName)
	Gets the index of the property in the source data structure from the name.
int	fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable available, const char propertyName)
	Gets the required property index of the property named, which is its place in the names the caller gave, the first if the name was given more than once.
int	fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
	Maps the required property index to the index in the source data structure.
fiftyoneDegreesString *	fiftyoneDegreesPropertiesGetNameFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
	Gets the name as a string from the required property index.
FIFTYONE_DEGREES_PROPERTIES_INLINE uint32_t	fiftyoneDegreesPropertiesGetRequiredPropertyCount (const fiftyoneDegreesPropertiesAvailable *available)
	Gets the number of required property indexes, which is the number of names the caller gave, or when the caller named no property, the number of available properties.
FIFTYONE_DEGREES_PROPERTIES_INLINE int	fiftyoneDegreesPropertiesGetAvailableIndex (const fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
	Gets the available index of the property at the required property index.
FIFTYONE_DEGREES_PROPERTIES_INLINE int	fiftyoneDegreesPropertiesGetAvailableIndexFromName (fiftyoneDegreesPropertiesAvailable available, const char propertyName)
	Gets the available index of the property named.
FIFTYONE_DEGREES_PROPERTIES_INLINE int	fiftyoneDegreesPropertiesGetPropertyIndexFromAvailableIndex (const fiftyoneDegreesPropertiesAvailable *available, int availableIndex)
	Maps the available index to the index in the source data structure.
bool	fiftyoneDegreesPropertiesIsSetHeaderAvailable (fiftyoneDegreesPropertiesAvailable *available)
	Check if the 'SetHeader' properties are included in the available required properties.
void	fiftyoneDegreesPropertiesFree (fiftyoneDegreesPropertiesAvailable *available)
	Frees the memory and resources used by the properties results previously created using the fiftyoneDegreesPropertiesCreate method.

Variables
EXTERNAL_VAR fiftyoneDegreesPropertiesRequired	fiftyoneDegreesPropertiesDefault
	The default properties required to make all possible properties available.

Typedef Documentation

◆ fiftyoneDegreesEvidencePropertiesGetMethod

typedef uint32_t(* fiftyoneDegreesEvidencePropertiesGetMethod) (void *state, fiftyoneDegreesPropertyAvailable *property, fiftyoneDegreesEvidenceProperties *evidenceProperties)

Populates the evidence properties structure with the indexes of the properties required by the property provided, and returns the number of property indexes which were added.

If the evidence properties structure is null, then this method returns the count but does not populate the structure.

Parameters

state	pointer to data which the method may need to use
property	pointer to the property to get the evidence properties for
evidenceProperties	pointer to the pre-allocated structure to populate with the evidence property indexes

Returns: the number of property indexes added to the structure. Or the number which would have been added were it not null

◆ fiftyoneDegreesPropertiesGetMethod

typedef const fiftyoneDegreesString *(* fiftyoneDegreesPropertiesGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *item)

Returns a string for the property at the index provided or NULL if there is no property available at the index.

Parameters

state	resource used to obtain the string
index	of the property
item	used to obtain a handle to the string

Returns: pointer to the string or NULL if no property available

Function Documentation

◆ fiftyoneDegreesPropertiesCreate()

fiftyoneDegreesPropertiesAvailable * fiftyoneDegreesPropertiesCreate	(	fiftyoneDegreesPropertiesRequired *	properties,
		void *	state,
		fiftyoneDegreesPropertiesGetMethod	getPropertyMethod,
		fiftyoneDegreesEvidencePropertiesGetMethod	getEvidencePropertiesMethod )

Creates a properties result instance for use with future property operations.

The available properties are in ascending order of name, and the required property index of each name given is its place among the names given.

Parameters

properties	required to be available as either a separated list of property names, an array of property names or an existing properties results structure from another data set. Valid separators include pipe, comma and space, and a run of separators separates two names. The fields are evaluated in order of existing, array and then string. The first field with a value is used. Existing results give the names they were created with.
state	pointer to state used with the get method
getPropertyMethod	method used to return the property name from a string collection
getEvidencePropertiesMethod	method used to populate the evidence properties for a property

Returns: instance of a properties result for use with future properties methods

◆ fiftyoneDegreesPropertiesFree()

void fiftyoneDegreesPropertiesFree

(

fiftyoneDegreesPropertiesAvailable *

available

)

Frees the memory and resources used by the properties results previously created using the fiftyoneDegreesPropertiesCreate method.

Parameters

available properties instance to be freed

◆ fiftyoneDegreesPropertiesGetAvailableIndex()

FIFTYONE_DEGREES_PROPERTIES_INLINE int fiftyoneDegreesPropertiesGetAvailableIndex	(	const fiftyoneDegreesPropertiesAvailable *	available,
		int	requiredPropertyIndex )

Gets the available index of the property at the required property index.

Parameters

available	properties instance
requiredPropertyIndex	index of the property in the names the caller gave, or when the caller named no property, in the available properties

Returns: 0 based available index, or -1 if the index is outside the names given or the data set does not have the property

◆ fiftyoneDegreesPropertiesGetAvailableIndexFromName()

FIFTYONE_DEGREES_PROPERTIES_INLINE int fiftyoneDegreesPropertiesGetAvailableIndexFromName	(	fiftyoneDegreesPropertiesAvailable *	available,
		const char *	propertyName )

Gets the available index of the property named.

Parameters

available	properties instance
propertyName	string containing the property name

Returns: 0 based available index, or -1 if the data set does not have the property

◆ fiftyoneDegreesPropertiesGetNameFromRequiredIndex()

fiftyoneDegreesString * fiftyoneDegreesPropertiesGetNameFromRequiredIndex	(	fiftyoneDegreesPropertiesAvailable *	available,
		int	requiredPropertyIndex )

Gets the name as a string from the required property index.

A property the data set does not have gives the name the caller gave.

Parameters

available	properties instance
requiredPropertyIndex	index of the property in the names the caller gave, or when the caller named no property, in the available properties

Returns: string representation of the property, or NULL if the index is outside the names given

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromAvailableIndex()

FIFTYONE_DEGREES_PROPERTIES_INLINE int fiftyoneDegreesPropertiesGetPropertyIndexFromAvailableIndex	(	const fiftyoneDegreesPropertiesAvailable *	available,
		int	availableIndex )

Maps the available index to the index in the source data structure.

Parameters

available	properties instance
availableIndex	index of the property in the available properties

Returns: 0 based index of the property in the source, or -1 if the index is outside the available properties

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromName()

int fiftyoneDegreesPropertiesGetPropertyIndexFromName	(	fiftyoneDegreesPropertiesAvailable *	available,
		const char *	propertyName )

Gets the index of the property in the source data structure from the name.

Parameters

available	properties instance
propertyName	string containing the property name

Returns: 0 based index of the property in the source or -1 if not available

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex()

int fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex	(	fiftyoneDegreesPropertiesAvailable *	available,
		int	requiredPropertyIndex )

Maps the required property index to the index in the source data structure.

Parameters

available	properties instance
requiredPropertyIndex	index of the property in the names the caller gave, or when the caller named no property, in the available properties

Returns: 0 based index of the property in the source, or -1 if the index is outside the names given or the data set does not have the property

◆ fiftyoneDegreesPropertiesGetRequiredPropertyCount()

FIFTYONE_DEGREES_PROPERTIES_INLINE uint32_t fiftyoneDegreesPropertiesGetRequiredPropertyCount

(

const fiftyoneDegreesPropertiesAvailable *

available

)

Gets the number of required property indexes, which is the number of names the caller gave, or when the caller named no property, the number of available properties.

Use it, rather than the count field, with fiftyoneDegreesPropertiesGetNameFromRequiredIndex and the reads that take a required property index.

Parameters

available properties instance

Returns: number of required property indexes

◆ fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName()

int fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName	(	fiftyoneDegreesPropertiesAvailable *	available,
		const char *	propertyName )

Gets the required property index of the property named, which is its place in the names the caller gave, the first if the name was given more than once.

When the caller named no property, it is the index of the property in the available properties.

Parameters

available	properties instance
propertyName	string containing the property name

Returns: 0 based required property index, or -1 if the data set does not have the property

◆ fiftyoneDegreesPropertiesIsSetHeaderAvailable()

bool fiftyoneDegreesPropertiesIsSetHeaderAvailable

(

fiftyoneDegreesPropertiesAvailable *

available

)

Check if the 'SetHeader' properties are included in the available required properties.

Parameters

available properties instance

Returns: bool whether 'SetHeader' properties are included

Variable Documentation

◆ fiftyoneDegreesPropertiesDefault

EXTERNAL_VAR fiftyoneDegreesPropertiesRequired fiftyoneDegreesPropertiesDefault

The default properties required to make all possible properties available.

Should be used to initialise a new instance of fiftyoneDegreesPropertiesRequired.

Properties Common

Detailed Description

Terms

Introduction

Creation

Free

Operation

Collaboration diagram for Properties:

Structs

Macros

Typedefs

Functions

Variables

Typedef Documentation

◆ fiftyoneDegreesEvidencePropertiesGetMethod

◆ fiftyoneDegreesPropertiesGetMethod

Function Documentation

◆ fiftyoneDegreesPropertiesCreate()

◆ fiftyoneDegreesPropertiesFree()

◆ fiftyoneDegreesPropertiesGetAvailableIndex()

◆ fiftyoneDegreesPropertiesGetAvailableIndexFromName()

◆ fiftyoneDegreesPropertiesGetNameFromRequiredIndex()

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromAvailableIndex()

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromName()

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex()

◆ fiftyoneDegreesPropertiesGetRequiredPropertyCount()

◆ fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName()

◆ fiftyoneDegreesPropertiesIsSetHeaderAvailable()

Variable Documentation

◆ fiftyoneDegreesPropertiesDefault

Properties
Common