\r\n

51Degrees Device Detection C/C++  4.4

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

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  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. More...
#define  FIFTYONE_DEGREES_HASH_DIFFERENCE   0
Default value for the difference threshold used in the default configuration.
#define  FIFTYONE_DEGREES_HASH_DRIFT   0
Default value for the drift threshold used in the default configuration.
#define  FIFTYONE_DEGREES_STRING_CACHE_SIZE   10000
Default value for the string cache size used in the default collection configuration.
#define  FIFTYONE_DEGREES_STRING_LOADED   100
Default value for the string cache loaded size used in the default collection configuration.
#define  FIFTYONE_DEGREES_NODE_CACHE_SIZE   50000
Default value for the node cache size used in the default collection configuration.
#define  FIFTYONE_DEGREES_NODE_LOADED   100
Default value for the node cache loaded size used in the default collection configuration.
#define  FIFTYONE_DEGREES_PROFILE_CACHE_SIZE   10000
Default value for the profile cache size used in the default collection configuration.
#define  FIFTYONE_DEGREES_PROFILE_LOADED   100
Default value for the profile cache loaded size used in the default collection configuration.
#define  FIFTYONE_DEGREES_VALUE_CACHE_SIZE   500
Default value for the value cache size used in the default collection configuration.
#define  FIFTYONE_DEGREES_VALUE_LOADED   0
Default value for the value cache loaded size used in the default collection configuration.
#define  FIFTYONE_DEGREES_PROPERTY_CACHE_SIZE   0
Default value for the property cache size used in the default collection configuration.
#define  FIFTYONE_DEGREES_PROPERTY_LOADED   INT_MAX
Default value for the property cache loaded size used in the default collection configuration.
#define  FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS
Macro defining the common members of a Hash result. More...

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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
void  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. More...
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. More...
void  fiftyoneDegreesResultsHashFree (fiftyoneDegreesResultsHash *results)
Frees the results structure created by the fiftyoneDegreesResultsHashCreate method. More...
bool  fiftyoneDegreesResultsHashGetHasValues (fiftyoneDegreesResultsHash *results, int requiredPropertyIndex, fiftyoneDegreesException *exception)
Gets whether or not the results provided contain valid values for the property index provided. More...
fiftyoneDegreesResultsNoValueReason  fiftyoneDegreesResultsHashGetNoValueReason (fiftyoneDegreesResultsHash *results, int requiredPropertyIndex, fiftyoneDegreesException *exception)
Gets the reason why a results does not contain valid values for a given property. More...
const char *  fiftyoneDegreesResultsHashGetNoValueReasonMessage (fiftyoneDegreesResultsNoValueReason reason)
Gets a fuller description of the reason why a value is missing. More...
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. More...
size_t  fiftyoneDegreesResultsHashGetValuesString (fiftyoneDegreesResultsHash *results, const char *propertyName, char *buffer, size_t bufferLength, const char *separator, fiftyoneDegreesException *exception)
Sets the buffer the values associated in the results for the property name. More...
size_t  fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex (fiftyoneDegreesResultsHash *results, const int requiredPropertyIndex, char *buffer, size_t bufferLength, const char *separator, fiftyoneDegreesException *exception)
Sets the buffer the values associated in the results for the property name. More...
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. More...
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. More...
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. More...
fiftyoneDegreesDataSetHash *  fiftyoneDegreesDataSetHashGet (fiftyoneDegreesResourceManager *manager)
Gets a safe reference to the Hash data set from the resource manager. More...
void  fiftyoneDegreesDataSetHashRelease (fiftyoneDegreesDataSetHash *dataSet)
Release the reference to a data set returned by the fiftyoneDegreesDataSetHashGet method. More...
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. More...
char *  fiftyoneDegreesHashGetDeviceIdFromResult (fiftyoneDegreesDataSetHash *dataSet, fiftyoneDegreesResultHash *result, char *destination, size_t size, fiftyoneDegreesException *exception)
Get the device id string from the single result provided. More...
char *  fiftyoneDegreesHashGetDeviceIdFromResults (fiftyoneDegreesResultsHash *results, char *destination, size_t size, fiftyoneDegreesException *exception)
Get the device id string from the results provided. More...

Variables

EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashInMemoryConfig
DETECTION CONFIGURATIONS. More...
EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashHighPerformanceConfig
Highest performance configuration. More...
EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashLowMemoryConfig
Low memory configuration. More...
EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashBalancedConfig
Uses caching to balance memory usage and performance. More...
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. More...
EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashDefaultConfig
Default detection configuration. More...
EXTERNAL_VAR fiftyoneDegreesConfigHash  fiftyoneDegreesHashSingleLoadedConfig
Configuration designed only for testing. More...

Macro Definition Documentation

◆ FIFTYONE_DEGREES_CACHE_CONCURRENCY

#define FIFTYONE_DEGREES_CACHE_CONCURRENCY   10

Default value for the cache concurrency used in the default configuration.

◆ FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS

#define FIFTYONE_DEGREES_RESULTS_HASH_MEMBERS
Value:
fiftyoneDegreesCollectionItem propertyItem; \
fiftyoneDegreesList values; \
fiftyoneDegreesEvidenceKeyValuePairArray* pseudoEvidence;
Device detection specific results structure which any device detection processing results should exte...
Definition: results-dd.h:74

Macro defining the common members of a Hash result.

Array of pseudo evidence

Enumeration Type Documentation

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

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 *   destination,
size_t   size,
fiftyoneDegreesException *   exception  
)

Get the device id string from the single result provided.

This contains profile ids for all components, concatenated with the separator character '-'.

Parameters
dataSet - pointer to the data set used to get the result
result - pointer to the result to get the device id of
destination - pointer to the memory to write the characters to
size - amount of memory allocated to destination
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 *   destination,
size_t   size,
fiftyoneDegreesException *   exception  
)

Get the device id string from the results provided.

This contains profile ids for all components, concatenated with the separator character '-'.

Parameters
results - pointer to the results to get the device id of
destination - pointer to the memory to write the characters to
size - amount of memory allocated to destination
exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the destination pointer

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

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

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

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 correctly

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

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

◆ 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
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 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 - number of User-Agents to be able to handle
overridesCapacity - number of properties that can be overridden, 0 to disable overrides
Returns
newly created results structure
Examples
Hash/MatchMetrics.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesResultsHashFromDeviceId()

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

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.

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

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.

Parameters
results - pointer to the results to check
requiredPropertyIndex - index in the required properties of the property to check for values of
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.

Parameters
results - pointer to the results to check
requiredPropertyIndex - index in the required properties of the property to check for values of
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.

Parameters
results - pointer to the results structure to release
requiredPropertyIndex -
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.

◆ fiftyoneDegreesResultsHashGetValuesString()

size_t fiftyoneDegreesResultsHashGetValuesString ( fiftyoneDegreesResultsHash *   results,
const char *   propertyName,
char *   buffer,
size_t   bufferLength,
const char *   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
bufferLength - 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.

◆ fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex()

size_t fiftyoneDegreesResultsHashGetValuesStringByRequiredPropertyIndex ( fiftyoneDegreesResultsHash *   results,
const int   requiredPropertyIndex,
char *   buffer,
size_t   bufferLength,
const char *   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 - required property index of for the values
buffer - character buffer allocated by the caller
bufferLength - 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 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.

◆ fiftyoneDegreesHashSingleLoadedConfig

EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashSingleLoadedConfig

Configuration designed only for testing.

This uses a loaded size of 1 in all collections to ensure all every get and release calls can be tested for items which do not exist in the root collection. This configuration is not exposed through C++ intentionally as it is only used in testing.