\r\n

51Degrees Device Detection C/C++  4.4

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

Properties

Detailed Description

Structures for properties which are available, or required.

Terms

Required Property Index : the 0 based index of the property in the list of required properties. Not the same as the property index.

Property Index : the 0 based index of the property in the source used to create the required properties. Not the same as the required property index.

Results : the structure used to contain the data associated with the available required properties.

Source : the source of property names. Typically a call back method to return properties from the data structure used by the aspect engine.

Introduction

Aspect engine performance can often be improved by limiting the properties that can be returned from the engine. As this is a performance feature shared across different types of aspect engine the utility functions are stored in the common C files.

Required properties could be specified at initialisation as a character separated string, as an array of strings or from an existing set of properties already obtained from these methods. In all scenarios it is desirable to be able to query the properties and find their indexes in the source data structure using a consistent set of methods.

Creation

fiftyoneDegreesPropertiesCreate is used to create a consistent set of required properties. The structure passed must have one of the follow set.

  1. Separated string of property names. Valid separators include space, comma and pipe.
  2. An array of strings.
  3. Existing properties results from a previous creation operation. This method is used when a data set is being reloaded due to a change in the underlying data.

Creation also requires a method to retrieve the name of the properties from the underlying data source. A method pointer conforming to fiftyoneDegreesPropertiesGetMethod must be provided to retrieve the property name string item for a given property index up to the maximum count. The call back is used to avoid any hard dependency between the data structure and the properties methods.

Unlike standard collection item retrieval the properties methods will not know the underlying collection implement or reference from which the item was obtained from. Therefore the implementation of get MUST set the collection field of the collection item.

Some, or all, of the required properties may not be present in the underlying data source. Any missing properties will be ignored in the results. The get name from required index method can be used to iterate over the available properties. The number of available properties after creation can be obtained from the count field of properties results.

Whilst the property names can be provided as string(s) the property names referenced from the properties results are collection items from a strings collection. The properties methods are responsible for releasing the references to these strings when the properties results are freed.

The resulting require properties index will be in ascending order of the property name a string. As such the ordered list can be used with a binary search (divide and conquer) to quickly determine the required property index from the property name.

Free

When the properties results are finished with, the fiftyoneDegreesPropertiesFree method must be used. This will also free the collection items used to reference the property name strings using the collection field of the item to obtain the source collection. This collection must have been set by the get method used at creation.

Operation

Several methods are available which can be used to convert from an input such as a property name or required property index to a property index in the data structure. The method names are self-explanatory.

Where possible using integer property or required property indexes is preferable to the string representation of the property as this improves performance.

Collaboration diagram for Properties:

Structs

struct  fiftyoneDegreesEvidencePropertyIndexArray
Array of items of type fiftyoneDegreesEvidencePropertyIndex used to easily access and track the size of the array. More...
struct  fiftyoneDegreesPropertyAvailable
Used to access the property item quickly without the need to search. More...
struct  fiftyoneDegreesPropertyAvailableArray
Array of items of type fiftyoneDegreesPropertyAvailable used to easily access and track the size of the array. More...
struct  fiftyoneDegreesPropertiesRequired
Defines a set of properties which are required by a caller. More...

Typedefs

typedef uint32_t  fiftyoneDegreesEvidencePropertyIndex
Index in the properties collection to a property which is required to get evidence for another property.
typedef fiftyoneDegreesEvidencePropertyIndexArray  fiftyoneDegreesEvidenceProperties
Array of properties which are required to fetch additional evidence for a specific property.
typedef fiftyoneDegreesPropertyAvailableArray  fiftyoneDegreesPropertiesAvailable
Array of properties which are available in a data set. More...
typedef fiftyoneDegreesString *(*  fiftyoneDegreesPropertiesGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *item)
Returns a string for the property at the index provided or NULL if there is no property available at the index. More...
typedef uint32_t(*  fiftyoneDegreesEvidencePropertiesGetMethod) (void *state, fiftyoneDegreesPropertyAvailable *property, fiftyoneDegreesEvidenceProperties *evidenceProperties)
Populates the evidence properties structure with the indexes of the properties required by the property provided, and returns the number of property indexes which were added. More...

Functions

fiftyoneDegreesPropertiesAvailable *  fiftyoneDegreesPropertiesCreate (fiftyoneDegreesPropertiesRequired *properties, void *state, fiftyoneDegreesPropertiesGetMethod getPropertyMethod, fiftyoneDegreesEvidencePropertiesGetMethod getEvidencePropertiesMethod)
Creates a properties result instance for use with future property operations. More...
int  fiftyoneDegreesPropertiesGetPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable *available, const char *propertyName)
Gets the index of the property in the source data structure from the name. More...
int  fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable *available, const char *propertyName)
Gets the required property index in the list of all required properties from the name. More...
int  fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
Maps the required property index to the index in the source data structure. More...
fiftyoneDegreesString *  fiftyoneDegreesPropertiesGetNameFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
Gets the name as a string from the required property index. More...
bool  fiftyoneDegreesPropertiesIsSetHeaderAvailable (fiftyoneDegreesPropertiesAvailable *available)
Check if the 'SetHeader' properties are included in the available required properties. More...
void  fiftyoneDegreesPropertiesFree (fiftyoneDegreesPropertiesAvailable *available)
Frees the memory and resources used by the properties results previously created using the fiftyoneDegreesPropertiesCreate method. More...

Variables

EXTERNAL_VAR fiftyoneDegreesPropertiesRequired  fiftyoneDegreesPropertiesDefault
The default properties required to make all possible properties available. More...

Typedef Documentation

◆ fiftyoneDegreesEvidencePropertiesGetMethod

typedef uint32_t(* fiftyoneDegreesEvidencePropertiesGetMethod) (void *state, fiftyoneDegreesPropertyAvailable *property, fiftyoneDegreesEvidenceProperties *evidenceProperties)

Populates the evidence properties structure with the indexes of the properties required by the property provided, and returns the number of property indexes which were added.

If the evidence properties structure is null, then this method returns the count but does not populate the structure.

Parameters
state - pointer to data which the method may need to use
property - pointer to the property to get the evidence properties for
evidenceProperties - pointer to the pre-allocated structure to populate with the evidence property indexes
Returns
the number of property indexes added to the structure. Or the number which would have been added were it not null

◆ fiftyoneDegreesPropertiesGetMethod

typedef fiftyoneDegreesString*(* fiftyoneDegreesPropertiesGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *item)

Returns a string for the property at the index provided or NULL if there is no property available at the index.

Parameters
state - resource used to obtain the string
index - of the property
item - used to obtain a handle to the string
Returns
pointer to the string or NULL if no property available

Function Documentation

◆ fiftyoneDegreesPropertiesCreate()

fiftyoneDegreesPropertiesAvailable* fiftyoneDegreesPropertiesCreate ( fiftyoneDegreesPropertiesRequired *   properties,
void *   state,
fiftyoneDegreesPropertiesGetMethod   getPropertyMethod,
fiftyoneDegreesEvidencePropertiesGetMethod   getEvidencePropertiesMethod  
)

Creates a properties result instance for use with future property operations.

The resulting required properties will be provided in ascending order.

Parameters
properties - required to be available as either a separated list of property names, an array of property names or an existing properties results structure from another data set. Valid separators include pipe, comma and space. The fields are evaluated in order of existing, array and then string. the first field with a value is used.
state - pointer to state used with the get method
getPropertyMethod - method used to return the property name from a string collection
getEvidencePropertiesMethod - method used to populate the evidence properties for a property
Returns
instance of a properties result for use with future properties methods

◆ fiftyoneDegreesPropertiesGetNameFromRequiredIndex()

fiftyoneDegreesString* fiftyoneDegreesPropertiesGetNameFromRequiredIndex ( fiftyoneDegreesPropertiesAvailable *   available,
int   requiredPropertyIndex  
)

Gets the name as a string from the required property index.

Parameters
available - properties instance
requiredPropertyIndex - index of the property in the required properties structure
Returns
string representation of the property

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromName()

int fiftyoneDegreesPropertiesGetPropertyIndexFromName ( fiftyoneDegreesPropertiesAvailable *   available,
const char *   propertyName  
)

Gets the index of the property in the source data structure from the name.

Parameters
available - properties instance
propertyName - string containing the property name
Returns
0 based index of the property in the source or -1 if not available

◆ fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex()

int fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex ( fiftyoneDegreesPropertiesAvailable *   available,
int   requiredPropertyIndex  
)

Maps the required property index to the index in the source data structure.

Parameters
available - properties instance
requiredPropertyIndex - index of the property in the required properties structure
Returns
0 based index of the property in the source or -1 if not available

◆ fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName()

int fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName ( fiftyoneDegreesPropertiesAvailable *   available,
const char *   propertyName  
)

Gets the required property index in the list of all required properties from the name.

Parameters
available - properties instance
propertyName - string containing the property name
Returns
0 based index of the property in the required properties or -1 if not available
Examples
Hash/StronglyTyped.c.

◆ fiftyoneDegreesPropertiesIsSetHeaderAvailable()

bool fiftyoneDegreesPropertiesIsSetHeaderAvailable ( fiftyoneDegreesPropertiesAvailable *   available )

Check if the 'SetHeader' properties are included in the available required properties.

Parameters
available - properties instance
Returns
bool whether 'SetHeader' properties are included

Variable Documentation

On This Page

Generated by doxygen 1.8.15