51Degrees Device Detection C/C++  4.1

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

Headers

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

void *state;
// Create the headers structure
false,
state,
getHeaderId);
// Get the index of a header
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

Collaboration diagram for Headers:

Structs

struct  fiftyoneDegreesHeader
Header structure containing the name and unique id. More...
struct  fiftyoneDegreesHeaderArray
Array of items of type fiftyoneDegreesHeader used to easily access and track the size of the array. More...

Macros

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

Typedefs

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. More...

Functions

size_t  fiftyoneDegreesHeadersSize (int count)
Returns the number of bytes that will be allocated for a headers structure created using the fiftyoneDegreesHeadersCreate method. More...
fiftyoneDegreesHeaders *  fiftyoneDegreesHeadersCreate (bool useUpperPrefixedHeaders, void *state, fiftyoneDegreesHeadersGetMethod get)
Creates a new headers instance configured with the unique HTTP names needed from evidence. More...
int  fiftyoneDegreesHeaderGetIndex (fiftyoneDegreesHeaders *headers, const char *httpHeaderName, size_t length)
Provides the integer index of the HTTP header name. More...
fiftyoneDegreesHeader *  fiftyoneDegreesHeadersGetHeaderFromUniqueId (fiftyoneDegreesHeaders *headers, uint32_t uniqueId)
Gets a pointer to the header in the headers structure with a unique id matching the one provided. More...
void  fiftyoneDegreesHeadersFree (fiftyoneDegreesHeaders *headers)
Frees the memory allocated by the fiftyoneDegreesHeadersCreate method. More...
bool  fiftyoneDegreesHeadersIsHttp (void *state, fiftyoneDegreesEvidenceKeyValuePair *pair)
Determines if the key of an evidence pair is an HTTP header. More...

Typedef Documentation

◆ fiftyoneDegreesHeadersGetMethod

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

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

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.

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  
)

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.

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
Returns
a new instance of fiftyoneDegreesHeaders ready to be used to filter HTTP headers.

◆ fiftyoneDegreesHeadersGetHeaderFromUniqueId()

fiftyoneDegreesHeader* fiftyoneDegreesHeadersGetHeaderFromUniqueId ( fiftyoneDegreesHeaders *   headers,
uint32_t   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,
fiftyoneDegreesEvidenceKeyValuePair *   pair  
)

Determines if the key of an evidence pair is an HTTP header.

Parameters
state - results instance to check against
pair - the evidence pair to be checked
Returns
true if the evidence relates to an HTTP header, otherwise false.

◆ fiftyoneDegreesHeadersSize()

size_t fiftyoneDegreesHeadersSize ( int   count )

Returns the number of bytes that will be allocated for a headers structure created using the fiftyoneDegreesHeadersCreate method.

Parameters
count - number of headers in the structure
Returns
number of bytes needed