\r\n

51Degrees Device Detection C/C++  4.4

A device detection library that is used natively or by 51Degrees products

Data Set

Detailed Description

A data file initialised in a structure.

Terms

Get : returns an immutable data set that must be released when the caller is finished with it.

Release : releases a reference on the data set returned from the Get operation.

Reload : reloads an existing data set while maintaining any current references to the existing data set.

Introduction

A DataSet is a data file initialised in a structure that can be used to process data. Collections from the file may be stored in memory or streamed from the file when needed.

A DataSet is used to process data, in most cases this is in the form of evidence. Values for the Properties which the data set is capable of returning can then be retrieved from the result of processing.

Creation

A DataSet is created by allocating the structure and initialising from one of the following:

File : a data file is either read into memory or handle maintained for streaming by the data set.

Memory : a data file read into continuous memory is used by the data set.

Operation

A DataSet is a resource to be maintained by a Resource Manager. So any thread wanting to use it must get a reference from the manager (see resource.h).

The data set implementation extending will contain methods to process data. Usually these will return a Results instance (or an extending structure), see results.h for more details.

Reloading

A DataSet can be reloaded without interrupting operation by using the defined Reload methods. These take either a new data file or a new memory pointer, initialise a new data set, and replace the existing one in a thread-safe manor.

Free

A DataSet is a managed resource, so it should not be freed directly. Instead the manager should be freed, so that the data set is safely freed without impacting other threads.

Collaboration diagram for Data Set:

Structs

struct  fiftyoneDegreesDataSetBase
Base data set structure which contains the 'must have's for all data sets. More...

Macros

#define  FIFTYONE_DEGREES_DATASET_RELOAD(t)
Reload functions are common across all data set implementations where the naming of the data set type and the init methods comform to the common pattern. More...

Typedefs

typedef fiftyoneDegreesStatusCode(*  fiftyoneDegreesDataSetInitFromMemoryMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, long size, fiftyoneDegreesException *exception)
Initialses the data set from data stored in continuous memory. More...
typedef fiftyoneDegreesStatusCode(*  fiftyoneDegreesDataSetInitFromFileMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)
Initialses the data set from data stored on file. More...

Functions

fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetInitProperties (fiftyoneDegreesDataSetBase *dataSet, fiftyoneDegreesPropertiesRequired *properties, void *state, fiftyoneDegreesPropertiesGetMethod getPropertyMethod, fiftyoneDegreesEvidencePropertiesGetMethod getEvidencePropertiesMethod)
Initialises the properties in the data set. More...
fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetInitHeaders (fiftyoneDegreesDataSetBase *dataSet, void *state, fiftyoneDegreesHeadersGetMethod getHeaderMethod)
Initialises the HTTP headers in the data set. More...
fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetInitFromFile (fiftyoneDegreesDataSetBase *dataSet, const char *fileName, long bytesToCompare)
Initialses the data set from data stored on file. More...
fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetInitInMemory (fiftyoneDegreesDataSetBase *dataSet, fiftyoneDegreesMemoryReader *reader)
Initialses the data set from data stored in continuous memory. More...
void  fiftyoneDegreesDataSetReset (fiftyoneDegreesDataSetBase *dataSet)
Resets a newly allocated data set structure ready for initialisation. More...
fiftyoneDegreesDataSetBase *  fiftyoneDegreesDataSetGet (fiftyoneDegreesResourceManager *manager)
Gets a pointer to the active data set from a resource manager. More...
void  fiftyoneDegreesDataSetRelease (fiftyoneDegreesDataSetBase *dataSet)
Releases a reference to a data set which has been fetched via the DataSetGet method. More...
void  fiftyoneDegreesDataSetFree (fiftyoneDegreesDataSetBase *dataSet)
Closes the data set by freeing anything which has been initialised at creation. More...
fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetReloadManagerFromMemory (fiftyoneDegreesResourceManager *manager, void *source, long length, size_t dataSetSize, fiftyoneDegreesDataSetInitFromMemoryMethod initDataSet, fiftyoneDegreesException *exception)
Reload the data set being used by the resource manager using a data file loaded into contiguous memory. More...
fiftyoneDegreesStatusCode  fiftyoneDegreesDataSetReloadManagerFromFile (fiftyoneDegreesResourceManager *manager, const char *fileName, size_t dataSetSize, fiftyoneDegreesDataSetInitFromFileMethod initDataSet, fiftyoneDegreesException *exception)
Reload the data set being used by the resource manager using the data file location specified. More...

Macro Definition Documentation

◆ FIFTYONE_DEGREES_DATASET_RELOAD

#define FIFTYONE_DEGREES_DATASET_RELOAD (   t )

Reload functions are common across all data set implementations where the naming of the data set type and the init methods comform to the common pattern.

This macro requires the init methods to be static and of the form initDataFrom[Memory|File]. The data set name must be DataSet[Type].

Parameters
t - the name of the resource type to define reload methods for

Typedef Documentation

◆ fiftyoneDegreesDataSetInitFromFileMethod

typedef fiftyoneDegreesStatusCode(* fiftyoneDegreesDataSetInitFromFileMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)

Initialses the data set from data stored on file.

This method should clean up the resource properly if the initialisation process fails. That means all allocated memory should be freed and pointers to these memorys should be set to NULL. The input dataSet should also be freed.

Parameters
dataSet - pointer to the data set to be initialised
config - configuration for the operation of the data set, or NULL if default configuration is required
properties - the properties that will be consumed from the data set, or NULL if all available properties in the hash data file should be available for consumption
fileName - the full path to a file with read permission that contains the data set
exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h
Returns
the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitFromMemoryMethod

typedef fiftyoneDegreesStatusCode(* fiftyoneDegreesDataSetInitFromMemoryMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, long size, fiftyoneDegreesException *exception)

Initialses the data set from data stored in continuous memory.

Parameters
dataSet - pointer to the data set to be initialised
config - configuration for the operation of the data set, or NULL if default configuration is required
properties - the properties that will be consumed from the data set, or NULL if all available properties in the hash data file should be available for consumption
memory - pointer to continuous memory containing the data set
size - the number of bytes that make up the data set
exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

Function Documentation

◆ fiftyoneDegreesDataSetFree()

void fiftyoneDegreesDataSetFree ( fiftyoneDegreesDataSetBase *   dataSet )

Closes the data set by freeing anything which has been initialised at creation.

This does not free the data set structure itself.

Parameters
dataSet - pointer to the data set to complete

◆ fiftyoneDegreesDataSetGet()

fiftyoneDegreesDataSetBase* fiftyoneDegreesDataSetGet ( fiftyoneDegreesResourceManager *   manager )

Gets a pointer to the active data set from a resource manager.

Note that when this is finished with it must be released with the corresponding release method.

Parameters
manager - pointer to the manager which manages the data set resource
Returns
pointer to the data set resource

◆ fiftyoneDegreesDataSetInitFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitFromFile ( fiftyoneDegreesDataSetBase *   dataSet,
const char *   fileName,
long   bytesToCompare  
)

Initialses the data set from data stored on file.

Parameters
dataSet - pointer to the pre allocated data set to be initialised
fileName - the full path to a file with read permission that contains the data set
bytesToCompare - the number of bytes to compare if the reuse temporary file option is enabled. If a temporary file is found and the first bytes are equal to the master file, then the file is used, if not then a new temporary file is created
Returns
the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitHeaders()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitHeaders ( fiftyoneDegreesDataSetBase *   dataSet,
void *   state,
fiftyoneDegreesHeadersGetMethod   getHeaderMethod  
)

Initialises the HTTP headers in the data set.

Usually this means constructing an array of pointers to the headers which are required for quick access.

Parameters
dataSet - pointer to a valid data set
state - pointer to data which is needed by getPropertymethod
getHeaderMethod - method used to retrieve the unique id and name of a header at a specified index from the data set
Returns
the status associated with the header initialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the headers were not initialised correctly

◆ fiftyoneDegreesDataSetInitInMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitInMemory ( fiftyoneDegreesDataSetBase *   dataSet,
fiftyoneDegreesMemoryReader *   reader  
)

Initialses the data set from data stored in continuous memory.

Parameters
dataSet - pointer to the pre allocated data set to be initialised
reader - constructed to read the memory containing the data set
Returns
the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitProperties()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitProperties ( fiftyoneDegreesDataSetBase *   dataSet,
fiftyoneDegreesPropertiesRequired *   properties,
void *   state,
fiftyoneDegreesPropertiesGetMethod   getPropertyMethod,
fiftyoneDegreesEvidencePropertiesGetMethod   getEvidencePropertiesMethod  
)

Initialises the properties in the data set.

Usually this means constructing an array of pointers to the properties which are required for quick access.

Parameters
dataSet - pointer to a valid data set
properties - the properties which should be initialised in the data set
state - pointer to data which is needed by getPropertymethod
getPropertyMethod - method used to retrieve the name of a property at a specified index from the data set
getEvidencePropertiesMethod - method used to populate the list of evidence required for a property in the data set
Returns
the status associated with the property initialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the properties were not initialised correctly

◆ fiftyoneDegreesDataSetRelease()

void fiftyoneDegreesDataSetRelease ( fiftyoneDegreesDataSetBase *   dataSet )

Releases a reference to a data set which has been fetched via the DataSetGet method.

Parameters
dataSet - pointer to the data set to release

◆ fiftyoneDegreesDataSetReloadManagerFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetReloadManagerFromFile ( fiftyoneDegreesResourceManager *   manager,
const char *   fileName,
size_t   dataSetSize,
fiftyoneDegreesDataSetInitFromFileMethod   initDataSet,
fiftyoneDegreesException *   exception  
)

Reload the data set being used by the resource manager using the data file location specified.

When initialising the data, the configuration that manager was first created with is used.

If the new data file is successfully initialised, the current data set is replaced The old data will remain in memory until the last reference to it is released.

Parameters
manager - pointer to the resource manager to reload the data set for
fileName - path to the new data file
dataSetSize - size of the data set structure to allocate for the new data set
initDataSet - init method used to initialise the new data set from the file provided
exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded correctly

◆ fiftyoneDegreesDataSetReloadManagerFromMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetReloadManagerFromMemory ( fiftyoneDegreesResourceManager *   manager,
void *   source,
long   length,
size_t   dataSetSize,
fiftyoneDegreesDataSetInitFromMemoryMethod   initDataSet,
fiftyoneDegreesException *   exception  
)

Reload the data set being used by the resource manager using a data file loaded into contiguous memory.

When initialising the data, the configuration that manager was first created with is used.

If the data passed in is successfully initialised, the current data set is replaced The old data will remain in memory until the last reference to it is released.

Parameters
manager - pointer to the resource manager to reload the data set for
source - pointer to the memory location where the new data file is stored
length - of the data in memory
dataSetSize - size of the data set structure to allocate for the new data set
initDataSet - init method used to initialise the new data set from the memory pointer provided
exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
Returns
the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded correctly

◆ fiftyoneDegreesDataSetReset()

void fiftyoneDegreesDataSetReset ( fiftyoneDegreesDataSetBase *   dataSet )

Resets a newly allocated data set structure ready for initialisation.

Parameters
dataSet - pointer to the allocated data set
On This Page

Generated by doxygen 1.8.15