Detailed Description

Common 51Degrees methods, types and macros.

Collaboration diagram for Common:

Modules

	Arrays Macros used to quickly define array structures.
	Cache Fixed size, thread safe, loading, tree based cache.
	Collection Group of related items such as strings.
	CollectionKey Group of related items such as keys.
	CollectionKeyTypes Group of related items such as collection key type constants.
	Component Component of a data set.
	Config Configuration for building data sets.
	Data Structure containing memory allocated to store a variable.
	Data Set A data file initialised in a structure.
	Date Represents a date in a data set.
	Exceptions Allow the bubbling up or errors in C.
	Synonyms Quick shortenings of common methods and types.
	File File handle pool and simple file operations e.g.
	Float IEEE Single Precision Floating Point standard implementation and methods to convert to native float type.
	Headers Common form of evidence in 51Degrees engines.
	Indices A look up structure for profile and property index to the first value associated with the property and profile.
	IP Types and methods to parse IP address strings.
	JSON JSON methods.
	List A more manageable way to store arrays.
	Memory Utility methods used to handle common memory operations such as allocating memory and freeing it, or reading through continuous memory checking for buffer over or under runs.
	Overrides Used to override properties values or an entire profile.
	Pool Pool of handles to allow safe access to multiple threads.
	Profile Profile containing a unique set of values for the properties of a single component.
	Properties Structures for properties which are available, or required.
	Property Property in a data set relating to a single component.
	Resource Manager Resources to be managed by a resource manager.
	Results Structure returned by an engine's process method(s), containing values.
	Status Status codes and messages indicating the result of an operation.
	String Byte array structures containing raw data bytes.
	TextFile Contains helper methods for accessing and using text files.
	Threading Defines multi threading macros if the FIFTYONE_DEGREES_NO_THREADING compiler directive is not explicitly requesting single threaded operation.
	Tree Implementation of the classic red black binary tree.
	Values Value of a data set relating to a property.

enum fiftyoneDegreesEvidencePrefix {
FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_STRING = 1 << 0, FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_IP_ADDRESSES = 1 << 1, FIFTYONE_DEGREES_EVIDENCE_SERVER = 1 << 2, FIFTYONE_DEGREES_EVIDENCE_QUERY = 1 << 3,
FIFTYONE_DEGREES_EVIDENCE_COOKIE = 1 << 4, FIFTYONE_DEGREES_EVIDENCE_IGNORE = 1 << 7
}

@

Contains key value pairs as evidence to be processed. More...

Enumeration Type Documentation

◆ fiftyoneDegreesEvidencePrefix

enum fiftyoneDegreesEvidencePrefix

@

Contains key value pairs as evidence to be processed.

Introduction

An Evidence structure contains key value pairs to be parsed and processed by an engine.

Items of evidence (e.g. an HTTP header) are added to the structure. The values are then parsed based on the key prefix. In the case of an HTTP header the string would simply be copied, but other types can require further parsing. Evidence items can then be accessed by engines in their parsed form, enabling simpler processing.

Creation

An evidence structure is created using the #fiftyoneDegreesEvidenceCreate method. This takes the maximum number of evidence items which the structure can store.

Prefixes

Evidence keys contain a prefix and the key within that prefix. For example, the key header.user-agent has the prefix header indicating that the second part of the key is an HTTP header name (user-agent).

Prefixes are stored as an enum value with the type of fiftyoneDegreesEvidencePrefix. The enum value of the prefix can be found for a key string by using the #fiftyoneDegreesEvidenceMapPrefix method which takes the key string as an argument, and returns the enum value.

Prefix values are defined by their bit positions such that multiple prefixes can be filtered when iterating with the #fiftyoneDegreesEvidenceIterate method. For example, to iterate over all HTTP headers and all query parameters two prefixes can be used in combination like FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_STRING | FIFTYONE_DEGREES_EVIDENCE_QUERY.

Add

An item of evidence is added to the evidence structure using the #fiftyoneDegreesEvidenceAddString method. This then parses the string value it is provided into the correct type which is determined by the prefix.

Iterate

The evidence a particular evidence structure can be iterated over using the #fiftyoneDegreesEvidenceIterate method. This takes a prefix filter (as described in the Prefixes section above), and a callback method which is called for each evidence item which matches the filter. The number of matching items is then returned.

Free

An evidence structure is freed using the #fiftyoneDegreesEvidenceFree method. It is important to note that this method does NOT free the original values which are referenced by the structure.

Usage Example

void *state;

fiftyoneDegreesEvidenceIterateMethod doSomethingToAValue;

// Create an evidence structure large enough to hold a single item of

// evidence

fiftyoneDegreesEvidenceKeyValuePairArray* evidence =

fiftyoneDegreesEvidenceCreate(1);

// Add an item of evidence which is a string

fiftyoneDegreesEvidenceAddString(

evidence,

fiftyoneDegreesEvidenceMapPrefix("header"),

"some-header-name",

"some-header-value");

// Iterate over all HTTP header evidence and call a method which does

// something to each item

int numberIterated = fiftyoneDegreesEvidenceIterate(

evidence,

FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_STRING,

state,

doSomethingToAValue);

// Free the evidence

fiftyoneDegreesEvidenceFree(evidence);

Evidence prefixes used to determine the category a piece of evidence belongs to. This will determine how the value is parsed.

Enumerator
FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_STRING	An HTTP header value.
FIFTYONE_DEGREES_EVIDENCE_HTTP_HEADER_IP_ADDRESSES	A list of IP addresses as a string to be parsed into a IP addresses collection.
FIFTYONE_DEGREES_EVIDENCE_SERVER	A server value e.g. client IP
FIFTYONE_DEGREES_EVIDENCE_QUERY	A query string parameter.
FIFTYONE_DEGREES_EVIDENCE_COOKIE	A cookie value.
FIFTYONE_DEGREES_EVIDENCE_IGNORE	The evidence is invalid and should be ignored.

51Degrees Device Detection C/C++ 4.5

Common