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

Values

Detailed Description

Value of a data set relating to a property.

Introduction

A Value is stored in a values collection and contains the meta data for a specific value of a property in a data set.

Get

A value can be fetched from a values collection in one of two ways:

By Index : the fiftyoneDegreesValueGet method return the value at a specified index. This provides a way to access a value at a known index, or iterate over all values.

By Name : if the index of a value is not known, then the value can be fetched using the fiftyoneDegreesValueGetByName method to find the value in a values collection. This requires that the property the value relates to is also known, as values are only unique within the values which relate to a single property. For example "True" could be a value of many properties.

Collaboration diagram for Values:

Structs

struct  fiftyoneDegreesValue
 Value structure containing meta data relating to the value. More...

Macros

#define FIFTYONE_DEGREES_VALUE_IS_MASKED(v)
 Macro to check if a Value's urlOffsetOrWeight field carries a masked weight.

Functions

const fiftyoneDegreesStoredBinaryValue * fiftyoneDegreesValueGetContent (const fiftyoneDegreesCollection *strings, const fiftyoneDegreesValue *value, fiftyoneDegreesPropertyValueType storedValueType, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Returns the contents of the value using the item provided.
const fiftyoneDegreesString * fiftyoneDegreesValueGetName (const fiftyoneDegreesCollection *strings, const fiftyoneDegreesValue *value, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Returns the string name of the value using the item provided.
const fiftyoneDegreesString * fiftyoneDegreesValueGetDescription (const fiftyoneDegreesCollection *strings, const fiftyoneDegreesValue *value, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Returns the string description of the value using the item provided.
const fiftyoneDegreesString * fiftyoneDegreesValueGetUrl (const fiftyoneDegreesCollection *strings, const fiftyoneDegreesValue *value, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Returns the string URL of the value using the item provided.
const fiftyoneDegreesValue * fiftyoneDegreesValueGet (const fiftyoneDegreesCollection *values, uint32_t valueIndex, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Gets the value for the requested index from the collection provided.
const fiftyoneDegreesValue * fiftyoneDegreesValueGetByNameAndType (const fiftyoneDegreesCollection *values, const fiftyoneDegreesCollection *strings, const fiftyoneDegreesProperty *property, fiftyoneDegreesPropertyValueType storedValueType, const char *valueName, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Get the value for the requested name from the collection provided.
const fiftyoneDegreesValue * fiftyoneDegreesValueGetByName (const fiftyoneDegreesCollection *values, const fiftyoneDegreesCollection *strings, const fiftyoneDegreesProperty *property, const char *valueName, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
 Get the value for the requested name from the collection provided.
long fiftyoneDegreesValueGetIndexByNameAndType (const fiftyoneDegreesCollection *values, const fiftyoneDegreesCollection *strings, const fiftyoneDegreesProperty *property, fiftyoneDegreesPropertyValueType storedValueType, const char *valueName, fiftyoneDegreesException *exception)
 Get index of the value for the requested name from the collection provided.
long fiftyoneDegreesValueGetIndexByName (fiftyoneDegreesCollection *values, fiftyoneDegreesCollection *strings, fiftyoneDegreesProperty *property, const char *valueName, fiftyoneDegreesException *exception)
 Get index of the value for the requested name from the collection provided.
char * fiftyoneDegreesValueGetText (const fiftyoneDegreesCollection *strings, const fiftyoneDegreesCollection *propertyTypes, const fiftyoneDegreesValue *value, uint8_t decimalPlaces, char *buffer, size_t bufferLength, fiftyoneDegreesException *exception)
 Gets the text of the value's name as the metadata gives it.
char * fiftyoneDegreesValueGetDefaultText (const fiftyoneDegreesCollection *values, const fiftyoneDegreesCollection *strings, const fiftyoneDegreesCollection *propertyTypes, const fiftyoneDegreesProperty *property, char *buffer, size_t bufferLength, fiftyoneDegreesException *exception)
 Gets the text the metadata gives as the property's default value.
long fiftyoneDegreesValueGetDefaultIndex (const fiftyoneDegreesCollection *values, const fiftyoneDegreesCollection *strings, const fiftyoneDegreesCollection *propertyTypes, const fiftyoneDegreesProperty *property, fiftyoneDegreesException *exception)
 Gets the index in the values collection of the value the metadata gives as the property's default.
bool fiftyoneDegreesValueIsWeighted (const fiftyoneDegreesValue *value)
 Returns true if the value carries a masked weight.
uint16_t fiftyoneDegreesValueGetWeight (const fiftyoneDegreesValue *value)
 Gets the weight from a Value record as a uint16_t (0–65535), or 0 if the value is not weighted.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_VALUE_IS_MASKED

#define FIFTYONE_DEGREES_VALUE_IS_MASKED ( v)
Value:
((((uint32_t)((v)->urlOffsetOrWeight)) & 0xFFFF0000u) == 0xFF000000u)

Macro to check if a Value's urlOffsetOrWeight field carries a masked weight.

A value is weighted when (urlOffsetOrWeight & 0xFFFF0000) == 0xFF000000. This is distinct from -1 (0xFFFFFFFF, "no URL" sentinel) and from valid non-negative URL offsets.

Function Documentation

◆ fiftyoneDegreesValueGet()

const fiftyoneDegreesValue * fiftyoneDegreesValueGet ( const fiftyoneDegreesCollection * values,
uint32_t valueIndex,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Gets the value for the requested index from the collection provided.

Parameters
valuescollection to get the value from
valueIndexindex of the value to get
itemto store the value in
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
pointer to the value or NULL

◆ fiftyoneDegreesValueGetByName()

const fiftyoneDegreesValue * fiftyoneDegreesValueGetByName ( const fiftyoneDegreesCollection * values,
const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesProperty * property,
const char * valueName,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Get the value for the requested name from the collection provided.

Parameters
valuescollection to get the value from
stringscollection containing the value names
propertythat the value relates to
valueNamename of the value to get
itemto store the value in
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
pointer to the value or NULL if it does not exist

◆ fiftyoneDegreesValueGetByNameAndType()

const fiftyoneDegreesValue * fiftyoneDegreesValueGetByNameAndType ( const fiftyoneDegreesCollection * values,
const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesProperty * property,
fiftyoneDegreesPropertyValueType storedValueType,
const char * valueName,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Get the value for the requested name from the collection provided.

Parameters
valuescollection to get the value from
stringscollection containing the value names
propertythat the value relates to
storedValueTypeformat of byte array representation.
valueNamename of the value to get
itemto store the value in
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
pointer to the value or NULL if it does not exist

◆ fiftyoneDegreesValueGetContent()

const fiftyoneDegreesStoredBinaryValue * fiftyoneDegreesValueGetContent ( const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesValue * value,
fiftyoneDegreesPropertyValueType storedValueType,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Returns the contents of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters
stringscollection of strings retrieved by offsets.
valuestructure for the name required.
storedValueTypeformat of byte array representation.
itemused to store the resulting string in.
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
a pointer to a contents in the collection item data structure.

◆ fiftyoneDegreesValueGetDefaultIndex()

long fiftyoneDegreesValueGetDefaultIndex ( const fiftyoneDegreesCollection * values,
const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesCollection * propertyTypes,
const fiftyoneDegreesProperty * property,
fiftyoneDegreesException * exception )

Gets the index in the values collection of the value the metadata gives as the property's default.

The text fiftyoneDegreesValueGetDefaultText gives is searched for among the property's values, each compared as the type propertyTypes gives the property by its name. So a default that is not among the property's values has none, and a property with no default value index has the value with an empty name when it has one.

Parameters
valuescollection containing the property's values
stringscollection containing the value names
propertyTypescollection of the type each property's values are stored as, or NULL when every value is stored as a string
propertythe property to find the default value of
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the 0 based index of the value in the values collection, or -1 when the property has no such value or a value, a type or a name cannot be read

◆ fiftyoneDegreesValueGetDefaultText()

char * fiftyoneDegreesValueGetDefaultText ( const fiftyoneDegreesCollection * values,
const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesCollection * propertyTypes,
const fiftyoneDegreesProperty * property,
char * buffer,
size_t bufferLength,
fiftyoneDegreesException * exception )

Gets the text the metadata gives as the property's default value.

This is the name of the value at the property's default value index, written as fiftyoneDegreesValueGetText writes it with a number written to #FIFTYONE_DEGREES_MAX_DOUBLE_DECIMAL_PLACES places. Those are the most places the search in fiftyoneDegreesValueGetDefaultIndex writes a number to, so a default stored with more places than the metadata shows for a value is still found. A property with no default value index has an empty text. A default that is read but cannot be written gives NULL rather than an empty text, so it is not taken for a value with an empty name. The text is written into buffer when it fits, and otherwise into memory the caller frees, as fiftyoneDegreesStoredBinaryValueToText describes.

Parameters
valuescollection containing the property's values
stringscollection containing the value names
propertyTypescollection of the type each property's values are stored as, or NULL when every value is stored as a string
propertythe property to get the default value text of
buffermemory the text is written into when it fits
bufferLengththe bytes buffer holds
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the null terminated text, or NULL when the default value, its type or its name cannot be read or written

◆ fiftyoneDegreesValueGetDescription()

const fiftyoneDegreesString * fiftyoneDegreesValueGetDescription ( const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesValue * value,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Returns the string description of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters
stringscollection of strings retrieved by offsets.
valuestructure for the description required.
itemused to store the resulting string in.
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
a pointer to a string in the collection item data structure, or to an empty string if the value has no description.

◆ fiftyoneDegreesValueGetIndexByName()

long fiftyoneDegreesValueGetIndexByName ( fiftyoneDegreesCollection * values,
fiftyoneDegreesCollection * strings,
fiftyoneDegreesProperty * property,
const char * valueName,
fiftyoneDegreesException * exception )

Get index of the value for the requested name from the collection provided.

Parameters
valuescollection to get the value from
stringscollection containing the value names
propertythat the value relates to
valueNamename of the value to get
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the 0 based index of the item if found, otherwise -1

◆ fiftyoneDegreesValueGetIndexByNameAndType()

long fiftyoneDegreesValueGetIndexByNameAndType ( const fiftyoneDegreesCollection * values,
const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesProperty * property,
fiftyoneDegreesPropertyValueType storedValueType,
const char * valueName,
fiftyoneDegreesException * exception )

Get index of the value for the requested name from the collection provided.

Parameters
valuescollection to get the value from
stringscollection containing the value names
propertythat the value relates to
storedValueTypeformat of byte array representation
valueNamename of the value to get
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the 0 based index of the item if found, otherwise -1

◆ fiftyoneDegreesValueGetName()

const fiftyoneDegreesString * fiftyoneDegreesValueGetName ( const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesValue * value,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Returns the string name of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters
stringscollection of strings retrieved by offsets.
valuestructure for the name required.
itemused to store the resulting string in.
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
a pointer to a string in the collection item data structure.

◆ fiftyoneDegreesValueGetText()

char * fiftyoneDegreesValueGetText ( const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesCollection * propertyTypes,
const fiftyoneDegreesValue * value,
uint8_t decimalPlaces,
char * buffer,
size_t bufferLength,
fiftyoneDegreesException * exception )

Gets the text of the value's name as the metadata gives it.

The name is read as the type the value's property is stored as, which propertyTypes gives by the value's property index, and a number is written to at most decimalPlaces places after the point. A data set that stores every value as a string has no property types and passes NULL. The text is written into buffer when it fits, and otherwise into memory the caller frees, as fiftyoneDegreesStoredBinaryValueToText describes. A name the strings collection gives no value for has an empty text. So does a name that is read but cannot be written, such as an IP address of a length no address has or an area of an unknown geometry, and no exception is then set.

Parameters
stringscollection containing the value names
propertyTypescollection of the type each property's values are stored as, or NULL when every value is stored as a string
valuethe value to get the text of
decimalPlacesthe most places to write after the decimal point
buffermemory the text is written into when it fits
bufferLengththe bytes buffer holds
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the null terminated text, or NULL when the type or the name cannot be read or memory cannot be allocated

◆ fiftyoneDegreesValueGetUrl()

const fiftyoneDegreesString * fiftyoneDegreesValueGetUrl ( const fiftyoneDegreesCollection * strings,
const fiftyoneDegreesValue * value,
fiftyoneDegreesCollectionItem * item,
fiftyoneDegreesException * exception )

Returns the string URL of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters
stringscollection of strings retrieved by offsets.
valuestructure for the URL required.
itemused to store the resulting string in.
exceptionpointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
a pointer to a string in the collection item data structure, to an empty string if the value has no URL, or NULL if the field is negative as it is when it holds a weight.

◆ fiftyoneDegreesValueGetWeight()

uint16_t fiftyoneDegreesValueGetWeight ( const fiftyoneDegreesValue * value)

Gets the weight from a Value record as a uint16_t (0–65535), or 0 if the value is not weighted.

The weight is stored in the lower 2 bytes of urlOffsetOrWeight when the upper 2 bytes match the 0xFF00 mask. To convert to a proportion: (double)weight / UINT16_MAX

Parameters
valuethe value to get the weight from
Returns
the weight (0–65535 range), or 0 if not weighted

◆ fiftyoneDegreesValueIsWeighted()

bool fiftyoneDegreesValueIsWeighted ( const fiftyoneDegreesValue * value)

Returns true if the value carries a masked weight.

A value is weighted when (urlOffsetOrWeight & 0xFFFF0000) == 0xFF000000. This is distinct from -1 (0xFFFFFFFF, "no URL" sentinel) and from valid non-negative URL offsets.

Parameters
valuethe value to check
Returns
true if the value carries a masked weight, false otherwise

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