51Degrees Common C/C++  4.1

A shared functionality library that is used by 51Degrees products
Search

Evidence

Detailed Description

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);

Structs

struct  fiftyoneDegreesEvidencePrefixMap
Map of prefix strings to prefix enum values. More...
struct  fiftyoneDegreesEvidenceKeyValuePair
Evidence key value pair structure which combines the prefix, key and value. More...
struct  fiftyoneDegreesEvidenceKeyValuePairArray
Array of items of type fiftyoneDegreesEvidenceKeyValuePair used to easily access and track the size of the array. More...

Typedefs

typedef bool(*  fiftyoneDegreesEvidenceIterateMethod) (void *state, fiftyoneDegreesEvidenceKeyValuePair *pair)
Callback method used to iterate evidence key value pairs. More...

Enumerations

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
}
Evidence prefixes used to determine the category a piece of evidence belongs to. More...

Functions

EXTERNAL fiftyoneDegreesEvidenceKeyValuePairArray *  fiftyoneDegreesEvidenceCreate (uint32_t capacity)
Creates a new evidence array with the capacity requested. More...
EXTERNAL void  fiftyoneDegreesEvidenceFree (fiftyoneDegreesEvidenceKeyValuePairArray *evidence)
Frees the memory used by an evidence array. More...
EXTERNAL fiftyoneDegreesEvidenceKeyValuePair *  fiftyoneDegreesEvidenceAddString (fiftyoneDegreesEvidenceKeyValuePairArray *evidence, fiftyoneDegreesEvidencePrefix prefix, const char *field, const char *originalValue)
Adds a new entry to the evidence. More...
EXTERNAL fiftyoneDegreesEvidencePrefixMap *  fiftyoneDegreesEvidenceMapPrefix (const char *key)
Determines the evidence map prefix from the key. More...
EXTERNAL uint32_t  fiftyoneDegreesEvidenceIterate (fiftyoneDegreesEvidenceKeyValuePairArray *evidence, int prefixes, void *state, fiftyoneDegreesEvidenceIterateMethod callback)
Iterates over the evidence calling the callback method for any values that match the prefixes provided. More...

Typedef Documentation

◆ fiftyoneDegreesEvidenceIterateMethod

typedef bool(* fiftyoneDegreesEvidenceIterateMethod) (void *state, fiftyoneDegreesEvidenceKeyValuePair *pair)

Callback method used to iterate evidence key value pairs.

Parameters
state - pointer provided to the iterator
pair - evidence key value pair with the parsed value set
Returns
true if the iteration should continue otherwise false

Enumeration Type Documentation

◆ fiftyoneDegreesEvidencePrefix

enum fiftyoneDegreesEvidencePrefix

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.

Function Documentation

◆ fiftyoneDegreesEvidenceAddString()

EXTERNAL fiftyoneDegreesEvidenceKeyValuePair* fiftyoneDegreesEvidenceAddString ( fiftyoneDegreesEvidenceKeyValuePairArray *   evidence,
fiftyoneDegreesEvidencePrefix   prefix,
const char *   field,
const char *   originalValue  
)

Adds a new entry to the evidence.

The memory associated with the field and original value parameters must not be freed until after the evidence collection has been freed. This method will NOT copy the values.

Parameters
evidence - pointer to the evidence array to add the entry to
prefix - enum indicating the category the entry belongs to
field - used as the key for the entry within its prefix
originalValue - the value to be parsed

◆ fiftyoneDegreesEvidenceCreate()

EXTERNAL fiftyoneDegreesEvidenceKeyValuePairArray* fiftyoneDegreesEvidenceCreate ( uint32_t   capacity )

Creates a new evidence array with the capacity requested.

Parameters
capacity - maximum number of evidence items
Returns
pointer to the newly created array

◆ fiftyoneDegreesEvidenceFree()

EXTERNAL void fiftyoneDegreesEvidenceFree ( fiftyoneDegreesEvidenceKeyValuePairArray *   evidence )

Frees the memory used by an evidence array.

Parameters
evidence - pointer to the array to be freed

◆ fiftyoneDegreesEvidenceIterate()

EXTERNAL uint32_t fiftyoneDegreesEvidenceIterate ( fiftyoneDegreesEvidenceKeyValuePairArray *   evidence,
int   prefixes,
void *   state,
fiftyoneDegreesEvidenceIterateMethod   callback  
)

Iterates over the evidence calling the callback method for any values that match the prefixes provided.

Parameters
evidence - key value pairs including prefixes
prefixes - one or more prefix flags to return values for
state - pointer passed to the callback method
callback - method called when a matching prefix is found
Returns
the number of matching evidence keys iterated over

◆ fiftyoneDegreesEvidenceMapPrefix()

EXTERNAL fiftyoneDegreesEvidencePrefixMap* fiftyoneDegreesEvidenceMapPrefix ( const char *   key )

Determines the evidence map prefix from the key.

Parameters
key - the evidence key including the evidence prefix .i.e. header
Returns
the prefix enumeration, or NULL if one does not exist
On This Page

Generated by doxygen 1.8.15