#
# This Original Work is copyright of 51 Degrees Mobile Experts Limited.
# Copyright 2020 51 Degrees Mobile Experts Limited, 5 Charlotte Close,
# Caversham, Reading, Berkshire, United Kingdom RG4 7BY.
#
# This Original Work is licensed under the European Union Public Licence (EUPL) 
# v.1.2 and is subject to its terms as set out below.
#
# If a copy of the EUPL was not distributed with this file, You can obtain
# one at https://opensource.org/licenses/EUPL-1.2.
#
# The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
# amended by the European Commission) shall be deemed incompatible for
# the purposes of the Work and the provisions of the compatibility
# clause in Article 5 of the EUPL shall not apply.
# 
# If using the Work as, or as part of, a network application, by 
# including the attribution notice(s) required under Article 5 of the EUPL
# in the end user terms of the application under an appropriate heading, 
# such notice(s) shall fulfill the requirements of that article.
#

$Module fiftyonedegrees 4 51Degrees Device Detection VMOD

DESCRIPTION
===========

Prototype 51Degrees device detection module for Varnish 6.0

Implements the 51Degrees match functionality as a VMOD.
Initialise the data set with
fiftyonedegrees.start(datafilepath),
then get a match property from a requesting device with
fiftyonedegrees.match_*(propertyname).

$Function VOID start(STRING filePath)

Return value
	VOID
Description
	Initialises the 51Degrees resource manager with the data file path
	provided.
Example
        ::

                fiftyonedegrees.start("/path/to/51Degrees.dat");

$Function VOID reload([STRING filePath])

Return value
	VOID
Description
	Reload the data set being used by the resource manager by using
	the given data file path. If no data file path is given, the original
	file path will be used. The data set is reloaded with the configuration
	when the resource manager was first initialised.

$Function STRING match_all(STRING properties)

Return value
	STRING The value of the requested property or properties for the
	matched device. Multiple values for the name property are separated
	with "|", and values for different properties are separated by the
	delimiter set with set_delimiter or "," by default.
Description
	Returns the values(s) of property provided for the requesting device
	using all important HTTP headers. Multiple properties should be
	separated with a comma.
Example
	::

		set req.http.X-IsMobile = fiftyonedegrees.match_all("IsMobile");

$Function STRING match_single(STRING userAgent, STRING properties)

Return value
	STRING The value of the requested property or properties for the
	matched device. Multiple values for the same property are separated
	with "|", and values for different properties are separated by the
	delimiter set with set_delimiter or "," by default.
Description
	Returns the value of property provided for the requesting device
	using the User-Agent provided. Multiple properties should be
	separated with a comma.
Example
	::

		set req.http.X-IsMobile = fiftyonedegrees.match_single(req.http.user-agent, "IsMobile");

$Function STRING evidence_used()

Return value
	STRING List of evidence from the request which will be used by the
	match_all function.
Description
	Gets the evidence used for matching.
Example
	::

		set evidence = fiftyonedegrees.evidence_used();
		
$Function VOID set_resp_headers()

Description
	Set the response headers which are supported by the requesting browser. For example,
	client-hint headers on newer versions of Chrome.
Example
	::

		fiftyonedegrees.set_resp_headers();

$Function VOID set_properties(STRING properties)

Description
	Limits the properties which are initialised to the ones set
	in this function. The function takes a comma separted lisst of
	properties.
Example
	::

		fiftyonedegrees.set_properties("IsMobile,BrowserName");

$Function VOID set_delimiter(STRING delimiter)

Description
	Sets the delimiter to use when returning values for multiple properties.
	If not set, then a comma is used by default.
Example
	::

		fiftyonedegrees.set_delimiter("/");

$Function VOID set_performance_profile(STRING performanceProfile)

Descripton
	Dictates how device detection allocates memory and manage data.
	The possible profiles are "DEFAULT", "IN_MEMORY", "HIGH_PERFORMANCE",
	"LOW_MEMORY", "BALANCED". By default the "DEFAULT" profile is used.
Example
	::

		fiftyonedegrees.set_performance_profile("IN_MEMORY")

$Function VOID set_drift(INT drift)

Description
	Set the drift value to allow the sub-strings to be matched in
	a wider range of character positions. By default the value is 0.
Example
	::

		fiftyonedegrees.set_drift(10)

$Function VOID set_difference(INT difference)

Description
	Set the difference value to allow User-Agents where characters are
	slightly different from what is expected. By default the value is 0.
Example
	::

		fiftyonedegrees.set_difference(10)

$Function VOID set_max_concurrency(INT concurrency)

Description
	Set the expected concurrent detection requests. This will allow
	the internal caches, used by the detection process to be constructed
	in a way that will allow this level of concurrency. This should
	be the expected frequency of number of worker threads being deployed.
	This will override what being set by the performance profile.
Example
	::

		fiftyeonedegrees.set_max_concurrency(10)

$Function VOID set_allow_unmatched(STRING allowUnmatched)

Description
	Set whether unmatched node should be allowed. Potential values are
	"YES" and "NO". If this value is set to "YES", which meansthe
	unmatched node will be used and a default value is returned in
	the case no match is found. If "NO" is set, an empty string will
	returned. By default "NO" is used.
Example
	::

		fiftyonedegrees.set_allow_unmatched("NO")

$Function VOID set_use_performance_graph(STRING usePerformanceGraph)

Description
	Set whether performance optimized graph should be used. The
	potential values are "YES" and "NO". The default value is determined
	by the performance profile being used.
Example
	::

		fiftyonedegrees.set_use_performance_graph("NO")

$Function VOID set_use_predictive_graph(STRING usePredictiveGraph)

Description
	Set whether predictive optimized graph should be used. The potentinal
	values are "YES" and "NO". The default value is determinedby the
	performance profile being used.
Example
	::

		fiftyonedegrees.set_use_predictive_graph("NO")
	
$Function STRING get_dataset_name()

Description
	Returns the name of the dataset being used e.g. Premium.

$Function STRING get_dataset_format()

Description
	Returns the format of the dataset being used e.g. HashV41.

$Function STRING get_dataset_published_date()

Description
	Returns the date the dataset was published in the format YYYY-MM-DD.

$Event init_function

Description
	Initialize the memory used by 51Degrees Device Detection VMOD.