51Degrees Device Detection C/C++  4.5

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

Search

Documentation

Overrides

• Common

Detailed Description

Used to override properties values or an entire profile.

Introduction

Overrides are used to override property values, or an entire profile in a set of results. For example, if the screen size is not known from the HTTP headers alone, it can be fetched using JavaScript and overridden.

Creation

An array of overridable properties is created using the fiftyoneDegreesOverridePropertiesCreate method. This returns all the properties which are capable of being overridden.

An array of override value ready to be populated is created using the fiftyoneDegreesOverrideValuesCreate method. This is then ready to be added to and used to override the values in a results structure.

Extraction

Override values are extracted from an evidence structure using the fiftyoneDegreesOverridesExtractFromEvidence method. This looks through the items of evidence for any items which are overrides, then parses and adds them to the override values ready to be applied.

Add

Override values can also be added using the fiftyoneDegreesOverridesAdd or fiftyoneDegreesOverrideValuesAdd methods which add a single or multiple values respectively to the override values.

Free

Property and value overrides are freed using the fiftyoneDegreesOverridePropertiesFree and fiftyoneDegreesOverrideValuesFree methods.

Collaboration diagram for Overrides:

Structs
struct	fiftyoneDegreesOverrideProperty
	Index and pointer to a property which can be overridden. More...
struct	fiftyoneDegreesOverrideValue
	String value which should override the value for the property indicated by the required property index. More...
struct	fiftyoneDegreesOverridePropertyArray
	Array of items of type fiftyoneDegreesOverrideProperty used to easily access and track the size of the array. More...
struct	fiftyoneDegreesOverrideValueArray
	An array of properties and values to use when getting override values. More...

Typedefs
typedef fiftyoneDegreesOverridePropertyArray	fiftyoneDegreesOverridable
	Array of overridable properties.
typedef void(*	fiftyoneDegreesOverrideProfileIdMethod) (void *state, uint32_t profileId)
	Called when a profile Id has been found and should override the one found from another source such as the User-Agent.
typedef bool(*	fiftyoneDegreesOverridesFilterMethod) (void *state, uint32_t requiredPropertyIndex)
	Determines if the required property index is eligible for overriding considering the configuration of the data set.

Functions
fiftyoneDegreesOverrideValueArray *	fiftyoneDegreesOverrideValuesCreate (uint32_t capacity)
	Creates a fresh array of override values with the given capacity.
fiftyoneDegreesOverridePropertyArray *	fiftyoneDegreesOverridePropertiesCreate (fiftyoneDegreesPropertiesAvailable *available, bool prefix, void *state, fiftyoneDegreesOverridesFilterMethod filter)
	Returns a list of the evidence keys that are available to support overriding property values.
void	fiftyoneDegreesOverridePropertiesFree (fiftyoneDegreesOverridePropertyArray *properties)
	Frees the resources used by the override properties.
uint32_t	fiftyoneDegreesOverridesExtractFromEvidence (fiftyoneDegreesOverridePropertyArray *properties, fiftyoneDegreesOverrideValueArray *values, fiftyoneDegreesEvidenceKeyValuePairArray *evidence)
	Extracts override values from evidence.
bool	fiftyoneDegreesOverrideHasValueForRequiredPropertyIndex (fiftyoneDegreesOverrideValueArray *values, uint32_t requiredPropertyIndex)
	Gets whether or not the override values contain an override relating to the property identified by the required property index.
uint32_t	fiftyoneDegreesOverrideValuesAdd (fiftyoneDegreesOverrideValueArray *values, uint32_t requiredPropertyIndex, fiftyoneDegreesList *list)
	Adds values from the overrides data structure into the results.
bool	fiftyoneDegreesOverridesAdd (fiftyoneDegreesOverrideValueArray *values, int requiredPropertyIndex, const char *value)
	Add a value override to the override values array.
fiftyoneDegreesString *	fiftyoneDegreesOverrideValuesGetFirst (fiftyoneDegreesOverrideValueArray *values, uint32_t requiredPropertyIndex, fiftyoneDegreesCollectionItem *item)
	Returns the first value for the required property index or NULL of no value exists for the property index.
int	fiftyoneDegreesOverridesGetOverridingRequiredPropertyIndex (fiftyoneDegreesPropertiesAvailable *available, uint32_t requiredPropertyIndex)
	Gets the required property index of a property that MIGHT provide logic such as JavaScript or Regular Expressions that could override the value of the required property index provided.
void	fiftyoneDegreesOverrideValuesFree (fiftyoneDegreesOverrideValueArray *values)
	Frees the memory used for the override values.
void	fiftyoneDegreesOverrideValuesReset (fiftyoneDegreesOverrideValueArray *values)
	Reset override array.
void	fiftyoneDegreesOverrideProfileIds (fiftyoneDegreesEvidenceKeyValuePairArray *evidence, void *state, fiftyoneDegreesOverrideProfileIdMethod callback)
	Extracts the profile overrides from the evidence and overrides them using the override method supplied.

Typedef Documentation

◆ fiftyoneDegreesOverridable

typedef fiftyoneDegreesOverridePropertyArray fiftyoneDegreesOverridable

Array of overridable properties.

These are properties in a data set which a capable of being overridden.

◆ fiftyoneDegreesOverrideProfileIdMethod

typedef void(* fiftyoneDegreesOverrideProfileIdMethod) (void *state, uint32_t profileId)

Called when a profile Id has been found and should override the one found from another source such as the User-Agent.

Parameters

state	pointer to be used by the method
profileId	if to override

◆ fiftyoneDegreesOverridesFilterMethod

typedef bool(* fiftyoneDegreesOverridesFilterMethod) (void *state, uint32_t requiredPropertyIndex)

Determines if the required property index is eligible for overriding considering the configuration of the data set.

Parameters

state	pointer to be used by the method
requiredPropertyIndex	index of the property in the available properties structure

Returns

true if the property can be overridden, otherwise false.

Function Documentation

◆ fiftyoneDegreesOverrideHasValueForRequiredPropertyIndex()

bool fiftyoneDegreesOverrideHasValueForRequiredPropertyIndex	(	fiftyoneDegreesOverrideValueArray *	values,
		uint32_t	requiredPropertyIndex )

Gets whether or not the override values contain an override relating to the property identified by the required property index.

Note that the required property index MUST be valid when calling this method, so should be checked by the caller.

Parameters

values	pointer to the values to search in
requiredPropertyIndex	index in the required properties of the property to check for values of

Returns

true if there are override values for the requested property

◆ fiftyoneDegreesOverrideProfileIds()

void fiftyoneDegreesOverrideProfileIds	(	fiftyoneDegreesEvidenceKeyValuePairArray *	evidence,
		void *	state,
		fiftyoneDegreesOverrideProfileIdMethod	callback )

Extracts the profile overrides from the evidence and overrides them using the override method supplied.

Parameters

evidence	to extract the profile ids from
state	pointer to pass to the override method
callback	method called to override a profile id

◆ fiftyoneDegreesOverridePropertiesCreate()

fiftyoneDegreesOverridePropertyArray * fiftyoneDegreesOverridePropertiesCreate	(	fiftyoneDegreesPropertiesAvailable *	available,
		bool	prefix,
		void *	state,
		fiftyoneDegreesOverridesFilterMethod	filter )

Returns a list of the evidence keys that are available to support overriding property values.

Parameters

available	pointer to the available properties structure
prefix	true if the 51D_ prefix should be checked for in evidence
state	pointer to be used by the method
filter	pointer to a filter method which determines whether or not a property is eligible to be overridden

Returns

a new override properties array

◆ fiftyoneDegreesOverridePropertiesFree()

void fiftyoneDegreesOverridePropertiesFree

(

fiftyoneDegreesOverridePropertyArray *

properties

)

Frees the resources used by the override properties.

Parameters

properties

pointer to the properties to free

◆ fiftyoneDegreesOverridesAdd()

bool fiftyoneDegreesOverridesAdd	(	fiftyoneDegreesOverrideValueArray *	values,
		int	requiredPropertyIndex,
		const char *	value )

Add a value override to the override values array.

Where the array already holds a value for the property the new value replaces it, which needs no free item and therefore works whether or not the array is full. Where the property is new to the array and the array is full nothing is stored, the values already held are left as they are, and the status of the array is set to insufficient capacity for the caller to read.

Parameters

values	the override values array to add the value to
requiredPropertyIndex	the index in the dataset's required properties of the property to override the value of
value	the value string override

Returns

true if the value was stored, otherwise false

◆ fiftyoneDegreesOverridesExtractFromEvidence()

uint32_t fiftyoneDegreesOverridesExtractFromEvidence	(	fiftyoneDegreesOverridePropertyArray *	properties,
		fiftyoneDegreesOverrideValueArray *	values,
		fiftyoneDegreesEvidenceKeyValuePairArray *	evidence )

Extracts override values from evidence.

Every cookie and query item is read, including those that follow an item whose value could not be stored, because a later item can still replace a value the array already holds. Where a value could not be stored the status of the values array says so.

Parameters

properties	which can be overridden
values	array to populate with the override values
evidence	to extract any overrides from

Returns

the number of cookie and query evidence items read

◆ fiftyoneDegreesOverridesGetOverridingRequiredPropertyIndex()

int fiftyoneDegreesOverridesGetOverridingRequiredPropertyIndex	(	fiftyoneDegreesPropertiesAvailable *	available,
		uint32_t	requiredPropertyIndex )

Gets the required property index of a property that MIGHT provide logic such as JavaScript or Regular Expressions that could override the value of the required property index provided.

Parameters

available	list of require properties
requiredPropertyIndex	of the property to test for being overridden

Returns

the positive index of the overriding required property, or -1 it can't be overridden.

◆ fiftyoneDegreesOverrideValuesAdd()

uint32_t fiftyoneDegreesOverrideValuesAdd	(	fiftyoneDegreesOverrideValueArray *	values,
		uint32_t	requiredPropertyIndex,
		fiftyoneDegreesList *	list )

Adds values from the overrides data structure into the results.

Parameters

values	array to add the new values to
requiredPropertyIndex	of the property which the values relate to
list	to add the values to

Returns

the number of values which have been added to the list

◆ fiftyoneDegreesOverrideValuesCreate()

fiftyoneDegreesOverrideValueArray * fiftyoneDegreesOverrideValuesCreate

(

uint32_t

capacity

)

Creates a fresh array of override values with the given capacity.

The capacity is the number of properties the array can hold a value for, so a caller working from evidence needs room for the values the evidence carries and for the empty value given to each JavaScript property that measures one of them.

Parameters

capacity

the number of values the array can contain

Returns

a new array of override values

◆ fiftyoneDegreesOverrideValuesFree()

void fiftyoneDegreesOverrideValuesFree

(

fiftyoneDegreesOverrideValueArray *

values

)

Frees the memory used for the override values.

Parameters

values

to be freed

◆ fiftyoneDegreesOverrideValuesGetFirst()

fiftyoneDegreesString * fiftyoneDegreesOverrideValuesGetFirst	(	fiftyoneDegreesOverrideValueArray *	values,
		uint32_t	requiredPropertyIndex,
		fiftyoneDegreesCollectionItem *	item )

Returns the first value for the required property index or NULL of no value exists for the property index.

Parameters

values	to get the value from
requiredPropertyIndex	index of the property to get the first value of
item	to store the result in

Returns

pointer to the value or NULL if none were found

◆ fiftyoneDegreesOverrideValuesReset()

void fiftyoneDegreesOverrideValuesReset

(

fiftyoneDegreesOverrideValueArray *

values

)

Reset override array.

All existing item memory will not be freed by reset with 0s. Remaining values will be reset to default except the allocateds size. The status is returned to success, so a caller which resets the array between requests reads a status that relates to the current request only.

Parameters

values

to be reset

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