51Degrees Device Detection C/C++  4.5

A device detection library that is used natively or by 51Degrees products

Documentation

Hash

• Device Detection
• Hash API

Detailed Description

All the functions specific to the Hash device detection API.

Collaboration diagram for Hash:

Structs
struct	fiftyoneDegreesDataSetHashHeader
	Dataset header containing information about the dataset. More...
struct	fiftyoneDegreesConfigHash
	Hash specific configuration structure. More...
struct	fiftyoneDegreesHashRootNodes
	Data structure containing the root nodes for the combination of an evidence item and a component. More...
struct	fiftyoneDegreesHashValueProfiles
	Index from each value of the properties named when the data set is initialised to the profiles holding it, so those profiles are found without reading every profile. More...
struct	fiftyoneDegreesDataSetHash
	Data set structure containing all the components used for detections. More...
struct	fiftyoneDegreesResultHash
	Singular User-Agent result returned by a Hash process method. More...
struct	fiftyoneDegreesResultHashArray
	Array of items of type fiftyoneDegreesResultHash used to easily access and track the size of the array. More...

Macros
#define	FIFTYONE_DEGREES_CACHE_CONCURRENCY   0
	Default value for the concurrency used in the default configurations, where 0 is one operation for each processor the system has.
#define	FIFTYONE_DEGREES_EVIDENCE_HIGH_ENTROPY_VALUES
	Evidence key for GetHighEntropyValues base 64 encoded JSON data.
#define	FIFTYONE_DEGREES_EVIDENCE_STRUCTURED_USER_AGENT
	Evidence key for Structured User Agents (SUA) JSON data.
#define	FIFTYONE_DEGREES_EVIDENCE_DEVICE_ID
	Evidence key for Structured User Agents (SUA) JSON data.
#define	FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS
	Macro defining the common members of a Hash result.

Typedefs
typedef fiftyoneDegreesResultHashArray	fiftyoneDegreesResultsHash
	Array of Hash results used to easily access and track the size of the array.

Enumerations
enum	fiftyoneDegreesHashMatchMethod {   FIFTYONE_DEGREES_HASH_MATCH_METHOD_NONE , FIFTYONE_DEGREES_HASH_MATCH_METHOD_PERFORMANCE , FIFTYONE_DEGREES_HASH_MATCH_METHOD_COMBINED , FIFTYONE_DEGREES_HASH_MATCH_METHOD_PREDICTIVE ,   FIFTYONE_DEGREES_HASH_MATCH_METHODS_LENGTH }
	DATA STRUCTURES. More...

Functions
size_t	fiftyoneDegreesHashSizeManagerFromFile (fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)
	EXTERNAL METHODS.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashInitManagerFromFile (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)
	Initialises the resource manager with a Hash data set resource populated from the Hash data file referred to by fileName.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, const char **indexedProperties, int indexedPropertiesCount, fiftyoneDegreesException *exception)
	Initialises the resource manager as fiftyoneDegreesHashInitManagerFromFile does, and indexes the profiles holding each value of the properties named, so that fiftyoneDegreesHashIterateProfilesForPropertyAndValue and fiftyoneDegreesHashGetProfileIdsForPropertyAndValue find them without reading every profile.
size_t	fiftyoneDegreesHashSizeManagerFromMemory (fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, long size, fiftyoneDegreesException *exception)
	Gets the total size in bytes which will be allocated when intialising a Hash resource and associated manager with the same parameters.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashInitManagerFromMemory (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, long size, fiftyoneDegreesException *exception)
	Initialises the resource manager with a Hash data set resource populated from the Hash data set pointed to by the memory parameter.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashInitManagerFromMemoryWithIndexedProperties (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, long size, const char **indexedProperties, int indexedPropertiesCount, fiftyoneDegreesException *exception)
	Initialises the resource manager as fiftyoneDegreesHashInitManagerFromMemory does, and indexes the profiles holding each value of the properties named, as fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties does.
void	fiftyoneDegreesResultsHashFromEvidence (fiftyoneDegreesResultsHash *results, fiftyoneDegreesEvidenceKeyValuePairArray *evidence, fiftyoneDegreesException *exception)
	Processes the evidence value pairs in the evidence collection and populates the result in the results structure.
void	fiftyoneDegreesResultsHashFromUserAgent (fiftyoneDegreesResultsHash *results, const char *userAgent, size_t userAgentLength, fiftyoneDegreesException *exception)
	Process a single User-Agent and populate the device offsets in the results structure.
int	fiftyoneDegreesResultsHashFromDeviceId (fiftyoneDegreesResultsHash *results, const char *deviceId, size_t deviceIdLength, fiftyoneDegreesException *exception)
	Process a single Device Id and populate the device offsets in the results structure.
fiftyoneDegreesResultsHash *	fiftyoneDegreesResultsHashCreate (fiftyoneDegreesResourceManager *manager, uint32_t userAgentCapacity, uint32_t overridesCapacity)
	Allocates a results structure containing a reference to the Hash data set managed by the resource manager provided.
void	fiftyoneDegreesResultsHashFree (fiftyoneDegreesResultsHash *results)
	Frees the results structure created by the fiftyoneDegreesResultsHashCreate method.
bool	fiftyoneDegreesResultsHashGetHasValues (fiftyoneDegreesResultsHash *results, int requiredPropertyIndex, fiftyoneDegreesException *exception)
	Gets whether or not the results provided contain valid values for the property index provided.
fiftyoneDegreesResultsNoValueReason	fiftyoneDegreesResultsHashGetNoValueReason (fiftyoneDegreesResultsHash *results, int requiredPropertyIndex, fiftyoneDegreesException *exception)
	Gets the reason why a results does not contain valid values for a given property.
const char *	fiftyoneDegreesResultsHashGetNoValueReasonMessage (fiftyoneDegreesResultsNoValueReason reason)
	Gets a fuller description of the reason why a value is missing.
fiftyoneDegreesCollectionItem *	fiftyoneDegreesResultsHashGetValues (fiftyoneDegreesResultsHash *results, int requiredPropertyIndex, fiftyoneDegreesException *exception)
	Populates the list of values in the results instance with value structure instances associated with the required property index.
size_t	fiftyoneDegreesResultsHashGetValuesString (fiftyoneDegreesResultsHash *results, const char *propertyName, char *const buffer, size_t const length, char *const separator, fiftyoneDegreesException *exception)
	Sets the buffer the values associated in the results for the property name.
size_t	fiftyoneDegreesHashGetHardwareProfileScript (const char *body, char *buffer, size_t length)
	Writes the script the client runs for a value of the JavascriptHardwareProfile property.
size_t	fiftyoneDegreesResultsHashGetValuesJson (fiftyoneDegreesResultsHash *results, char *const buffer, size_t const length, fiftyoneDegreesException *exception)
	Sets the buffer to a JSON string that represents all the available properties and values in the results.
size_t	fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex (fiftyoneDegreesResultsHash *results, const int requiredPropertyIndex, char *const buffer, size_t const length, char *const separator, fiftyoneDegreesException *exception)
	Sets the buffer the values associated in the results for the property name.
size_t	fiftyoneDegreesResultsHashGetValuesStringAllProperties (fiftyoneDegreesResultsHash *results, char *const buffer, size_t const length, char *const separator, fiftyoneDegreesException *exception)
	Sets the buffer to the values in the results of every required property index, one line for each index in order, so line i holds the values of the property at required property index i.
void	fiftyoneDegreesResultsHashGetMatchMetrics (fiftyoneDegreesResultsHash *results, fiftyoneDegreesHashMatchMethod *method, int32_t *difference, int32_t *drift, int32_t *iterations, int32_t *matchedNodes, fiftyoneDegreesException *exception)
	Gets the match metrics of the results, taken across every result.
bool	fiftyoneDegreesResultsHashGetMatchMetricsForResult (fiftyoneDegreesResultsHash *results, uint32_t resultIndex, fiftyoneDegreesHashMatchMethod *method, int32_t *difference, int32_t *drift, int32_t *iterations, int32_t *matchedNodes, fiftyoneDegreesException *exception)
	Gets the match metrics of one result, being those fiftyoneDegreesResultsHashGetMatchMetrics takes across every result.
const char *	fiftyoneDegreesResultsHashGetMatchedUserAgent (fiftyoneDegreesResultsHash *results, uint32_t resultIndex, fiftyoneDegreesException *exception)
	Gets the matched User-Agent of one result, being the evidence value its component was matched from, with each character the match did not use replaced by '_'.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashReloadManagerFromOriginalFile (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesException *exception)
	Reload the data set being used by the resource manager using the data file location which was used when the manager was created.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashReloadManagerFromFile (fiftyoneDegreesResourceManager *manager, const char *fileName, fiftyoneDegreesException *exception)
	Reload the data set being used by the resource manager using the data file location specified.
fiftyoneDegreesStatusCode	fiftyoneDegreesHashReloadManagerFromMemory (fiftyoneDegreesResourceManager *manager, void *source, long length, fiftyoneDegreesException *exception)
	Reload the data set being used by the resource manager using a data file loaded into contiguous memory.
fiftyoneDegreesDataSetHash *	fiftyoneDegreesDataSetHashGet (fiftyoneDegreesResourceManager *manager)
	Gets a safe reference to the Hash data set from the resource manager.
void	fiftyoneDegreesDataSetHashRelease (fiftyoneDegreesDataSetHash *dataSet)
	Release the reference to a data set returned by the fiftyoneDegreesDataSetHashGet method.
size_t	fiftyoneDegreesHashGetEvidenceKeys (fiftyoneDegreesDataSetHash *dataSet, char *buffer, size_t length, const char *separator)
	Writes the evidence keys the data set accepts, each with its prefix, with the separator between them.
bool	fiftyoneDegreesHashGetPublished (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesDate *date)
	Gets the date the data file in use was published, from its header.
bool	fiftyoneDegreesHashGetNextUpdate (fiftyoneDegreesResourceManager *manager, fiftyoneDegreesDate *date)
	Gets the date 51Degrees expect to publish the next data file, from the header of the data file in use.
uint32_t	fiftyoneDegreesHashIterateProfilesForPropertyAndValue (fiftyoneDegreesResourceManager *manager, const char *propertyName, const char *valueName, void *state, fiftyoneDegreesProfileIterateMethod callback, fiftyoneDegreesException *exception)
	Iterates over the profiles in the data set calling the callback method for any profiles that contain the property and value provided.
uint32_t	fiftyoneDegreesHashGetProfileIdsForPropertyAndValue (fiftyoneDegreesResourceManager *manager, const char *propertyName, const char *valueName, uint32_t *profileIds, uint32_t length, fiftyoneDegreesException *exception)
	Gets the ids of the profiles that contain the property and value provided.
char *	fiftyoneDegreesHashGetDeviceIdFromResult (fiftyoneDegreesDataSetHash *dataSet, fiftyoneDegreesResultHash *result, char *const buffer, size_t const length, fiftyoneDegreesException *exception)
	Get the device id string from the single result provided.
char *	fiftyoneDegreesHashGetDeviceIdFromResults (fiftyoneDegreesResultsHash *results, char *const buffer, size_t const length, fiftyoneDegreesException *exception)
	Get the device id string from the results provided.

Variables
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashInMemoryConfig
	DETECTION CONFIGURATIONS.
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashHighPerformanceConfig
	Highest performance configuration.
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashLowMemoryConfig
	Low memory configuration.
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashBalancedConfig
	Uses caching to balance memory usage and performance.
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashBalancedTempConfig
	Balanced configuration modified to create a temporary file copy of the source data file to avoid locking the source data file.
EXTERNAL_VAR fiftyoneDegreesConfigHash	fiftyoneDegreesHashDefaultConfig
	Default detection configuration.

Metadata
The properties of the data file, with the answers the C++ property metadata gives. Each function takes a data set from fiftyoneDegreesDataSetHashGet, which the caller holds while it reads so that every answer comes from the same data file. A property is found by its index in the data file, which counts every property the file defines, including those the data set was not created with. A function that gives text writes it into the buffer provided when it fits, and otherwise into memory the caller frees with fiftyoneDegreesFree when the pointer returned is not the buffer, as fiftyoneDegreesStoredBinaryValueToText describes.
uint32_t	fiftyoneDegreesHashGetPropertyCount (fiftyoneDegreesDataSetHash *dataSet)
	Gets the number of properties the data file defines.
int	fiftyoneDegreesHashGetPropertyIndex (fiftyoneDegreesDataSetHash *dataSet, const char *propertyName, fiftyoneDegreesException *exception)
	Gets the index of the property with the name provided, which must match exactly.
bool	fiftyoneDegreesHashGetProperty (fiftyoneDegreesDataSetHash *dataSet, uint32_t propertyIndex, uint8_t *valueType, uint8_t *componentId, uint8_t *displayOrder, bool *isMandatory, bool *isList, bool *isObsolete, bool *show, bool *showValues, uint32_t *mapCount, bool *isAvailable, int *requiredPropertyIndex, fiftyoneDegreesException *exception)
	Gets the fields of the property that are not text.
bool	fiftyoneDegreesHashGetPropertyValueIndexes (fiftyoneDegreesDataSetHash *dataSet, uint32_t propertyIndex, uint32_t *firstValueIndex, uint32_t *valueCount, long *defaultValueIndex, fiftyoneDegreesException *exception)
	Gets where the property's values are in the values collection, and which of them is its default.
char *	fiftyoneDegreesHashGetPropertyText (fiftyoneDegreesDataSetHash *dataSet, uint32_t propertyIndex, fiftyoneDegreesPropertyText text, char *buffer, size_t bufferLength, fiftyoneDegreesException *exception)
	Gets a text of the property, as fiftyoneDegreesPropertyGetText gives it.
char *	fiftyoneDegreesHashGetPropertyMapText (fiftyoneDegreesDataSetHash *dataSet, uint32_t propertyIndex, uint32_t mapIndex, char *buffer, size_t bufferLength, fiftyoneDegreesException *exception)
	Gets the name of one of the maps the property is in, as fiftyoneDegreesPropertyGetMapText gives it.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_EVIDENCE_DEVICE_ID

#define FIFTYONE_DEGREES_EVIDENCE_DEVICE_ID

Value:

(FIFTYONE_DEGREES_COMMON_COOKIE_PREFIX \

"deviceId")

Evidence key for Structured User Agents (SUA) JSON data.

◆ FIFTYONE_DEGREES_EVIDENCE_HIGH_ENTROPY_VALUES

#define FIFTYONE_DEGREES_EVIDENCE_HIGH_ENTROPY_VALUES

Value:

(FIFTYONE_DEGREES_COMMON_COOKIE_PREFIX \

"gethighentropyvalues")

Evidence key for GetHighEntropyValues base 64 encoded JSON data.

Examples

Hash/GettingStarted.c.

◆ FIFTYONE_DEGREES_EVIDENCE_STRUCTURED_USER_AGENT

#define FIFTYONE_DEGREES_EVIDENCE_STRUCTURED_USER_AGENT

Value:

(FIFTYONE_DEGREES_COMMON_COOKIE_PREFIX \

"structureduseragent")

Evidence key for Structured User Agents (SUA) JSON data.

◆ FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS

#define FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS

Value:

fiftyoneDegreesResultsDeviceDetection b; \

fiftyoneDegreesCollectionItem propertyItem; \

fiftyoneDegreesList values; \

fiftyoneDegreesEvidenceKeyValuePairArray *evidence; \

size_t evidenceBytes; \

int evidencePrefixes; \

bool profileIdsOverridden;

Macro defining the common members of a Hash result.

True if the evidence overrode the profile of a component, so that a walk applies the overrides again

Typedef Documentation

◆ fiftyoneDegreesResultsHash

typedef fiftyoneDegreesResultHashArray fiftyoneDegreesResultsHash

Array of Hash results used to easily access and track the size of the array.

The results are 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 property of a component walks the component's graph. Different results can be used on different threads at once, and the resource manager can be shared, unless the library is compiled with FIFTYONE_DEGREES_NO_THREADING.

Examples

Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

Enumeration Type Documentation

◆ fiftyoneDegreesHashMatchMethod

enum fiftyoneDegreesHashMatchMethod

DATA STRUCTURES.

Enum used to indicate which method was used to find a match for the evidence provided.

Enumerator
FIFTYONE_DEGREES_HASH_MATCH_METHODS_LENGTH	The length of the enum.

Examples

Hash/MatchMetrics.c, and Hash/MatchMetrics.cpp.

Function Documentation

◆ fiftyoneDegreesDataSetHashGet()

fiftyoneDegreesDataSetHash * fiftyoneDegreesDataSetHashGet

(

fiftyoneDegreesResourceManager *

manager

)

Gets a safe reference to the Hash data set from the resource manager.

Fetching through this method ensures that the data set it not freed or moved during the time it is in use. The data set returned by this method should be released with the fiftyoneDegreesDataSetHashRelease method.

Parameters

manager

the resource manager containing a hash data set initialised by one of the Hash data set init methods

Returns

a fixed pointer to the data set in manager

◆ fiftyoneDegreesDataSetHashRelease()

void fiftyoneDegreesDataSetHashRelease

(

fiftyoneDegreesDataSetHash *

dataSet

)

Release the reference to a data set returned by the fiftyoneDegreesDataSetHashGet method.

Doing so tell the resource manager linked to the data set that it is no longer being used.

Parameters

dataSet

pointer to the data set to release

◆ fiftyoneDegreesHashGetDeviceIdFromResult()

char * fiftyoneDegreesHashGetDeviceIdFromResult	(	fiftyoneDegreesDataSetHash *	dataSet,
		fiftyoneDegreesResultHash *	result,
		char *const	buffer,
		size_t const	length,
		fiftyoneDegreesException *	exception )

Get the device id string from the single result provided.

This contains profile ids for all components, concatenated with the separator character '-'. The result is read as it is, so call fiftyoneDegreesResultsEvaluateAll on the results it is from first.

Parameters

dataSet	pointer to the data set used to get the result
result	pointer to the result to get the device id of
buffer	pointer to the memory to write the characters to
length	amount of memory allocated to buffer
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the destination pointer

◆ fiftyoneDegreesHashGetDeviceIdFromResults()

char * fiftyoneDegreesHashGetDeviceIdFromResults	(	fiftyoneDegreesResultsHash *	results,
		char *const	buffer,
		size_t const	length,
		fiftyoneDegreesException *	exception )

Get the device id string from the results provided.

This contains profile ids for all components, concatenated with the separator character '-', so every graph not yet walked is walked first.

Parameters

results	pointer to the results to get the device id of
buffer	pointer to the memory to write the characters to
length	amount of memory allocated to buffer
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the destination pointer

◆ fiftyoneDegreesHashGetEvidenceKeys()

size_t fiftyoneDegreesHashGetEvidenceKeys	(	fiftyoneDegreesDataSetHash *	dataSet,
		char *	buffer,
		size_t	length,
		const char *	separator )

Writes the evidence keys the data set accepts, each with its prefix, with the separator between them.

The keys are listed in this order.

1. For each unique header in the data set that is not a pseudo header, a key under header. and then one under query., with HTTP_ before the header name when the configuration's usesUpperPrefixedHeaders is true. The header name is as the data set holds it.
2. For each property that can be overridden, a key under cookie. and then one under query., with 51D_ before the property name when the overrides need that prefix.
3. query.51D_deviceId, query.51D_gethighentropyvalues, query.51D_structureduseragent, cookie.51D_gethighentropyvalues, cookie.51D_structureduseragent, query.51D_ProfileIds and cookie.51D_ProfileIds.

The keys in 2 and 3 are listed only when the configuration's processSpecialEvidence is true, as the data set reads none of them otherwise.

A key that is listed more than once is written where it is first listed. Call with a NULL buffer to find the length needed, then with a buffer one longer than that.

Parameters

dataSet	the data set to list the keys of
buffer	to write the keys to, or NULL to only find their length
length	of the buffer, including room for the null terminator
separator	written between keys. A comma suits, as no HTTP header name holds one and property names are given as a comma separated list.

Returns

the number of characters the keys and separators need, not counting the null terminator. When the buffer is shorter than that plus one, it holds as many characters as fit followed by a null terminator.

◆ fiftyoneDegreesHashGetHardwareProfileScript()

size_t fiftyoneDegreesHashGetHardwareProfileScript	(	const char *	body,
		char *	buffer,
		size_t	length )

Writes the script the client runs for a value of the JavascriptHardwareProfile property.

The values the results give for that property are the bodies of the script. A body pushes the ids of the profiles it finds onto an array named profileIds, which it does not declare, and sends them nowhere. The script declares the array, then runs the body, then writes the ids, separated by '|', to the 51D_ProfileIds cookie, which the engine reads as evidence that sets the profiles. An empty or NULL body is written in the same way. Call with a NULL buffer to find the length needed, then with a buffer one longer than that.

Parameters

body	the value of the property, or NULL for an empty one
buffer	to write the script to, or NULL to only find its length
length	of the buffer, including room for the null terminator

Returns

the number of characters the script needs, not counting the null terminator. When the buffer is shorter than that plus one, it holds as many characters as fit followed by a null terminator, and a buffer of length 0 is left as it is.

◆ fiftyoneDegreesHashGetNextUpdate()

bool fiftyoneDegreesHashGetNextUpdate	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesDate *	date )

Gets the date 51Degrees expect to publish the next data file, from the header of the data file in use.

Parameters

manager	the resource manager containing a hash data set initialised by one of the Hash data set init methods
date	pointer to the date to set, to the header's date when that is valid (see fiftyoneDegreesDateIsValid), otherwise to a year, month and day of zero

Returns

true if the header holds a valid date, otherwise false

◆ fiftyoneDegreesHashGetProfileIdsForPropertyAndValue()

uint32_t fiftyoneDegreesHashGetProfileIdsForPropertyAndValue	(	fiftyoneDegreesResourceManager *	manager,
		const char *	propertyName,
		const char *	valueName,
		uint32_t *	profileIds,
		uint32_t	length,
		fiftyoneDegreesException *	exception )

Gets the ids of the profiles that contain the property and value provided.

They are the profiles fiftyoneDegreesHashIterateProfilesForPropertyAndValue iterates over, in the same order, found in the same way.

Parameters

manager	the resource manager containing a hash data set initialised by one of the Hash data set init methods
propertyName	name of the property which the value relates to
valueName	name of the property value which the profiles must contain
profileIds	array to set the profile ids in, or NULL to count them
length	number of ids the array can hold
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the number of profiles that contain the value. When this is more than length only the first length ids are set, so a larger array is needed for the rest.

◆ fiftyoneDegreesHashGetProperty()

bool fiftyoneDegreesHashGetProperty	(	fiftyoneDegreesDataSetHash *	dataSet,
		uint32_t	propertyIndex,
		uint8_t *	valueType,
		uint8_t *	componentId,
		uint8_t *	displayOrder,
		bool *	isMandatory,
		bool *	isList,
		bool *	isObsolete,
		bool *	show,
		bool *	showValues,
		uint32_t *	mapCount,
		bool *	isAvailable,
		int *	requiredPropertyIndex,
		fiftyoneDegreesException *	exception )

Gets the fields of the property that are not text.

Any of the output pointers can be NULL, and the property's name is read only when isAvailable or requiredPropertyIndex is not.

Parameters

dataSet	the data set to read
propertyIndex	index of the property
valueType	set to the #fiftyoneDegreesPropertyValueType of the property's values
componentId	set to the id of the component the property belongs to
displayOrder	set to the order to display the property in
isMandatory	set to true when the property is mandatory
isList	set to true when the property can have more than one value
isObsolete	set to true when the property is obsolete
show	set to true when the property should be shown
showValues	set to true when the property's values should be shown
mapCount	set to the number of maps the property is in, which fiftyoneDegreesHashGetPropertyMapText names
isAvailable	set to true when the data set was created with the property, so that results can hold its values
requiredPropertyIndex	set to the index the results functions take for the property, or -1 when it has none
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

true when the fields were read, otherwise false. False with no exception set means the properties collection gave nothing at the index.

◆ fiftyoneDegreesHashGetPropertyCount()

uint32_t fiftyoneDegreesHashGetPropertyCount

(

fiftyoneDegreesDataSetHash *

dataSet

)

Gets the number of properties the data file defines.

Parameters

dataSet

the data set to read

Returns

the number of properties

◆ fiftyoneDegreesHashGetPropertyIndex()

int fiftyoneDegreesHashGetPropertyIndex	(	fiftyoneDegreesDataSetHash *	dataSet,
		const char *	propertyName,
		fiftyoneDegreesException *	exception )

Gets the index of the property with the name provided, which must match exactly.

Parameters

dataSet	the data set to read
propertyName	name of the property to find
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the index of the property, or -1 when the data file has no property of that name or reading a property or a name sets the exception. A property whose name the strings collection gives nothing for is taken as the one named.

◆ fiftyoneDegreesHashGetPropertyMapText()

char * fiftyoneDegreesHashGetPropertyMapText	(	fiftyoneDegreesDataSetHash *	dataSet,
		uint32_t	propertyIndex,
		uint32_t	mapIndex,
		char *	buffer,
		size_t	bufferLength,
		fiftyoneDegreesException *	exception )

Gets the name of one of the maps the property is in, as fiftyoneDegreesPropertyGetMapText gives it.

Parameters

dataSet	the data set to read
propertyIndex	index of the property
mapIndex	the place of the map among the property's maps, less than the mapCount fiftyoneDegreesHashGetProperty gives
buffer	memory the name is written into when it fits
bufferLength	the bytes buffer holds
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the null terminated name, or NULL. NULL with no exception set means the strings collection gives nothing at the map's offset, and the metadata then leaves the map out.

◆ fiftyoneDegreesHashGetPropertyText()

char * fiftyoneDegreesHashGetPropertyText	(	fiftyoneDegreesDataSetHash *	dataSet,
		uint32_t	propertyIndex,
		fiftyoneDegreesPropertyText	text,
		char *	buffer,
		size_t	bufferLength,
		fiftyoneDegreesException *	exception )

Gets a text of the property, as fiftyoneDegreesPropertyGetText gives it.

Parameters

dataSet	the data set to read
propertyIndex	index of the property
text	which text of the property to get
buffer	memory the text is written into when it fits
bufferLength	the bytes buffer holds
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the null terminated text, or NULL when the property or the text cannot be read or written

◆ fiftyoneDegreesHashGetPropertyValueIndexes()

bool fiftyoneDegreesHashGetPropertyValueIndexes	(	fiftyoneDegreesDataSetHash *	dataSet,
		uint32_t	propertyIndex,
		uint32_t *	firstValueIndex,
		uint32_t *	valueCount,
		long *	defaultValueIndex,
		fiftyoneDegreesException *	exception )

Gets where the property's values are in the values collection, and which of them is its default.

Any of the output pointers can be NULL, and the default value is found only when defaultValueIndex is not.

Parameters

dataSet	the data set to read
propertyIndex	index of the property
firstValueIndex	set to the index of the property's first value
valueCount	set to the number of values the property has, as fiftyoneDegreesPropertyGetValueCount counts them
defaultValueIndex	set to the index of the property's default value as fiftyoneDegreesValueGetDefaultIndex finds it, or -1 when it has none
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

true when the indexes were read, otherwise false. False with no exception set means the properties collection gave nothing at the index.

◆ fiftyoneDegreesHashGetPublished()

bool fiftyoneDegreesHashGetPublished	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesDate *	date )

Gets the date the data file in use was published, from its header.

Parameters

manager	the resource manager containing a hash data set initialised by one of the Hash data set init methods
date	pointer to the date to set, to the header's date when that is valid (see fiftyoneDegreesDateIsValid), otherwise to a year, month and day of zero

Returns

true if the header holds a valid date, otherwise false

◆ fiftyoneDegreesHashInitManagerFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesHashInitManagerFromFile	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		const char *	fileName,
		fiftyoneDegreesException *	exception )

Initialises the resource manager with a Hash data set resource populated from the Hash data file referred to by fileName.

Configures the data set to operate using the configuration set in detection, collection and properties.

Parameters

manager	the resource manager to manager the share data set resource
config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
fileName	the full path to a file with read permission that contains the Hash data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set resource assign to the resource manager. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not created and the resource manager can not be used.

Examples

Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties()

fiftyoneDegreesStatusCode fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		const char *	fileName,
		const char **	indexedProperties,
		int	indexedPropertiesCount,
		fiftyoneDegreesException *	exception )

Initialises the resource manager as fiftyoneDegreesHashInitManagerFromFile does, and indexes the profiles holding each value of the properties named, so that fiftyoneDegreesHashIterateProfilesForPropertyAndValue and fiftyoneDegreesHashGetProfileIdsForPropertyAndValue find them without reading every profile.

A property is indexed whether or not it is required, and whatever the configuration. A reload indexes the same names again.

Parameters

manager	the resource manager to manage the shared data set resource
config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
fileName	the full path to a file with read permission that contains the Hash data set
indexedProperties	names of the properties to index, matched exactly, or NULL to index none. Null names and repeats are ignored, and a name the data file has no property of indexes nothing. The names are copied
indexedPropertiesCount	number of names in indexedProperties
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set resource assigned to the resource manager. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not created and the resource manager can not be used.

◆ fiftyoneDegreesHashInitManagerFromMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesHashInitManagerFromMemory	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		void *	memory,
		long	size,
		fiftyoneDegreesException *	exception )

Initialises the resource manager with a Hash data set resource populated from the Hash data set pointed to by the memory parameter.

Configures the data set to operate using the configuration set in detection and properties.

Parameters

manager	the resource manager to manager the share data set resource
config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
memory	pointer to continuous memory containing the Hash data set. If the data set is not created the memory stays with the caller, even if the configuration says to free it
size	the number of bytes that make up the Hash data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set resource assign to the resource manager. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not created and the resource manager can not be used.

◆ fiftyoneDegreesHashInitManagerFromMemoryWithIndexedProperties()

fiftyoneDegreesStatusCode fiftyoneDegreesHashInitManagerFromMemoryWithIndexedProperties	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		void *	memory,
		long	size,
		const char **	indexedProperties,
		int	indexedPropertiesCount,
		fiftyoneDegreesException *	exception )

Initialises the resource manager as fiftyoneDegreesHashInitManagerFromMemory does, and indexes the profiles holding each value of the properties named, as fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties does.

Parameters

manager	the resource manager to manage the shared data set resource
config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
memory	pointer to continuous memory containing the Hash data set. If the data set is not created the memory stays with the caller, even if the configuration says to free it
size	the number of bytes that make up the Hash data set
indexedProperties	names of the properties to index, matched exactly, or NULL to index none. Null names and repeats are ignored, and a name the data file has no property of indexes nothing. The names are copied
indexedPropertiesCount	number of names in indexedProperties
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set resource assigned to the resource manager. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not created and the resource manager can not be used.

◆ fiftyoneDegreesHashIterateProfilesForPropertyAndValue()

uint32_t fiftyoneDegreesHashIterateProfilesForPropertyAndValue	(	fiftyoneDegreesResourceManager *	manager,
		const char *	propertyName,
		const char *	valueName,
		void *	state,
		fiftyoneDegreesProfileIterateMethod	callback,
		fiftyoneDegreesException *	exception )

Iterates over the profiles in the data set calling the callback method for any profiles that contain the property and value provided.

The profiles are iterated in the order of the data file, which is ascending profile id, and each one is passed to the callback whatever the callback returns. Both names are matched exactly.

For a property named to index when the data set was initialised, with fiftyoneDegreesHashInitManagerFromFileWithIndexedProperties or fiftyoneDegreesHashInitManagerFromMemoryWithIndexedProperties, an index finds the profiles. For any other property every profile is read. Both give the same profiles.

Parameters

manager	the resource manager containing a hash data set initialised by one of the Hash data set init methods
propertyName	name of the property which the value relates to
valueName	name of the property value which the profiles must contain
state	pointer passed to the callback method
callback	method called when a matching profile is found
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns

the number of matching profiles iterated over

◆ fiftyoneDegreesHashReloadManagerFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesHashReloadManagerFromFile	(	fiftyoneDegreesResourceManager *	manager,
		const char *	fileName,
		fiftyoneDegreesException *	exception )

Reload the data set being used by the resource manager using the data file location specified.

When initialising the data, the configuration that manager was first created with is used.

If the new data file is successfully initialised, the current data set is replaced The old data will remain in memory until the last fiftyoneDegreesResultsHash which contain a reference to it are released.

This method is defined by the FIFTYONE_DEGREES_DATASET_RELOAD macro.

Parameters

manager	pointer to the resource manager to reload the data set for
fileName	path to the new data file
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded and the current one stays in use

◆ fiftyoneDegreesHashReloadManagerFromMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesHashReloadManagerFromMemory	(	fiftyoneDegreesResourceManager *	manager,
		void *	source,
		long	length,
		fiftyoneDegreesException *	exception )

Reload the data set being used by the resource manager using a data file loaded into contiguous memory.

When initialising the data, the configuration that manager was first created with is used.

If the data passed in is successfully initialised, the current data set is replaced The old data will remain in memory until the last fiftyoneDegreesResultsHash which contain a reference to it are released.

This method is defined by the FIFTYONE_DEGREES_DATASET_RELOAD macro.

Parameters

manager	pointer to the resource manager to reload the data set for
source	pointer to the memory location where the new data file is stored
length	of the data in memory
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded and the current one stays in use

◆ fiftyoneDegreesHashReloadManagerFromOriginalFile()

fiftyoneDegreesStatusCode fiftyoneDegreesHashReloadManagerFromOriginalFile	(	fiftyoneDegreesResourceManager *	manager,
		fiftyoneDegreesException *	exception )

Reload the data set being used by the resource manager using the data file location which was used when the manager was created.

When initialising the data, the configuration that manager was first created with is used.

If the new data file is successfully initialised, the current data set is replaced The old data will remain in memory until the last fiftyoneDegreesResultsHash which contain a reference to it are released.

This method is defined by the FIFTYONE_DEGREES_DATASET_RELOAD macro.

Parameters

manager	pointer to the resource manager to reload the data set for
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded and the current one stays in use

◆ fiftyoneDegreesHashSizeManagerFromFile()

size_t fiftyoneDegreesHashSizeManagerFromFile	(	fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		const char *	fileName,
		fiftyoneDegreesException *	exception )

EXTERNAL METHODS.

Gets the total size in bytes which will be allocated when intialising a Hash resource and associated manager with the same parameters. If any of the configuration options prevent the memory from being constant (i.e. more memory may be allocated at process time) then zero is returned.

Parameters

config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
fileName	the full path to a file with read permission that contains the Hash data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the total number of bytes needed to initialise a Hash resource and associated manager with the configuration provided or zero

◆ fiftyoneDegreesHashSizeManagerFromMemory()

size_t fiftyoneDegreesHashSizeManagerFromMemory	(	fiftyoneDegreesConfigHash *	config,
		fiftyoneDegreesPropertiesRequired *	properties,
		void *	memory,
		long	size,
		fiftyoneDegreesException *	exception )

Gets the total size in bytes which will be allocated when intialising a Hash resource and associated manager with the same parameters.

If any of the configuration options prevent the memory from being constant (i.e. more memory may be allocated at process time) then zero is returned.

Parameters

config	configuration for the operation of the data set, or NULL if default detection configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the Hash data file should be available for consumption
memory	pointer to continuous memory containing the Hash data set, which stays with the caller
size	the number of bytes that make up the Hash data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h. Holds the status if the data set could not be initialised, for example from memory that is short or rejected, and the number returned then means nothing.

Returns

the total number of bytes needed to initialise a Hash resource and associated manager with the configuration provided or zero

◆ fiftyoneDegreesResultsHashCreate()

fiftyoneDegreesResultsHash * fiftyoneDegreesResultsHashCreate	(	fiftyoneDegreesResourceManager *	manager,
		uint32_t	userAgentCapacity,
		uint32_t	overridesCapacity )

Allocates a results structure containing a reference to the Hash data set managed by the resource manager provided.

The referenced data set will be kept active until the results structure is freed. The number of results allocated might be bigger to hold additional values returned from internal process. e.g. Client Hints support.

Parameters

manager	pointer to the resource manager which manages a Hash data set
userAgentCapacity	deprecated and ignored. Retained only so that integrations built against the pre-4.5 API (e.g. the HAProxy 51degrees addon, which still passes it) continue to compile unchanged. Results are now sized by the number of components determined at initialisation.
overridesCapacity	0 to disable overrides, any other number to enable them. The list is sized at the number of properties the data set allows evidence to override, which is as many as a set of results can need, or at this number where that is larger, so a caller processing evidence does not have to work the size out for itself.

Returns

newly created results structure

Examples

Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesResultsHashFree()

void fiftyoneDegreesResultsHashFree

(

fiftyoneDegreesResultsHash *

results

)

Frees the results structure created by the fiftyoneDegreesResultsHashCreate method.

When freeing, the reference to the Hash data set resource is released.

Parameters

results

pointer to the results structure to release

Examples

Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesResultsHashFromDeviceId()

int fiftyoneDegreesResultsHashFromDeviceId	(	fiftyoneDegreesResultsHash *	results,
		const char *	deviceId,
		size_t	deviceIdLength,
		fiftyoneDegreesException *	exception )

Process a single Device Id and populate the device offsets in the results structure.

Any component still to be walked from an earlier population of the results is walked first, so the device id's profiles replace what the walk sets.

Parameters

results	preallocated results structure to populate
deviceId	string to process
deviceIdLength	of the deviceId string
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

number of profiles that were valid in the device id provided.

◆ fiftyoneDegreesResultsHashFromEvidence()

void fiftyoneDegreesResultsHashFromEvidence	(	fiftyoneDegreesResultsHash *	results,
		fiftyoneDegreesEvidenceKeyValuePairArray *	evidence,
		fiftyoneDegreesException *	exception )

Processes the evidence value pairs in the evidence collection and populates the result in the results structure.

The result shape is a deterministic function of the data set, not of how many evidence pairs are supplied. One result item is produced per available component (results->count == componentsAvailableCount when every available component resolves from the evidence, as it does for a User-Agent). Adding a redundant, lower-precedence pair that resolves to the same value (for example both 'query.user-agent' and 'header.user-agent') therefore does not change the number or layout of result items. This is the single detection entry point; ResultsHashFromUserAgent is a thin wrapper over it.

Each available component with evidence for one of its headers takes a result, in component order. When the caller named the properties the data set was created with, the graph of each of those components is walked here, so no read walks a graph and the results keep no copy of the evidence. Otherwise no graph is walked here. The evidence is copied into the results, and a component's graph is walked the first time one of its properties is read. A device id in the evidence sets every profile here, and profile overrides and default profiles are applied as they are once every graph has been walked, so the answers do not depend on what is read first. The evidence can be freed once this returns. Code that reads the result items directly, such as their match metrics, calls fiftyoneDegreesResultsEvaluateAll first.

The 'query' and 'cookie' evidence key prefixes are used to get values which dynamically override values returned from device detection. 'query' prefixes are also used in preference to 'header' for HTTP header values that are provided by the application rather than the calling device. 'query.51D_deviceId' special evidence key has the highest priority and allows to retrieve the designated device by its 'deviceId'. 'deviceId' value is obtained as a property in the device detection results and may be stored and used later to retrieve the same device. In case provided 'query.51D_deviceId' value is invalid or does not match any device the other provided evidence will be considered.

Parameters

results	preallocated results structure to populate containing a pointer to an initialised resource manager
evidence	to process containing parsed or unparsed values
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

◆ fiftyoneDegreesResultsHashFromUserAgent()

void fiftyoneDegreesResultsHashFromUserAgent	(	fiftyoneDegreesResultsHash *	results,
		const char *	userAgent,
		size_t	userAgentLength,
		fiftyoneDegreesException *	exception )

Process a single User-Agent and populate the device offsets in the results structure.

This is a thin convenience wrapper: the User-Agent is wrapped in a single 'header.user-agent' evidence pair and passed to fiftyoneDegreesResultsHashFromEvidence, so the result shape is identical to processing the same User-Agent as evidence (one item per available component, not a single coalesced item). The User-Agent can be freed once this returns, as the results either walk every graph they need with it here or copy it.

Parameters

results	preallocated results structure to populate
userAgent	string to process
userAgentLength	of the User-Agent string
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Examples

Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesResultsHashGetHasValues()

bool fiftyoneDegreesResultsHashGetHasValues	(	fiftyoneDegreesResultsHash *	results,
		int	requiredPropertyIndex,
		fiftyoneDegreesException *	exception )

Gets whether or not the results provided contain valid values for the property index provided.

When no properties were named, the first read of a property of a component walks the component's graph, unless the property has an override value or the evidence overrides the component's profile. A failure to read the graph from the data file is reported by that read, and the component is not walked again until the results are next populated, so its properties then read as if it had no profile.

Parameters

results	pointer to the results to check
requiredPropertyIndex	index of the property in the names given when the data set was created, which a reload does not change. With no names given it is the index in the available properties, which a reload can change, so look it up from the name for each data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

true if there are valid values in the results for the property index provided

◆ fiftyoneDegreesResultsHashGetMatchedUserAgent()

const char * fiftyoneDegreesResultsHashGetMatchedUserAgent	(	fiftyoneDegreesResultsHash *	results,
		uint32_t	resultIndex,
		fiftyoneDegreesException *	exception )

Gets the matched User-Agent of one result, being the evidence value its component was matched from, with each character the match did not use replaced by '_'.

It is recorded only when the updateMatchedUserAgent option is set, and holds at most maxMatchedUserAgentLength characters. Every graph not yet walked is walked first, as the walk of a component's graph sets the matched User-Agent of its result.

Parameters

results	pointer to the results to get the User-Agent from, or NULL
resultIndex	index of the result, less than the number of results
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the matched User-Agent, which stays valid until the results are populated again or freed, or NULL when the results are NULL, the index is not that of a result, a walk fails or none was recorded

Examples

Hash/MatchMetrics.c.

◆ fiftyoneDegreesResultsHashGetMatchMetrics()

void fiftyoneDegreesResultsHashGetMatchMetrics	(	fiftyoneDegreesResultsHash *	results,
		fiftyoneDegreesHashMatchMethod *	method,
		int32_t *	difference,
		int32_t *	drift,
		int32_t *	iterations,
		int32_t *	matchedNodes,
		fiftyoneDegreesException *	exception )

Gets the match metrics of the results, taken across every result.

The results hold one result for each component that had evidence, and the walk of a component's graph sets the metrics of its result, so every graph not yet walked is walked first. The method is the highest any result used, and the difference, drift, iterations and matched nodes are each the sum of every result's. Each is zero, and the method none, when the results are NULL, hold no result or a walk fails.

Parameters

results	pointer to the results to get the metrics of, or NULL
method	set to the highest method any result used, or NULL if not needed
difference	set to the total difference in hash code values between the matched substrings and those of the evidence, or NULL if not needed
drift	set to the sum, over the results, of the largest number of characters a matched substring was from where it was expected, or NULL if not needed
iterations	set to the total number of graph nodes visited, or NULL if not needed
matchedNodes	set to the total number of hash nodes matched in the evidence, or NULL if not needed
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Examples

Hash/MatchMetrics.c.

◆ fiftyoneDegreesResultsHashGetMatchMetricsForResult()

bool fiftyoneDegreesResultsHashGetMatchMetricsForResult	(	fiftyoneDegreesResultsHash *	results,
		uint32_t	resultIndex,
		fiftyoneDegreesHashMatchMethod *	method,
		int32_t *	difference,
		int32_t *	drift,
		int32_t *	iterations,
		int32_t *	matchedNodes,
		fiftyoneDegreesException *	exception )

Gets the match metrics of one result, being those fiftyoneDegreesResultsHashGetMatchMetrics takes across every result.

Every graph not yet walked is walked first, so the answer does not depend on what was read before. Each is zero, and the method none, when the results are NULL, the index is not that of a result or a walk fails.

Parameters

results	pointer to the results to get the metrics of, or NULL
resultIndex	index of the result, less than the number of results
method	set to the method the result used, or NULL if not needed
difference	set to the result's difference, or NULL if not needed
drift	set to the result's drift, or NULL if not needed
iterations	set to the result's iterations, or NULL if not needed
matchedNodes	set to the result's matched nodes, or NULL if not needed
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

true if the metrics set are the result's, or false if they are the zeros given when there is no such result or a walk fails

◆ fiftyoneDegreesResultsHashGetNoValueReason()

fiftyoneDegreesResultsNoValueReason fiftyoneDegreesResultsHashGetNoValueReason	(	fiftyoneDegreesResultsHash *	results,
		int	requiredPropertyIndex,
		fiftyoneDegreesException *	exception )

Gets the reason why a results does not contain valid values for a given property.

When no properties were named, the first read of a property of a component walks the component's graph, unless the evidence overrides the component's profile. Then, when unmatched results are not allowed, every graph still to be walked is walked, as the reason depends on the results the walks of other components set. A failure to read a graph from the data file is reported by that read, and the component is not walked again until the results are next populated, so its properties then read as if it had no profile.

Parameters

results	pointer to the results to check
requiredPropertyIndex	index of the property in the names given when the data set was created, which a reload does not change. With no names given it is the index in the available properties, which a reload can change, so look it up from the name for each data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

enum indicating why a valid value cannot be returned by the results

◆ fiftyoneDegreesResultsHashGetNoValueReasonMessage()

const char * fiftyoneDegreesResultsHashGetNoValueReasonMessage

(

fiftyoneDegreesResultsNoValueReason

reason

)

Gets a fuller description of the reason why a value is missing.

Parameters

reason

enum of the reason for the missing value

Returns

full description for the reason

◆ fiftyoneDegreesResultsHashGetValues()

fiftyoneDegreesCollectionItem * fiftyoneDegreesResultsHashGetValues	(	fiftyoneDegreesResultsHash *	results,
		int	requiredPropertyIndex,
		fiftyoneDegreesException *	exception )

Populates the list of values in the results instance with value structure instances associated with the required property index.

When the results are released then the value items will be released. There is no need for the caller to release the collection item returned. The fiftyoneDegreesResultsHashGetValueString method should be used to get the string representation of the value. When no properties were named, the first read of a property of a component walks the component's graph, unless the property has an override value or the evidence overrides the component's profile. A failure to read the graph from the data file is reported by that read, and the component is not walked again until the results are next populated, so its properties then read as if it had no profile.

Parameters

results	pointer to the results structure to release
requiredPropertyIndex	index of the property in the names given when the data set was created, which a reload does not change. With no names given it is the index in the available properties, which a reload can change, so look it up from the name for each data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

a pointer to the first value item

Examples

Hash/StronglyTyped.c.

◆ fiftyoneDegreesResultsHashGetValuesJson()

size_t fiftyoneDegreesResultsHashGetValuesJson	(	fiftyoneDegreesResultsHash *	results,
		char *const	buffer,
		size_t const	length,
		fiftyoneDegreesException *	exception )

Sets the buffer to a JSON string that represents all the available properties and values in the results.

Each property is read as fiftyoneDegreesResultsHashGetValues reads it, so when no properties were named the graph of each component is walked by the first read of one of its properties.

Parameters

results	pointer to the results structure to release
buffer	character buffer allocated by the caller
length	of the character buffer
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the number of characters available for values. May be larger than bufferLength if the buffer is not long enough to return the result.

◆ fiftyoneDegreesResultsHashGetValuesString()

size_t fiftyoneDegreesResultsHashGetValuesString	(	fiftyoneDegreesResultsHash *	results,
		const char *	propertyName,
		char *const	buffer,
		size_t const	length,
		char *const	separator,
		fiftyoneDegreesException *	exception )

Sets the buffer the values associated in the results for the property name.

Parameters

results	pointer to the results structure to release
propertyName	name of the property to be used with the values
buffer	character buffer allocated by the caller
length	of the character buffer
separator	string to be used to separate multiple values if available
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the number of characters available for values. May be larger than bufferLength if the buffer is not long enough to return the result.

◆ fiftyoneDegreesResultsHashGetValuesStringAllProperties()

size_t fiftyoneDegreesResultsHashGetValuesStringAllProperties	(	fiftyoneDegreesResultsHash *	results,
		char *const	buffer,
		size_t const	length,
		char *const	separator,
		fiftyoneDegreesException *	exception )

Sets the buffer to the values in the results of every required property index, one line for each index in order, so line i holds the values of the property at required property index i.

The line of a property the data set does not have is empty.

Parameters

results	pointer to the results structure to release
buffer	character buffer allocated by the caller
length	of the character buffer
separator	string to be used to separate multiple values if available
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the number of characters available for values. May be larger than length if the buffer is not long enough to return the result.

◆ fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex()

size_t fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex	(	fiftyoneDegreesResultsHash *	results,
		const int	requiredPropertyIndex,
		char *const	buffer,
		size_t const	length,
		char *const	separator,
		fiftyoneDegreesException *	exception )

Sets the buffer the values associated in the results for the property name.

Parameters

results	pointer to the results structure to release
requiredPropertyIndex	index of the property in the names given when the data set was created, which a reload does not change. With no names given it is the index in the available properties, which a reload can change, so look it up from the name for each data set
buffer	character buffer allocated by the caller
length	of the character buffer
separator	string to be used to separate multiple values if available
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the number of characters available for values. May be larger than bufferLength if the buffer is not long enough to return the result.

Variable Documentation

◆ fiftyoneDegreesHashBalancedConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashBalancedConfig

Uses caching to balance memory usage and performance.

A connection is maintained to the source data file to load data into caches when required. As the cache is loaded, memory will increase until the cache capacity is reached. The components, maps, properties and root nodes are held in memory. The concurrency of each collection must be set to the maximum number of concurrent operations to optimize file reads. This is the default configuration. In this configuration, both the performance and predictive graphs are enabled, as performance is not as big of a concern in this configuration, so falling back to the more predictive graph if nothing is found on the first pass can be afforded.

◆ fiftyoneDegreesHashBalancedTempConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashBalancedTempConfig

Balanced configuration modified to create a temporary file copy of the source data file to avoid locking the source data file.

In this configuration, both the performance and predictive graphs are enabled, as performance is not as big of a concern in this configuration, so falling back to the more predictive graph if nothing is found on the first pass can be afforded.

◆ fiftyoneDegreesHashDefaultConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashDefaultConfig

Default detection configuration.

This configures the data set to not create a temp file, make no allowance for drift and difference and record the matched User-Agent substrings. In this configuration, both the performance and predictive graphs are enabled, as performance is not as big of a concern in this configuration, so falling back to the more predictive graph if nothing is found on the first pass can be afforded.

Examples

Hash/GettingStarted.cpp, Hash/MatchMetrics.cpp, Hash/MetaData.cpp, Hash/ReloadFromFile.cpp, and Hash/StronglyTyped.cpp.

◆ fiftyoneDegreesHashHighPerformanceConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashHighPerformanceConfig

Highest performance configuration.

Loads all the data into memory and does not maintain a connection to the source data file used to build the data set. The concurrency setting is ignored as there are no critical sections with this configuration. In this configuration, only the performance optimised graph is enabled for processing to give the fastest operation.

It sets loadRequiredPropertiesOnly, so when the required properties name some but not all of the properties in the data file, only the values they read and the strings those values use are kept in memory, and the rest of the values and strings read from the data file.

◆ fiftyoneDegreesHashInMemoryConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashInMemoryConfig

DETECTION CONFIGURATIONS.

Configuration to be used where the data set is being created using a buffer in memory and concepts like caching are not required. The concurrency setting is ignored as there are no critical sections with this configuration. In this configuration, only the performance optimised graph is enabled for processing to give the fastest operation.

◆ fiftyoneDegreesHashLowMemoryConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashLowMemoryConfig

Low memory configuration.

A connection is maintained to the source data file used to build the data set and used to load data into memory when required. No caching is used resulting in the lowest memory footprint at the expense of performance. The concurrency of each collection must be set to the maximum number of concurrent operations to optimize file reads. In this configuration, both the performance and predictive graphs are enabled, as performance is not as big of a concern in this configuration, so falling back to the more predictive graph if nothing is found on the first pass can be afforded.

Have a data or code question? Get in touch and explore subscription options.