Detailed Description

Structure returned by an engine's process method(s), containing values.

Introduction

Results are the structure returned by an engine's process method(s) and contains the values for the properties in the engine. The base structure contains only the essential element of a data set, which is needed to return values. Any engine can extend this structure to add any additional elements which may be needed to format or return values.

The data set pointer is a managed resource, meaning that while the results exist, the data set will not be freed by the resource manager. This ensures that values contained in the data set used for processing can always be returned.

First read

When the caller named the properties the data set was created with, populating the results walks the graph of each component they answer for, as fiftyoneDegreesResultsWalkWhenPopulated decides, and the call that populates them reports a walk that fails. Otherwise populating the results walks no graph. Each component the results answer for is marked pending, and the first read of one of its properties walks the component's graph against the data set the results hold. A component is walked at most once each time the results are populated, so a walk that fails is not repeated, and the component's properties then read as if it had no profile. Anything that depends on every component, such as a value made from all of them or the items of the results read directly, needs fiftyoneDegreesResultsEvaluateAll first, which walks nothing when the results walked every graph as they were populated.

Overrides

Results can hold values from the evidence that override the values of properties. A read looks for one with fiftyoneDegreesResultsGetOverrideValues before it walks the property's component, so a property with an override value is read without walking the graph, and a component whose properties are only read from overrides is never walked.

Threads

A results structure is used by one thread at a time, because reading a value writes into the results, and when no properties were named the first read of a component's property walks the component's graph. Different results can be used on different threads at once, and the resource manager they come from can be shared, unless the library is compiled with FIFTYONE_DEGREES_NO_THREADING.

Collaboration diagram for Results:

Structs
struct	fiftyoneDegreesResultsBase
	Base results structure which any processing results should extend. More...

Macros
#define	FIFTYONE_DEGREES_RESULTS_PENDING_WORDS 8
	Number of 32 bit words holding one bit for each possible component index.
#define	FIFTYONE_DEGREES_RESULTS_INLINE static inline
	Marks a function defined in this header, so that it adds no name to the libraries.

Typedefs
typedef void(*	fiftyoneDegreesResultsEvaluateMethod) (struct fiftyone_degrees_results_base_t results, byte componentIndex, fiftyoneDegreesException exception)
	Walks the graph of one component for the results, setting what a read of the component's properties needs.

Enumerations
enum	fiftyoneDegreesResultsNoValueReason { FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_DIFFERENCE , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_MATCHED_NODES , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_INVALID_PROPERTY , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULT_FOR_PROPERTY , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULTS , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_TOO_MANY_VALUES , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NULL_PROFILE , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_HIGH_RISK , FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_UNKNOWN }
	Enum containing reasons which cause a value to not be present or valid. More...

Functions
fiftyoneDegreesResultsBase *	fiftyoneDegreesResultsInit (fiftyoneDegreesResultsBase results, void dataSet)
	Initialise a set of results by setting the data set they are associated with.
FIFTYONE_DEGREES_RESULTS_INLINE void	fiftyoneDegreesResultsPendingClear (fiftyoneDegreesResultsBase *results)
	Marks every component as walked, before the results are populated again.
FIFTYONE_DEGREES_RESULTS_INLINE void	fiftyoneDegreesResultsPendingSet (fiftyoneDegreesResultsBase *results, byte componentIndex)
	Marks the component as waiting for the first read of one of its properties.
FIFTYONE_DEGREES_RESULTS_INLINE bool	fiftyoneDegreesResultsWalkWhenPopulated (const fiftyoneDegreesDataSetBase *dataSet)
	Returns true if populating the results walks the graph of each component they answer for, rather than leaving each walk to the first read of one of the component's properties.
FIFTYONE_DEGREES_RESULTS_INLINE void	fiftyoneDegreesResultsEvaluate (fiftyoneDegreesResultsBase results, byte componentIndex, fiftyoneDegreesException exception)
	Walks the component's graph if it is pending, and marks it walked whether or not the walk succeeds, so a failed walk is not repeated.
FIFTYONE_DEGREES_RESULTS_INLINE void	fiftyoneDegreesResultsEvaluateAll (fiftyoneDegreesResultsBase results, fiftyoneDegreesException exception)
	Walks every pending component in component order, stopping at the first walk that fails.
FIFTYONE_DEGREES_RESULTS_INLINE bool	fiftyoneDegreesResultsHasOverrideValue (fiftyoneDegreesResultsBase *results, uint32_t availableIndex)
	Returns true if the results hold an override value for the property, so that a read can answer without walking the property's component.
FIFTYONE_DEGREES_RESULTS_INLINE uint32_t	fiftyoneDegreesResultsGetOverrideValues (fiftyoneDegreesResultsBase results, uint32_t availableIndex, fiftyoneDegreesList values)
	Adds the override values the results hold for the property to the list.

Typedef Documentation

◆ fiftyoneDegreesResultsEvaluateMethod

typedef void(* fiftyoneDegreesResultsEvaluateMethod) (struct fiftyone_degrees_results_base_t *results, byte componentIndex, fiftyoneDegreesException *exception)

Walks the graph of one component for the results, setting what a read of the component's properties needs.

Each engine supplies its own walk.

Parameters

results	pointer to the results to walk the component for
componentIndex	index of the component in the data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Enumeration Type Documentation

◆ fiftyoneDegreesResultsNoValueReason

enum fiftyoneDegreesResultsNoValueReason

Enum containing reasons which cause a value to not be present or valid.

Enumerator
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_DIFFERENCE	The difference value is higher than the threshold, see the Pattern API.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_MATCHED_NODES	No hash nodes were matched, see the Hash API.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_INVALID_PROPERTY	The requested property does not exist, or is not a required property.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULT_FOR_PROPERTY	There is no result which contains a value for the requested property.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULTS	There are no results to get a value from.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_TOO_MANY_VALUES	There are too many values to be expressed as the requested type.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NULL_PROFILE	The results contain a null profile for the required component.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_HIGH_RISK	The match is deemed high risk of containing incorrect or misleading results.
FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_UNKNOWN	None of the above.

Examples: Hash/GettingStarted.c, and Hash/OfflineProcessing.c.

Function Documentation

◆ fiftyoneDegreesResultsEvaluate()

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluate	(	fiftyoneDegreesResultsBase *	results,
		byte	componentIndex,
		fiftyoneDegreesException *	exception )

Walks the component's graph if it is pending, and marks it walked whether or not the walk succeeds, so a failed walk is not repeated.

Called before a read of a property of the component.

Parameters

results	pointer to the results
componentIndex	index of the component in the data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

◆ fiftyoneDegreesResultsEvaluateAll()

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluateAll	(	fiftyoneDegreesResultsBase *	results,
		fiftyoneDegreesException *	exception )

Walks every pending component in component order, stopping at the first walk that fails.

Called before anything that depends on every component, such as a value made from all of them, or the items of the results read directly.

Parameters

results	pointer to the results
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Examples: Hash/MatchMetrics.c.

◆ fiftyoneDegreesResultsGetOverrideValues()

FIFTYONE_DEGREES_RESULTS_INLINE uint32_t fiftyoneDegreesResultsGetOverrideValues	(	fiftyoneDegreesResultsBase *	results,
		uint32_t	availableIndex,
		fiftyoneDegreesList *	values )

Adds the override values the results hold for the property to the list.

Each read calls this before fiftyoneDegreesResultsEvaluate, so a property with an override value is read without walking its component.

Parameters

results	pointer to the results to get the values from
availableIndex	index of the property in the available properties
values	list to add the values to

Returns: the number of values added, which is zero if there is no override value for the property

◆ fiftyoneDegreesResultsHasOverrideValue()

FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsHasOverrideValue	(	fiftyoneDegreesResultsBase *	results,
		uint32_t	availableIndex )

Returns true if the results hold an override value for the property, so that a read can answer without walking the property's component.

Parameters

results	pointer to the results to check
availableIndex	index of the property in the available properties

Returns: true if there is an override value for the property

◆ fiftyoneDegreesResultsInit()

fiftyoneDegreesResultsBase * fiftyoneDegreesResultsInit	(	fiftyoneDegreesResultsBase *	results,
		void *	dataSet )

Initialise a set of results by setting the data set they are associated with.

No component is pending, no walk is set and no override values are held.

Parameters

results	pointer to the results to initialise
dataSet	pointer to the data set which will be using the results

Returns: pointer to the initialised results

◆ fiftyoneDegreesResultsPendingClear()

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingClear

(

fiftyoneDegreesResultsBase *

results

)

Marks every component as walked, before the results are populated again.

Parameters

results pointer to the results

◆ fiftyoneDegreesResultsPendingSet()

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingSet	(	fiftyoneDegreesResultsBase *	results,
		byte	componentIndex )

Marks the component as waiting for the first read of one of its properties.

Parameters

results	pointer to the results
componentIndex	index of the component in the data set

◆ fiftyoneDegreesResultsWalkWhenPopulated()

FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsWalkWhenPopulated

(

const fiftyoneDegreesDataSetBase *

dataSet

)

Returns true if populating the results walks the graph of each component they answer for, rather than leaving each walk to the first read of one of the component's properties.

That is when the caller named the properties the data set was created with, as every graph the results need is then known before anything is read.

Parameters

dataSet pointer to the data set the results are populated from

Returns: true if populating the results walks the graphs

Results Common

Detailed Description

Introduction

First read

Overrides

Threads

Collaboration diagram for Results:

Structs

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ fiftyoneDegreesResultsEvaluateMethod

Enumeration Type Documentation

◆ fiftyoneDegreesResultsNoValueReason

Enumerator

Function Documentation

◆ fiftyoneDegreesResultsEvaluate()

◆ fiftyoneDegreesResultsEvaluateAll()

◆ fiftyoneDegreesResultsGetOverrideValues()

◆ fiftyoneDegreesResultsHasOverrideValue()

◆ fiftyoneDegreesResultsInit()

◆ fiftyoneDegreesResultsPendingClear()

◆ fiftyoneDegreesResultsPendingSet()

◆ fiftyoneDegreesResultsWalkWhenPopulated()

Results
Common