51Degrees Device Detection C/C++  4.1

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

collection.h

1 /* *********************************************************************
2  * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
3  * Copyright 2019 51 Degrees Mobile Experts Limited, 5 Charlotte Close,
4  * Caversham, Reading, Berkshire, United Kingdom RG4 7BY.
5  *
6  * This Original Work is licensed under the European Union Public Licence (EUPL)
7  * v.1.2 and is subject to its terms as set out below.
8  *
9  * If a copy of the EUPL was not distributed with this file, You can obtain
10  * one at https://opensource.org/licenses/EUPL-1.2.
11  *
12  * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
13  * amended by the European Commission) shall be deemed incompatible for
14  * the purposes of the Work and the provisions of the compatibility
15  * clause in Article 5 of the EUPL shall not apply.
16  *
17  * If using the Work as, or as part of, a network application, by
18  * including the attribution notice(s) required under Article 5 of the EUPL
19  * in the end user terms of the application under an appropriate heading,
20  * such notice(s) shall fulfill the requirements of that article.
21  * ********************************************************************* */
22 
23 #ifndef FIFTYONE_DEGREES_COLLECTION_H_INCLUDED
24 #define FIFTYONE_DEGREES_COLLECTION_H_INCLUDED
25 
236  /* Define NDEBUG if needed, to ensure asserts are disabled in release builds */
237 #if !defined(DEBUG) && !defined(_DEBUG) && !defined(NDEBUG)
238 #define NDEBUG
239 #endif
240 
241 #include "data.h"
242 #include "exceptions.h"
243 #include "cache.h"
244 #include "file.h"
245 #include "memory.h"
246 #include <stdio.h>
247 #include <string.h>
248 #include <assert.h>
249 
254 #define FIFTYONE_DEGREES_COLLECTION_FREE(c) \
255 if (c != NULL) { c->freeCollection(c); }
256 
257 
265 #ifndef FIFTYONE_DEGREES_MEMORY_ONLY
266 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i) c->release(i)
267 #else
268 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i)
269 #endif
270 
271 
276 #pragma pack(push, 4)
277 typedef struct fiftyone_degrees_collection_header_t {
278  uint32_t startPosition;
279  uint32_t length;
280  uint32_t count;
282 #pragma pack(pop)
283 
288 typedef struct fiftyone_degrees_collection_config_t {
289  uint32_t loaded;
291  uint32_t capacity;
293  uint16_t concurrency;
296 
298 typedef struct fiftyone_degrees_collection_t fiftyoneDegreesCollection;
299 typedef struct fiftyone_degrees_collection_item_t fiftyoneDegreesCollectionItem;
300 typedef struct fiftyone_degrees_collection_file_t fiftyoneDegreesCollectionFile;
309 typedef struct fiftyone_degrees_collection_item_t {
311  void *handle;
317 
329 typedef void* (*fiftyoneDegreesCollectionGetMethod)(
330  fiftyoneDegreesCollection *collection,
331  uint32_t indexOrOffset,
333  fiftyoneDegreesException *exception);
334 
342  void *initial);
343 
354 typedef void* (*fiftyoneDegreesCollectionFileRead)(
355  const fiftyoneDegreesCollectionFile *collection,
356  uint32_t offsetOrIndex,
357  fiftyoneDegreesData *data,
358  fiftyoneDegreesException *exception);
359 
371  void *state,
373  fiftyoneDegreesException *exception);
374 
382 
388  fiftyoneDegreesCollection* collection);
389 
398  void *state,
399  uint32_t key,
400  void *data);
401 
407 typedef struct fiftyone_degrees_collection_t {
418  void *state;
424  uint32_t count;
425  uint32_t elementSize;
426  uint32_t size;
429 
433 typedef struct fiftyone_degrees_collection_memory_t {
435  byte *firstByte;
436  byte *lastByte;
437  void *memoryToFree;
440 
444 typedef struct fiftyone_degrees_collection_file_t {
448  long offset;
453 
459 typedef struct fiftyone_degrees_collection_cache_t {
464 
474 
484  fiftyoneDegreesCollection *collection,
485  uint32_t indexOrOffset,
486  fiftyoneDegreesException *exception);
487 
504  FILE *file,
505  fiftyoneDegreesFilePool *reader,
506  const fiftyoneDegreesCollectionConfig *config,
509 
524 
537  const fiftyoneDegreesCollectionFile *file,
538  uint32_t offset,
539  fiftyoneDegreesException *exception);
540 
558  const fiftyoneDegreesCollectionFile *file,
559  uint32_t index,
560  fiftyoneDegreesData *data,
561  fiftyoneDegreesException *exception);
562 
577  FILE *file,
578  uint32_t elementSize,
579  bool isCount);
580 
597  const fiftyoneDegreesCollectionFile *file,
598  fiftyoneDegreesData *data,
599  uint32_t offset,
600  void *initial,
601  size_t initialSize,
603  fiftyoneDegreesException *exception);
604 
620  uint32_t elementSize,
621  bool isCount);
622 
623 
644  fiftyoneDegreesCollection *collection,
646  uint32_t lowerIndex,
647  uint32_t upperIndex,
648  void *state,
650  fiftyoneDegreesException *exception);
651 
665 EXTERNAL uint32_t fiftyoneDegreesCollectionGetCount(
666  fiftyoneDegreesCollection *collection);
667 
672 #endif
bool fiftyoneDegreesCollectionGetIsMemoryOnly()
Determines if in memory collection methods have been compiled so they are fully optimized.
fiftyoneDegreesCollection * source
The source collection used to load items into the cache.
Definition: collection.h:460
Type of collection where items are cached as they are used.
Definition: collection.h:459
fiftyoneDegreesCollectionFileRead read
Read method used to read an item from file at an offset or index.
Definition: collection.h:449
Collection header structure which defines the size and location of the collection data.
Definition: collection.h:277
void * fiftyoneDegreesCollectionReadFileFixed(const fiftyoneDegreesCollectionFile *file, uint32_t index, fiftyoneDegreesData *data, fiftyoneDegreesException *exception)
Used with collections where each item is a fixed number of bytes recorded in elementSize.
fiftyoneDegreesCache * cache
Loading cache to use as data source.
Definition: collection.h:462
int(* fiftyoneDegreesCollectionItemComparer)(void *state, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
Compares two items and returns the difference between them for the purposes of a binary search of ord...
Definition: collection.h:370
int32_t fiftyoneDegreesCollectionGetInteger32(fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesException *exception)
Returns a 32 bit integer from collections that provide such values.
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromFile(FILE *file, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
long fiftyoneDegreesCollectionBinarySearch(fiftyoneDegreesCollection *collection, fiftyoneDegreesCollectionItem *item, uint32_t lowerIndex, uint32_t upperIndex, void *state, fiftyoneDegreesCollectionItemComparer comparer, fiftyoneDegreesException *exception)
Where a collection is fixed width and contains an ordered list of items this method is used to perfor...
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:445
bool(* fiftyoneDegreesCollectionIterateMethod)(void *state, uint32_t key, void *data)
Method used to iterate over data held in a collection.
Definition: collection.h:397
Used to store a handle to the underlying item that could be used to release the item when it's finish...
Definition: collection.h:309
void(* fiftyoneDegreesCollectionReleaseMethod)(fiftyoneDegreesCollectionItem *item)
Releases the item so that the collection can free the memory or take other actions when the caller no...
Definition: collection.h:380
fiftyoneDegreesFileHandle * fiftyoneDegreesCollectionReadFilePosition(const fiftyoneDegreesCollectionFile *file, uint32_t offset, fiftyoneDegreesException *exception)
Get a handle from the file pool associated with the collection and position the file handle at the of...
Used to read data from memory in a similar manner to a file handle.
Definition: memory.h:58
void *(* fiftyoneDegreesCollectionFileRead)(const fiftyoneDegreesCollectionFile *collection, uint32_t offsetOrIndex, fiftyoneDegreesData *data, fiftyoneDegreesException *exception)
Reads the item from the underlying data file.
Definition: collection.h:354
Cache structure to store the root of the red black tree and a list of allocated cache nodes.
Definition: cache.h:184
fiftyoneDegreesCollectionFreeMethod freeCollection
Frees collection and all items retrieved from the collection will become invalid.
Definition: collection.h:414
void *(* fiftyoneDegreesCollectionGetMethod)(fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
Gets an item from the collection.
Definition: collection.h:329
fiftyoneDegreesCollection * fiftyoneDegreesCollectionCreateFromFile(FILE *file, fiftyoneDegreesFilePool *reader, const fiftyoneDegreesCollectionConfig *config, fiftyoneDegreesCollectionHeader header, fiftyoneDegreesCollectionFileRead read)
Creates a collection from the file handle at the current position in the file.
uint32_t count
The number of items, or 0 if not available.
Definition: collection.h:424
Type of collection where the collection is streamed from file.
Definition: collection.h:444
fiftyoneDegreesCollection * collection
Collection the item came from which may not have been set.
Definition: collection.h:312
uint32_t capacity
Number of items the cache should store, 0 for no cache.
Definition: collection.h:291
byte * firstByte
The first byte in memory of the collection.
Definition: collection.h:435
uint32_t fiftyoneDegreesCollectionGetCount(fiftyoneDegreesCollection *collection)
Gets the actual number of items in the collection by iterating through to the base collection.
Data structure used for reusing memory which may have been allocated in a previous operation.
Definition: data.h:106
uint32_t count
Number of entities in the collection.
Definition: collection.h:280
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromMemory(fiftyoneDegreesMemoryReader *reader, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
void * handle
A handle that relates to the data.
Definition: collection.h:311
uint32_t startPosition
Start position in the data file of the entities.
Definition: collection.h:278
long offset
Offset to the collection in the source data structure.
Definition: collection.h:448
void * memoryToFree
Memory to free when freeing the collection, or NULL if no memory to free.
Definition: collection.h:437
fiftyoneDegreesCollection * next
The next collection implementation or NULL.
Definition: collection.h:422
fiftyoneDegreesFilePool * reader
Reader used to load items into the cache, or NULL if no cache.
Definition: collection.h:446
uint16_t concurrency
Expected number of concurrent requests, 1 or greater.
Definition: collection.h:293
File handle node in the stack of handles.
Definition: file.h:214
uint32_t elementSize
The size of each entry, or 0 if variable length.
Definition: collection.h:425
fiftyoneDegreesCollectionGetMethod get
Gets an entry into the item provided.
Definition: collection.h:408
void * state
Pointer to data for memory, cache or file.
Definition: collection.h:418
uint32_t loaded
Number of items to load into memory from the start of the collection.
Definition: collection.h:289
Collection configuration structure which defines how the collection should memory_html_a64699d9a1d87a7b70574fa9d710a236f">
void * memoryToFree
Memory to free when freeing the collection, or NULL if no memory to free.
Definition: collection.h:437
fiftyoneDegreesCollection * next
The next collection implementation or NULL.
Definition: collection.h:422
fiftyoneDegreesFilePool * reader
Reader used to load items into the cache, or NULL if no cache.
Definition: collection.h:446
uint16_t concurrency
Expected number of concurrent requests, 1 or greater.
Definition: collection.h:293
File handle node in the stack of handles.
Definition: file.h:214
uint32_t elementSize
The size of each entry, or 0 if variable length.
Definition: collection.h:425
fiftyoneDegreesCollectionGetMethod get
Gets an entry into the item provided.
Definition: collection.h:408
void * state
Pointer to data for memory, cache or file.
Definition: collection.h:418
uint32_t loaded
Number of items to load into memory from the start of the collection.
Definition: collection.h:289
Collection configuration structure which defines how the collection should be created by the create m...
Definition: collection.h:288
void * fiftyoneDegreesCollectionReadFileVariable(const fiftyoneDegreesCollectionFile *file, fiftyoneDegreesData *data, uint32_t offset, void *initial, size_t initialSize, fiftyoneDegreesCollectionGetFileVariableSizeMethod getFinalSize, fiftyoneDegreesException *exception)
Reads a variable size item from the file where the initial bytes can be used to calculate the size of...
void(* fiftyoneDegreesCollectionFreeMethod)(fiftyoneDegreesCollection *collection)
Frees all the memory and handles associated with the collection.
Definition: collection.h:387
Structure used to represent a 51Degrees exception and passed into methods that might generate excepti...
Definition: exceptions.h:116
Type of collection where the collection is held in continuous memory.
Definition: collection.h:433
fiftyoneDegreesCollection * fiftyoneDegreesCollectionCreateFromMemory(fiftyoneDegreesMemoryReader *reader, fiftyoneDegreesCollectionHeader header)
Creates the collection from a memory reader where the collection maps to the memory allocated to the ...
Stack of handles used to read data from a single source file.
Definition: file.h:222
uint32_t length
Length in bytes of all the entities.
Definition: collection.h:279
All the shared methods and fields required by file, memory and cached collections.
Definition: collection.h:407
fiftyoneDegreesData data
Item data including allocated memory.
Definition: collection.h:310
fiftyoneDegreesCollectionReleaseMethod release
Releases the item handle.
Definition: collection.h:412
byte * lastByte
The last byte in memory of the collection.
Definition: collection.h:436
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:434
uint32_t size
Number of bytes in the source data structure containing the collection's data.
Definition: collection.h:426
uint32_t(* fiftyoneDegreesCollectionGetFileVariableSizeMethod)(void *initial)
Passed a pointer to the first part of a variable size item and returns the size of the entire item.
Definition: collection.h:341