51Degrees Device Detection C/C++  4.5

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

Search

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   10
	Default value for the cache concurrency used in the default configuration.
#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	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.
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.
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.

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

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

◆ 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

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

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