51Degrees Device Detection C/C++  4.5

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

Search

Documentation

Headers

• Common

Detailed Description

Common form of evidence in 51Degrees engines.

Introduction

HTTP headers are a common form of evidence, so required headers have their own structure and methods. By storing the unique id of headers, storing duplicates of the same header can be avoided. Duplicates can occur as a result of different cases or prefixes e.g. User-Agent, user-agent and HTTP_user-agent are all the same header.

Creation

A header structure is created using the fiftyoneDegreesHeadersCreate method. This takes a state and a method used to extract the unique headers from the state. See the method description for more details.

Get

A header can be fetched using it's unique id with the fiftyoneDegreesHeadersGetHeaderFromUniqueId method.

The index of a header in the unique headers structure can also be fetched using the fiftyoneDegreesHeaderGetIndex method.

Free

Once a headers structure is finished with, it is released using the fiftyoneDegreesHeadersFree method.

Usage Example

fiftyoneDegreesHeadersGetMethod getHeaderId;

void *state;

// Create the headers structure

fiftyoneDegreesHeaders *headers = fiftyoneDegreesHeadersCreate(

false,

state,

getHeaderId,

exception);

// Get the index of a header

int index = fiftyoneDegreesHeaderGetIndex(

headers,

"user-agent",

strlen("user-agent"));

// Check that the header exists in the structure

if (index >= 0) {

// Do something with the header

// ...

}

// Free the headers structure

fiftyoneDegreesHeadersFree(headers);

Collaboration diagram for Headers:

Structs
struct	fiftyoneDegreesHeaderPtrArray
	Array of header indexes. More...
struct	fiftyoneDegreesHeader
	Structure for a header known to the corresponding data set. More...
struct	fiftyoneDegreesHeaderArray
	Array of Headers which should always be ordered in ascending order of fullHeaderId. More...

Macros
#define	FIFTYONE_DEGREES_PSEUDO_HEADER_SEP
#define	FIFTYONE_DEGREES_HEADERS_MEMBERS   bool expectUpperPrefixedHeaders;
	True if the headers structure should expect input header to be prefixed with 'HTTP_'.

Typedefs
typedef uint32_t	fiftyoneDegreesHeaderID
	The unique id for the header field string in the data set.
typedef fiftyoneDegreesHeader *	fiftyoneDegreesHeaderPtr
	Pointer to a header structure.
typedef fiftyoneDegreesHeaderPtrArray	fiftyoneDegreesHeaderPtrs
typedef fiftyoneDegreesHeaderArray	fiftyoneDegreesHeaders
	Array of headers used to easily access and track the size of the array.
typedef long(*	fiftyoneDegreesHeadersGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *nameItem)
	Gets the unique id and name of the header at the requested index.

Functions
fiftyoneDegreesHeaders *	fiftyoneDegreesHeadersCreate (bool useUpperPrefixedHeaders, void *state, fiftyoneDegreesHeadersGetMethod get, fiftyoneDegreesException *exception)
	Creates a new headers instance configured with the unique HTTP names needed from evidence.
int	fiftyoneDegreesHeaderGetIndex (fiftyoneDegreesHeaders *headers, const char *httpHeaderName, size_t length)
	Provides the integer index of the HTTP header name, or -1 if there is no matching header.
fiftyoneDegreesHeader *	fiftyoneDegreesHeadersGetHeaderFromUniqueId (fiftyoneDegreesHeaders *headers, fiftyoneDegreesHeaderID uniqueId)
	Gets a pointer to the header in the headers structure with a unique id matching the one provided.
void	fiftyoneDegreesHeadersFree (fiftyoneDegreesHeaders *headers)
	Frees the memory allocated by the fiftyoneDegreesHeadersCreate method.
bool	fiftyoneDegreesHeadersIsHttp (void *state, const char *field, size_t length)
	Determines if the field is an HTTP header.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_PSEUDO_HEADER_SEP

#define FIFTYONE_DEGREES_PSEUDO_HEADER_SEP

Value:

'\x1F'

Typedef Documentation

◆ fiftyoneDegreesHeaderPtr

typedef fiftyoneDegreesHeader* fiftyoneDegreesHeaderPtr

Pointer to a header structure.

Used in an array of related headers.

◆ fiftyoneDegreesHeadersGetMethod

typedef long(* fiftyoneDegreesHeadersGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *nameItem)

Gets the unique id and name of the header at the requested index.

The caller must use COLLECTION_RELEASE on nameItem when finished with the result.

Parameters

state	pointer to data used by the method
index	of the header to get
nameItem	pointer to the collection item to populate with the name of the header

Returns

unique id of the header

Function Documentation

◆ fiftyoneDegreesHeaderGetIndex()

int fiftyoneDegreesHeaderGetIndex	(	fiftyoneDegreesHeaders *	headers,
		const char *	httpHeaderName,
		size_t	length )

Provides the integer index of the HTTP header name, or -1 if there is no matching header.

Parameters

headers	structure created by fiftyoneDegreesHeadersCreate
httpHeaderName	of the header whose index is required
length	number of characters in httpHeaderName

Returns

the index of the HTTP header name, or -1 if the name does not exist

◆ fiftyoneDegreesHeadersCreate()

fiftyoneDegreesHeaders * fiftyoneDegreesHeadersCreate	(	bool	useUpperPrefixedHeaders,
		void *	state,
		fiftyoneDegreesHeadersGetMethod	get,
		fiftyoneDegreesException *	exception )

Creates a new headers instance configured with the unique HTTP names needed from evidence.

If the useUpperPrefixedHeaders flag is true then checks for the presence of HTTP headers will also include checking for HTTP_ as a prefix to the header key. If header is a pseudo header, the indices of actual headers that form this header will be constructed.

Parameters

useUpperPrefixedHeaders	true if HTTP_ prefixes should be checked
state	pointer used by getHeaderMethod to retrieve the header integer
get	used to return the HTTP header unique integer
exception

Returns

a new instance of fiftyoneDegreesHeaders ready to be used to filter HTTP headers.

◆ fiftyoneDegreesHeadersFree()

void fiftyoneDegreesHeadersFree

(

fiftyoneDegreesHeaders *

headers

)

Frees the memory allocated by the fiftyoneDegreesHeadersCreate method.

Parameters

headers

structure created by fiftyoneDegreesHeadersCreate

◆ fiftyoneDegreesHeadersGetHeaderFromUniqueId()

fiftyoneDegreesHeader * fiftyoneDegreesHeadersGetHeaderFromUniqueId	(	fiftyoneDegreesHeaders *	headers,
		fiftyoneDegreesHeaderID	uniqueId )

Gets a pointer to the header in the headers structure with a unique id matching the one provided.

If the headers structure does not contain a header with the unique id, NULL will be returned. This method assumes that the headers in the structure are unique, if they are not, then the first matching header will be returned.

Parameters

headers	pointer to the headers structure to search
uniqueId	id to search for

Returns

pointer to the matching header, or NULL

◆ fiftyoneDegreesHeadersIsHttp()

bool fiftyoneDegreesHeadersIsHttp	(	void *	state,
		const char *	field,
		size_t	length )

Determines if the field is an HTTP header.

Parameters

state	results instance to check against
field	name from the evidence pair to be checked
length	of field string

Returns

true if the evidence relates to an HTTP header, otherwise false.

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