◆ EVIDENCE_KEY_VALUE_MEMBERS
| #define EVIDENCE_KEY_VALUE_MEMBERS struct fiftyone_degrees_array_fiftyoneDegreesEvidenceKeyValuePair_t* pseudoEvidence; |
The pseudo 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
// Add an item of evidence which is a string
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(
state,
doSomethingToAValue);
// Free the evidence
Collaboration diagram for 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...
|
Macros
| #define | EVIDENCE_KEY_VALUE_MEMBERS struct fiftyone_degrees_array_fiftyoneDegreesEvidenceKeyValuePair_t* pseudoEvidence;
The pseudo evidence. 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
Macro Definition Documentation
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
Evidence prefixes used to determine the category a piece of evidence belongs to.
This will determine how the value is parsed.
Function Documentation
◆ fiftyoneDegreesEvidenceAddString()
| 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()
| 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()
| void fiftyoneDegreesEvidenceFree | ( | fiftyoneDegreesEvidenceKeyValuePairArray * | evidence | ) |
Frees the memory used by an evidence array.
- Parameters
-
- evidence - pointer to the array to be freed
◆ fiftyoneDegreesEvidenceIterate()
| 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.
If there are pseudo evidence, this will also iterate through them and perform the callback on each.
- 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()
| 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
◆ fiftyoneDegreesEvidencePrefixString()
| const char* fiftyoneDegreesEvidencePrefixString | ( | fiftyoneDegreesEvidencePrefix | prefix | ) |
Get the prefix string of an evidence prefix.
- Parameters
-
- prefix - the evidence prefix enumeration
- Returns
- null terminated string value of the prefix, including a dot separator