Reference - Version 3
Pattern
As of version 3.1.5.2 all external functions and structs in the 51Degrees C library have been given the prefix 'fiftyoneDegrees'. If you have code using 51Degrees C written prior to this you will need to change the functions to use the new prefixes.
The pattern method library uses worksets and datasets to reference any working memory or parameters needed to perform detection. Datasets are created from data files and then used with worksets to perform device detection. Many dataset and worksets can be created. A single dataset can be used to create several worksets.
See the ProcPat.c file for an example of how to use these methods.
fiftyoneDegreesInitWithPropertyArray
fiftyoneDegreesDataSetInitStatus fiftyoneDegreesInitWithPropertyArray ( const char * fileName, fiftyoneDegreesDataSet * dataSet, char ** properties, int32_t count);
Initialises the data set passed to the method with the data from the file provided. If required properties is provided the data set will only return those contained in the array.
Parameters
- fileName - The file path of the data source to use for initialisation.
- dataSet - Pointer to the data set.
- requiredProperties - Pointer to a char array of the comma separated list of properties the dataSet can return
Return
Returns a fiftyoneDegreesDataSetInitStatus enum that will have one of 5 values showing if the init was successful:
- DATA_SET_INIT_STATUS_SUCCESS
- DATA_SET_INIT_STATUS_INSUFFICIENT_MEMORY
- DATA_SET_INIT_STATUS_CORRUPT_DATA
- DATA_SET_INIT_STATUS_INCORRECT_VERSION
- DATA_SET_INIT_STATUS_FILE_NOT_FOUND
fiftyoneDegreesInitWithPropertyString
fiftyoneDegreesDataSetInitStatus fiftyoneDegreesInitWithPropertyString ( const char * fileName, fiftyoneDegreesDataSet * dataSet, char * properties);
Initialises the data set passed to the method with the data from the file provided. If required properties is provided the data set will only return those listed and separated by comma, pipe, space or tab
Parameters
- fileName - The file path of the data source to use for initialisation.
- dataSet - Pointer to the data set.
- requiredProperties - Pointer to a char array of the comma separated list of properties the dataSet can return
Return
Returns a fiftyoneDegreesDataSetInitStatus enum that will have one of 5 values showing if the init was successful:
- DATA_SET_INIT_STATUS_SUCCESS
- DATA_SET_INIT_STATUS_INSUFFICIENT_MEMORY
- DATA_SET_INIT_STATUS_CORRUPT_DATA
- DATA_SET_INIT_STATUS_INCORRECT_VERSION
- DATA_SET_INIT_STATUS_FILE_NOT_FOUND
fiftyoneDegreesDestroy
void fiftyoneDegreesDestroy ( const fiftyoneDegreesDataSet * dataSet);
Destroys the data set releasing all memory available.
Parameters
- dataSet - Pointer to the data set being destroyed.
fiftyoneDegreesCreateWorkset
fiftyoneDegreesWorkset * fiftyoneDegreesCreateWorkset ( const fiftyoneDegreesDataSet * dataSet);
Creates a new workset to perform matches using the dataset provided. The workset must be destroyed using the freeWorkset method when it's finished with to release memory.
Parameters
- dataSet - Pointer to the data set.
Return
A pointer to the workset created.
fiftyoneDegreesMatch
void fiftyoneDegreesMatch (fiftyoneDegreesWorkset * ws, char * userAgent);
Main entry method used for perform a match.
Parameters
- ws - Pointer to a work set to be used for the match created by the fiftyoneDegreeCreateWorkset function
- userAgent - Pointer to the target user agent.
fiftyoneDegreesSetValues
int32_t fiftyoneDegreesSetValues (fiftyoneDegreesWorkset * ws, int32_t requiredPropertyIndex);
Sets the values associated with the required property index in the workset so that an array of values can be read.
Parameters
- ws - Pointer to the work set associated with the match.
- requiredPropertyIndex - Index of the property required from the array of require properties
Return
The number of values that were set.
fiftyoneDegreesGetString
const fiftyoneDegreesAsciiString * fiftyoneDegreesGetString ( const fiftyoneDegreesDataSet * dataSet, int32_t offset);
Returns a pointer to the ascii string at the byte offset provided.
Parameters
- dataSet - Pointer to the data set.
- offset - Offset to the ascii string required.
Return
A pointer to the AsciiString at the offset.
fiftyoneDegreesGetValueName
const char * fiftyoneDegreesGetValueName ( const fiftyoneDegreesDataSet * dataSet, const fiftyoneDegreesValue * value);
Returns the name of the value provided.
Parameters
- dataSet - Pointer to the data set containing the value.
- value - Pointer to value to get name of.
Returns
Pointer to the char string of the name.
fiftyoneDegreesGetPropertyName
const char * fiftyoneDegreesGetPropertyName ( const fiftyoneDegreesDataSet * dataSet, const fiftyoneDegreesProperty * property);
Returns the name of the property provided.
Parameters
- dataSet - Pointer to the data set containing the property.
- property - Pointer to property to get name of.
Return
Pointer to the char string of the name.
fiftyoneDegreesProcessDeviceCSV
int32_t fiftyoneDegreesProcessDeviceCSV (fiftyoneDegreesWorkset * ws, char * result, int32_t resultLength);
Process device properties into a CSV string.
Parameters
- ws - Pointer to the workset.
- result - Pointer to where the result CSV should be stored.
- resultLength - The maximum length the result can be to stop overflow.
Result
The length of the CSV string.
fiftyoneDegreesProcessDeviceJSON
int32_t fiftyoneDegreesProcessDeviceJSON (fiftyoneDegreesWorkset * ws, char * result, int32_t resultLength);
Process device properties into a JSON string.
Parameters
- ws - Pointer to the workset.
- result - Pointer to where the result JSON should be stored.
- resultLength - The maximum length the result can be to stop overflow.
Result
The length of the JSON string.
Trie
As of version 3.1.5.2 all external functions and structs in the 51Degrees C library have been given the prefix 'fiftyoneDegrees'. If you have code using 51Degrees C written prior to this you will need to change the functions to use the new prefixes.
The trie matching method is computationally very simple and as such does not require much working memory for detection requests, only for storing the trie data.
See the ProcTrie.c file for an example of how to use these methods.
fiftyoneDegreesInit
fiftyoneDegreesDataSetInitStatus fiftyoneDegreesInit ( char * fileName, char * properties);
Initialises the memory using the file provided.
Parameters
- fileName - The file path of the data source to use for initialisation.
- properties - Pointer to a char array of the comma separated list of properties the dataSet can return
Return
Returns a fiftyoneDegreesDataSetInitStatus enum that will have one of 5 values showing if the init was successful:
- DATA_SET_INIT_STATUS_SUCCESS
- DATA_SET_INIT_STATUS_INSUFFICIENT_MEMORY
- DATA_SET_INIT_STATUS_CORRUPT_DATA
- DATA_SET_INIT_STATUS_INCORRECT_VERSION
- DATA_SET_INIT_STATUS_FILE_NOT_FOUND
fiftyoneDegreesGetDeviceOffset
int fiftyoneDegreesGetDeviceOffset ( char * userAgent);
Returns the offset to a matching device based on the user agent provided.
Parameters
- userAgent - The user agent to be matched.
Return
The offset to a device that can be used with getValue or processDeviceCSV.
fiftyoneDegreesGetPropertyIndex
int fiftyoneDegreesGetPropertyIndex ( char * value);
Gets the index of the property requested.
Parameters
- value - The name of the property to get.
Return
The index of the value that can be used with getPropertyIndex, or -1 if the property could not be found.
fiftyoneDegreesGetValue
char * fiftyoneDegreesGetValue ( int deviceOffset, int propertyIndex);
Takes the results of getDeviceOffset and getPropertyIndex to return a value.
Parameters
- deviceOffset - The offset of the device.
- propertyIndex - The index of the property.
Return
Pointer to a string with the device's property value.
fiftyoneDegreesDestroy
void fiftyoneDegreesDestroy ();
Frees the memory taken by the Trie data.
fiftyoneDegreesProcessDeviceCSV
int fiftyoneDegreesProcessDeviceCSV ( int deviceOffset, char * result, int resultLength);
Process device properties into a CSV string.
Parameters
- deviceOffset - The offset of the device to use.
- result - Pointer to where the result CSV should be stored.
- resultLength - The maximum length the result can be to stop overflow.
Result
The length of the CSV string.
fiftyoneDegreesProcessDeviceJSON
int fiftyoneDegreesProcessDeviceJSON ( int deviceOffset, char * result, int resultLength);
Process device properties into a JSON string.
Parameters
- deviceOffset - The offset of the device to use.
- result - Pointer to where the result JSON should be stored.
- resultLength - The maximum length the result can be to stop overflow.
Result
The length of the JSON string.
Reference - Version 2
This reference guide describes the external C functions. Functions not documented here should either not be used as their intended for internal purposes or are not yet ready for external use.
Pattern
The pattern method library uses worksets to reference any working memory or parameters needed to perform detection. Worksets are created following the initialisation of the library and are then used by subsequent functions. The library can be initialised once, many worksets can be created and destroyed. When all worksets have been freed the library can be destroyed. See the ProcPat.c file for an example of how to use these methods.
| Method | Parameter | Description | ||
|---|---|---|---|---|
| init | Initialises the library with properties to return from each detection. A full list of properties is available in the property dictionary . | |||
| properties | Pointer to a comma separated list of properties to return. | |||
| destroy | Frees any memory used. Must be called after init and after all worksets have been freed. | |||
| createWorkset | Returns a pointer to a workset structure used in subsequent calls. | |||
| freeWorkset | Frees the memory used by the workset provided. | |||
| ws | Pointer to a workset. | |||
| getDevice | Returns a pointer to a device which matches the user agent provided in the input field of the workset structure. | |||
| deviceOffset | The integer value returned from getDeviceOffset. | |||
| ws | Pointer to a workset whose input field points to the user agent of the device to be matched. | |||
| processDeviceCSV |
Sets the provided results character array to a CSV format string using pipe (|) characters to separate fields. The number of rows returned will be equal to the number of valid properties provided to the init function. The function returns the length of the result array used. Example
The following lines from the above example are relevant. Line 4 sets the worksets input field to point to a useragent string captured from stdin. Line 5 uses getDevice to return a pointer to a device matching the input useragent string. Line 8 uses processDeviceCSV to return a pipe seperated list of properties for the device returned. |
|||
| subject | Pointer to a device returned from getDevice. | |||
| result | Pointer to a preallocated array of characters to hold the result. | |||
| resultLength | The length of the array of characters available to hold the result. |
Trie
The trie matching method is computationally very simple and as such does not require any working memory for detection requests. See the ProcTrie.c file for an example of how to use these methods.
| Method | Parameter | Description | ||
|---|---|---|---|---|
| init | Initialises the library with a data source and properties to return for each detection. A full list of properties is available in the property dictionary . | |||
| fileName | Pointer to the relative of absolute path to the trie format data file. | |||
| properties | Pointer to a comma separated list of properties to return. | |||
| destroy | Frees any memory used. Must be called after init when the library has been finished with. | |||
| getDeviceOffset | Returns the integer offset in the array of devices for the device which matches the useragent provided. | |||
| userAgent | Pointer to a useragent string of the device being requested. | |||
| getPropertyIndex | Returns the integer index of for the property requested, or -1 if the property is not available. A full list of properties is available in the property dictionary . | |||
| value | Pointer to a property name. | |||
| getValue | Returns a pointer to a string containing the value for the requested device and property. | |||
| deviceOffset | The integer value returned from getDeviceOffset. | |||
| propertyIndex | The integer value returned from getPropertyIndex. | |||
| processDeviceCSV |
Sets the provided results character array to a CSV format string using pipe (|) characters to separate fields. The number of rows returned will be equal to the number of valid properties provided to the init function. The function returns the length of the result array used. Example
Line 2 gets a user agent string from stdin. Line 3 gets the offset to the device and passes it directly to the processDeviceCSV along with the output buffer and the length of the buffer. |
|||
| deviceOffset | The integer value returned from getDeviceOffset. | |||
| result | Pointer to a preallocated array of characters to hold the result. | |||
| resultLength | The length of the array of characters available to hold the result. |