• About Us
  • Blog
  • Basket
  • Account
  • Sign In
  •  

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
51Degrees will only work if DATA_SET_INIT_STATUS_SUCCESS was returned.

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
51Degrees will only work if DATA_SET_INIT_STATUS_SUCCESS was returned.

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
51Degrees will only work if DATA_SET_INIT_STATUS_SUCCESS was returned.

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.

Need Help?

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
char output[4096];
const Device *device;

gets(ws->input);
device = getDevice(ws);

if (device != NULL) {
    processDeviceCSV(device, output, 4096);
    printf("%s", output);
}

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

1
2
3
4
char input[50000], output[50000];
gets(input);
processDeviceCSV(getDeviceOffset(input), output, 50000);
printf("%s", output);

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.