\r\n

51Degrees Device Detection Varnish  4.4

A device detection module for Varnish

51Degrees VMOD Internals

Detailed Description

Macros

#define  VMODFOD_MSG_FORMAT   "vmod_fiftyonedegrees: %s\n"
Error message format.
#define  VMODFOD_PROP_NO_VALUES_MSG_FORMAT   "vmod_fiftyonedegrees: Property %s has no values (Reason: %s)\n"
Property has no values message format.
#define  VMODFOD_UNRECOGNIZED_PERF_PROFILE_MSG_FORMAT   "vmod_fiftyonedegrees: Cannot recognize the performance profile %s. Revert to DEFAULT\n"
Performance profile is not recognized.

Functions

void  privResourceFree (void *ptr)
Method used on shutdown to free the 51Degrees ResourceManager and ConfigHash. More...
int  init_function (const struct vrt_ctx *ctx, struct vmod_priv *priv, enum vcl_event_e e)
VMOD init Initialise the 51Degrees ResourceManager and ConfigHash by allocating memory ready to be allocated. More...
static unsigned  getString (const int32_t offset, char *buffer, unsigned bufferSize)
Method used to get string from the strings collection of the 51Degrees dataset. More...
VCL_STRING  vmod_get_dataset_name (const struct vrt_ctx *ctx)
VMOD function Get the name of the dataset. More...
VCL_STRING  vmod_get_dataset_format (const struct vrt_ctx *ctx)
VMOD function Get the format of the dataset. More...
VCL_STRING  vmod_get_dataset_published_date (const struct vrt_ctx *ctx)
VMOD function Get the published date of the dataset. More...
void  vmod_set_properties (const struct vrt_ctx *ctx, VCL_STRING properties)
VMOD Function Set the properties which should be initialised in the dataset. More...
void  vmod_set_delimiter (const struct vrt_ctx *ctx, VCL_STRING delimiter)
VMOD Function Set the delimiter to use when returning values for multiple properties. More...
void  vmod_set_performance_profile (const struct vrt_ctx *ctx, VCL_STRING performanceProfile)
VMOD Function Set the performance profile which dictates how Device Detection  allocates memory and manage data. More...
void  vmod_set_drift (const struct vrt_ctx *ctx, VCL_INT drift)
VMOD Function Set the drift value to allow substrings to be matched at a wider range. More...
void  vmod_set_difference (const struct vrt_ctx *ctx, VCL_INT difference)
VMOD Function Set the difference value to allow User-Agents where characters are slightly different from what is expected. More...
void  vmod_set_allow_unmatched (const struct vrt_ctx *ctx, VCL_STRING allowUnmatched)
VMOD Function Set whether unmatched result should be allowed. More...
void  vmod_set_use_performance_graph (const struct vrt_ctx *ctx, VCL_STRING usePerformanceGraph)
VMOD Function Set whether performance optimized graph should be used. More...
void  vmod_set_use_predictive_graph (const struct vrt_ctx *ctx, VCL_STRING usePredictiveGraph)
VMOD Function Set whether predictive optimized graph should be used. More...
void  vmod_set_max_concurrency (const struct vrt_ctx *ctx, VCL_INT concurrency)
VMOD Function Set the maximum number of expected concurrent requests. More...
static void  logExceptionMessage (Exception *exception)
Method used to log the exception message to the standard error. More...
static void  loadFileError (const char *filePath)
Method to print appropriate error message. More...
static void  loadFileErrorAbort (const char *filePath)
Method to print appropriate error message and then terminate. More...
static void  initConfig ()
Method used to init a ConfigHash object.
static const char *  skipComponentName (const char *headerName)
static int  getSetHeaderIndex (const char **headerNames, const char *headerName, int setHeaderCount)
static void  initSetHeaders ()
void  vmod_start (const struct vrt_ctx *ctx, VCL_STRING filePath)
VMOD Function Start the 51Degrees module using the data file provided. More...
void  vmod_reload (const struct vrt_ctx *ctx, struct vmod_reload_arg *a)
VMOD Function Reload resource manager using the input file path. More...
static int32_t  getSeparatorCount (const char *input)
Get the number of separators contained in a string. More...
static void  stringToArray (char *propertiesString, char **propertiesArray, int propertiesCount)
Populate an array of strings from a comma separated string. More...
static int  getRequiredPropertyCount (ResultsHash *results)
Method used to get the number of required properties. More...
static const char *  getRequiredPropertyName (ResultsHash *results, int index)
Method used to get the name of the required property at the given index. More...
static unsigned  writeValue (ResultsHash *results, int requiredPropertyIndex, char *p, unsigned u, bool logMissing)
Method used to obtain the required property value by using its' index. More...
unsigned  getValue (ResultsHash *results, char *requiredPropertyName, char *p, unsigned u)
Write the values for the required property to the workspace memory. More...
static unsigned  printValuesToWorkspace (char *p, unsigned u, ResultsHash *results, char **propertiesArray, int propertiesCount)
Write the values for all the requested properties to the workspace memory. More...
VCL_STRING  vmod_match_single (const struct vrt_ctx *ctx, VCL_STRING userAgent, VCL_STRING propertyInputString)
VMOD Function Match the User-Agent provided, and return the values for the properties requested for the matched device. More...
static int  getHeaderCount ()
Method to obtain the number of unique headers. More...
static const char *  getHeaderName (int headerIndex)
Method to obtain header name at a given index. More...
static char *  searchHeaders (const struct http *reqOrResp, const char *headerName)
Get the value of the header for the request or response context. More...
static void  setImportantHeaders (const struct vrt_ctx *ctx, EvidenceKeyValuePairArray *evidence)
Method to fill evidence with all available HTTP request header. More...
ResultsHash *  obtainResultsFromAvailableHeaders (const struct vrt_ctx *ctx, Exception *exception)
Obtain the results from the available headers. More...
VCL_STRING  vmod_match_all (const struct vrt_ctx *ctx, VCL_STRING propertyInputString)
VMOD Function Match the HTTP request headers, and return the values for the properties requests for the matched device. More...
static unsigned  printSetHeaderToWorkspace (char *p, unsigned u, ResultsHash *result, vmodfod_setHeader *header)
Write the values for all the set header properties to the workspace memory. More...
void  vmod_set_resp_headers (const struct vrt_ctx *ctx)
VMOD Function Set the response headers which are supported by the requesting browser. More...
VCL_STRING  vmod_evidence_used (const struct vrt_ctx *ctx)
VMOD Function Gets a list of evidence from the request which will be used by the match_all function, formatted as a JSON string. More...

Variables

vmodfod_global  global = VMODFOD_DEFAULTGLOBAL
Global structure available to the module.

Function Documentation

◆ getHeaderCount()

static int getHeaderCount ( )
static

Method to obtain the number of unique headers.

Returns
the number of unique headers

◆ getHeaderName()

static const char* getHeaderName ( int   headerIndex )
static

Method to obtain header name at a given index.

Parameters
headerIndex - the index of the header
Returns
header name at the given index

◆ getRequiredPropertyCount()

static int getRequiredPropertyCount ( ResultsHash *   results )
static

Method used to get the number of required properties.

Parameters
results -
Returns
number of required properties

◆ getRequiredPropertyName()

static const char* getRequiredPropertyName ( ResultsHash *   results,
int   index  
)
static

Method used to get the name of the required property at the given index.

Parameters
results - the match results
index - index of the target property
Returns
the required property name

◆ getSeparatorCount()

static int32_t getSeparatorCount ( const char *   input )
static

Get the number of separators contained in a string.

Separators include ',', '|', ' ', and '\t'.

Parameters
input - to search for separators
Returns
the number of separators found

◆ getString()

static unsigned getString ( const int32_t   offset,
char *   buffer,
unsigned   bufferSize  
)
static

Method used to get string from the strings collection of the 51Degrees dataset.

Parameters
offset - the offset of the string in the strings collection
buffer - the buffer to store the string
bufferSize - the size of the buffer
Returns
the number of written characters or 0 if no characters has been written.

◆ getValue()

unsigned getValue ( ResultsHash *   results,
char *   requiredPropertyName,
char *   p,
unsigned   u  
)

Write the values for the required property to the workspace memory.

Parameters
results - the results to get the values from
requiredPropertyName - name of the required property
p - pointer to the point in workspace memory to print the values
u - the length of the available memory to write to
Returns
the number of bytes written

◆ init_function()

int init_function ( const struct vrt_ctx *   ctx,
struct vmod_priv *   priv,
enum vcl_event_e   e  
)

VMOD init Initialise the 51Degrees ResourceManager and ConfigHash by allocating memory ready to be allocated.

Parameters
ctx - the context
priv - the private memory pointer for the module
e - the event identifier
Returns
return code

◆ loadFileError()

static void loadFileError ( const char *   filePath )
static

Method to print appropriate error message.

Parameters
filePath - path to the data file

◆ loadFileErrorAbort()

static void loadFileErrorAbort ( const char *   filePath )
static

Method to print appropriate error message and then terminate.

Parameters
filePath - path to the data file

◆ logExceptionMessage()

static void logExceptionMessage ( Exception *   exception )
static

Method used to log the exception message to the standard error.

Parameters
exception - the exception

◆ obtainResultsFromAvailableHeaders()

ResultsHash* obtainResultsFromAvailableHeaders ( const struct vrt_ctx *   ctx,
Exception *   exception  
)

Obtain the results from the available headers.

The results should be freed by ResultsHashFree to prevent memory leak

Parameters
ctx - the context
exception - the exception object

◆ printSetHeaderToWorkspace()

static unsigned printSetHeaderToWorkspace ( char *   p,
unsigned   u,
ResultsHash *   result,
vmodfod_setHeader *   header  
)
static

Write the values for all the set header properties to the workspace memory.

Parameters
p - pointer to the point in workspace memory to print the string
u - the length of the available memory to write to
results - the matched results to get the values from
header - the set header to get property values for
Returns
the number of bytes written

◆ printValuesToWorkspace()

static unsigned printValuesToWorkspace ( char *   p,
unsigned   u,
ResultsHash *   results,
char **   propertiesArray,
int   propertiesCount  
)
static

Write the values for all the requested properties to the workspace memory.

Parameters
p - pointer to the point in workspace memory to print the values
u - the length of the available memory to write to
results - the matched results to get the values from
propertiesArray - the array of property names to write the values of
propertiesCount - the number of properties in the array
Returns
the number of bytes written

◆ privResourceFree()

void privResourceFree ( void *   ptr )

Method used on shutdown to free the 51Degrees ResourceManager and ConfigHash.

Parameters
ptr - pointer to the allocated memory to free.

◆ searchHeaders()

static char* searchHeaders ( const struct http *   reqOrResp,
const char *   headerName  
)
static

Get the value of the header for the request or response context.

Parameters
reqOrResp - the request or response from the context (e.g. ctx->http_req)
headerName - the name of the header to get the value for
Returns
the value of the header

◆ setImportantHeaders()

static void setImportantHeaders ( const struct vrt_ctx *   ctx,
EvidenceKeyValuePairArray *   evidence  
)
static

Method to fill evidence with all available HTTP request header.

Parameters
ctx - the context
evidence - the evidence object

◆ stringToArray()

static void stringToArray ( char *   propertiesString,
char **   propertiesArray,
int   propertiesCount  
)
static

Populate an array of strings from a comma separated string.

The comma characters are replaced with null terminators to allow the array elements to point to the strings directly.

Parameters
propertiesString - the string containing property names
propertiesArray - memory allocated for the array
propertiesCount - the number of properties contained in the string
Returns
a newly allocated array pointing to the property names

◆ vmod_evidence_used()

VCL_STRING vmod_evidence_used ( const struct vrt_ctx *   ctx )

VMOD Function Gets a list of evidence from the request which will be used by the match_all function, formatted as a JSON string.

Parameters
ctx - the context to get the evidence from
Returns
the values of the evidence used by the match_all method

◆ vmod_get_dataset_format()

VCL_STRING vmod_get_dataset_format ( const struct vrt_ctx *   ctx )

VMOD function Get the format of the dataset.

Parameters
ctx - the context
Returns
format

◆ vmod_get_dataset_name()

VCL_STRING vmod_get_dataset_name ( const struct vrt_ctx *   ctx )

VMOD function Get the name of the dataset.

Parameters
ctx - the context
Returns
dataset name

◆ vmod_get_dataset_published_date()

VCL_STRING vmod_get_dataset_published_date ( const struct vrt_ctx *   ctx )

VMOD function Get the published date of the dataset.

Parameters
ctx - the context
Returns
published date

◆ vmod_match_all()

VCL_STRING vmod_match_all ( const struct vrt_ctx *   ctx,
VCL_STRING   propertyInputString  
)

VMOD Function Match the HTTP request headers, and return the values for the properties requests for the matched device.

Parameters
ctx - the context
propertyInputString - the list of property names to return the values
Returns
the values of the requested properties for the device matched with the request headers

◆ vmod_match_single()

VCL_STRING vmod_match_single ( const struct vrt_ctx *   ctx,
VCL_STRING   userAgent,
VCL_STRING   propertyInputString  
)

VMOD Function Match the User-Agent provided, and return the values for the properties requested for the matched device.

Parameters
ctx - the context (the User-Agent does not come from here in this instance, it is instead provided as an argument)
userAgent - the User-Agent string to match
propertyInputString - the list of property names to return the values
Returns
the values of the requested properties for the device matched with the supplied User-Agent

◆ vmod_reload()

void vmod_reload ( const struct vrt_ctx *   ctx,
struct vmod_reload_arg *   a  
)

VMOD Function Reload resource manager using the input file path.

If no file path is given, the original data file will be used.

Parameters
ctx - the context
a - the vmod argument which contains the file path.

◆ vmod_set_allow_unmatched()

void vmod_set_allow_unmatched ( const struct vrt_ctx *   ctx,
VCL_STRING   allowUnmatched  
)

VMOD Function Set whether unmatched result should be allowed.

Parameters
ctx - the context
allowUnmatched - the indication string (YES/NO)

◆ vmod_set_delimiter()

void vmod_set_delimiter ( const struct vrt_ctx *   ctx,
VCL_STRING   delimiter  
)

VMOD Function Set the delimiter to use when returning values for multiple properties.

Parameters
ctx - the context
delimiter - the delimiter string to use

◆ vmod_set_difference()

void vmod_set_difference ( const struct vrt_ctx *   ctx,
VCL_INT   difference  
)

VMOD Function Set the difference value to allow User-Agents where characters are slightly different from what is expected.

Parameters
ctx - the context
difference - the difference value

◆ vmod_set_drift()

void vmod_set_drift ( const struct vrt_ctx *   ctx,
VCL_INT   drift  
)

VMOD Function Set the drift value to allow substrings to be matched at a wider range.

Parameters
ctx - the context
drift - the drift value

◆ vmod_set_max_concurrency()

void vmod_set_max_concurrency ( const struct vrt_ctx *   ctx,
VCL_INT   concurrency  
)

VMOD Function Set the maximum number of expected concurrent requests.

Parameters
ctx - the context
concurrency - the maximum number of expected concurrent requests

◆ vmod_set_performance_profile()

void vmod_set_performance_profile ( const struct vrt_ctx *   ctx,
VCL_STRING   performanceProfile  
)

VMOD Function Set the performance profile which dictates how Device Detection  allocates memory and manage data.

Parameters
ctx - the context
performanceProfile - the performance profile string

◆ vmod_set_properties()

void vmod_set_properties ( const struct vrt_ctx *   ctx,
VCL_STRING   properties  
)

VMOD Function Set the properties which should be initialised in the dataset.

Parameters
ctx - the context
properties - the list of required properties

◆ vmod_set_resp_headers()

void vmod_set_resp_headers ( const struct vrt_ctx *   ctx )

VMOD Function Set the response headers which are supported by the requesting browser.

For example, client-hint headers on newer versions of Chrome.

Parameters
ctx - the context

◆ vmod_set_use_performance_graph()

void vmod_set_use_performance_graph ( const struct vrt_ctx *   ctx,
VCL_STRING   usePerformanceGraph  
)

VMOD Function Set whether performance optimized graph should be used.

Parameters
ctx - the context
usePerformanceGraph - the indication string (YES/NO)

◆ vmod_set_use_predictive_graph()

void vmod_set_use_predictive_graph ( const struct vrt_ctx *   ctx,
VCL_STRING   usePredictiveGraph  
)

VMOD Function Set whether predictive optimized graph should be used.

Parameters
ctx - the context
usePredictiveGraph - the indication string (YES/NO)

◆ vmod_start()

void vmod_start ( const struct vrt_ctx *   ctx,
VCL_STRING   filePath  
)

VMOD Function Start the 51Degrees module using the data file provided.

Parameters
ctx - the context
filePath - the path to the data file to be used

◆ writeValue()

static unsigned writeValue ( ResultsHash *   results,
int   requiredPropertyIndex,
char *   p,
unsigned   u,
bool   logMissing  
)
static

Method used to obtain the required property value by using its' index.

Parameters
results - the match results
requiredPropertyIndex - the index of the required property
p - buffer which will hold the value
u - the size of the buffer
logMissing - true if missing values should be logged
Returns
the number of characters added, excluding the null terminator
On This Page