\r\n

51Degrees Device Detection C/C++  4.5

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 2023 51 Degrees Mobile Experts Limited, Davidson House,
4  * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
5  *
6  * This Original Work is licensed under the European Union Public Licence
7  * (EUPL) 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 "collectionKey.h"
242 #include "data.h"
243 #include "exceptions.h"
244 #include "cache.h"
245 #include "file.h"
246 #include "memory.h"
247 #include "common.h"
248 #include <stdio.h>
249 #include <string.h>
250 
251 #include "propertyValueType.h"
252 
257 #define FIFTYONE_DEGREES_COLLECTION_FREE(c) \
258 if (c != NULL) { c->freeCollection(c); }
259 
267 #ifndef FIFTYONE_DEGREES_MEMORY_ONLY
268 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i) { assert(!((i)->collection) || (c == (i)->collection)); c->release(i); };
269 #else
270 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i)
271 #endif
272 
277 #pragma pack(push, 1)
278 typedef struct fiftyone_degrees_collection_header_t {
279  fiftyoneDegreesFileOffsetUnsigned startPosition;
280  uint32_t length;
281  uint32_t count;
282 } fiftyoneDegreesCollectionHeader;
283 #pragma pack(pop)
284 
289 typedef struct fiftyone_degrees_collection_config_t {
290  bool loaded;
291  uint32_t capacity;
293  uint16_t concurrency;
295 } fiftyoneDegreesCollectionConfig;
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 {
310  fiftyoneDegreesData data;
311  void *handle;
317  const fiftyoneDegreesCollection *collection;
318 } fiftyoneDegreesCollectionItem;
319 
331 typedef void* (*fiftyoneDegreesCollectionGetMethod)(
332  const fiftyoneDegreesCollection *collection,
333  const fiftyoneDegreesCollectionKey *key,
334  fiftyoneDegreesCollectionItem *item,
335  fiftyoneDegreesException *exception);
336 
347 typedef void* (*fiftyoneDegreesCollectionFileRead)(
348  const fiftyoneDegreesCollectionFile *collection,
349  const fiftyoneDegreesCollectionKey *key,
350  fiftyoneDegreesData *data,
351  fiftyoneDegreesException *exception);
352 
364 typedef int(*fiftyoneDegreesCollectionItemComparer)(
365  void *state,
366  fiftyoneDegreesCollectionItem *item,
367  fiftyoneDegreesCollectionKey key,
368  fiftyoneDegreesException *exception);
369 
375 typedef void (*fiftyoneDegreesCollectionReleaseMethod)(
376  fiftyoneDegreesCollectionItem* item);
377 
382 typedef void(*fiftyoneDegreesCollectionFreeMethod)(
383  fiftyoneDegreesCollection* collection);
384 
392 typedef bool(*fiftyoneDegreesCollectionIterateMethod)(
393  void *state,
394  uint32_t key,
395  void *data);
396 
402 typedef struct fiftyone_degrees_collection_t {
403  fiftyoneDegreesCollectionGetMethod get;
407  fiftyoneDegreesCollectionReleaseMethod release;
409  fiftyoneDegreesCollectionFreeMethod freeCollection;
413  void *state;
417  uint32_t count;
418  uint32_t elementSize;
419  uint32_t size;
421  const char *typeName;
422 } fiftyoneDegreesCollection;
423 
427 typedef struct fiftyone_degrees_collection_memory_t {
428  fiftyoneDegreesCollection *collection;
429  byte *firstByte;
430  byte *lastByte;
431  void *memoryToFree;
433 } fiftyoneDegreesCollectionMemory;
434 
438 typedef struct fiftyone_degrees_collection_file_t {
439  fiftyoneDegreesCollection *collection;
440  fiftyoneDegreesFilePool *reader;
442  fiftyoneDegreesFileOffset offset;
443  fiftyoneDegreesCollectionFileRead read;
446 } fiftyoneDegreesCollectionFile;
447 
453 typedef struct fiftyone_degrees_collection_cache_t {
454  fiftyoneDegreesCollection *source;
456  fiftyoneDegreesCache *cache;
457 } fiftyoneDegreesCollectionCache;
458 
467 EXTERNAL bool fiftyoneDegreesCollectionGetIsMemoryOnly();
468 
477 EXTERNAL int32_t fiftyoneDegreesCollectionGetInteger32(
478  const fiftyoneDegreesCollection *collection,
479  uint32_t indexOrOffset,
480  fiftyoneDegreesException *exception);
481 
497 EXTERNAL fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromFile(
498  FILE *file,
499  fiftyoneDegreesFilePool *reader,
500  const fiftyoneDegreesCollectionConfig *config,
501  fiftyoneDegreesCollectionHeader header,
502  fiftyoneDegreesCollectionFileRead read);
503 
515 EXTERNAL fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromMemory(
516  fiftyoneDegreesMemoryReader *reader,
517  fiftyoneDegreesCollectionHeader header);
518 
530 EXTERNAL fiftyoneDegreesFileHandle* fiftyoneDegreesCollectionReadFilePosition(
531  const fiftyoneDegreesCollectionFile *file,
532  uint32_t offset,
533  fiftyoneDegreesException *exception);
534 
551 EXTERNAL void* fiftyoneDegreesCollectionReadFileFixed(
552  const fiftyoneDegreesCollectionFile *file,
553  const fiftyoneDegreesCollectionKey *key,
554  fiftyoneDegreesData *data,
555  fiftyoneDegreesException *exception);
556 
569 EXTERNAL fiftyoneDegreesCollectionHeader
570 fiftyoneDegreesCollectionHeaderFromFile(
571  FILE *file,
572  uint32_t elementSize,
573  bool isCount);
574 
588 EXTERNAL void* fiftyoneDegreesCollectionReadFileVariable(
589  const fiftyoneDegreesCollectionFile *file,
590  fiftyoneDegreesData *data,
591  const fiftyoneDegreesCollectionKey *key,
592  void *initial,
593  fiftyoneDegreesException *exception);
594 
607 EXTERNAL fiftyoneDegreesCollectionHeader
608 fiftyoneDegreesCollectionHeaderFromMemory(
609  fiftyoneDegreesMemoryReader *reader,
610  uint32_t elementSize,
611  bool isCount);
612 
613 
634 EXTERNAL long fiftyoneDegreesCollectionBinarySearch(
635  const fiftyoneDegreesCollection *collection,
636  fiftyoneDegreesCollectionItem *item,
637  fiftyoneDegreesCollectionIndexOrOffset lowerKey,
638  fiftyoneDegreesCollectionIndexOrOffset upperKey,
639  const fiftyoneDegreesCollectionKeyType *keyType,
640  void *state,
641  fiftyoneDegreesCollectionItemComparer comparer,
642  fiftyoneDegreesException *exception);
643 
657 #define fiftyoneDegreesCollectionGetCount(collection) ((collection)->count)
658 
663 #endif
fiftyoneDegreesCollectionItemComparer
int(* fiftyoneDegreesCollectionItemComparer)(void *state, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesCollectionKey key, fiftyoneDegreesException *exception)
Compares two items and returns the difference between them for the purposes of a binary search of ord...
Definition: collection.h:364
fiftyoneDegreesCollectionGetIsMemoryOnly
bool fiftyoneDegreesCollectionGetIsMemoryOnly()
Determines if in memory collection methods have been compiled so they are fully optimized.
fiftyoneDegreesCollectionCache::source
fiftyoneDegreesCollection * source
The source collection used to load items into the cache.
Definition: collection.h:454
fiftyoneDegreesCollectionCache
Type of collection where items are cached as they are used.
Definition: collection.h:453
fiftyoneDegreesCollectionFile::read
fiftyoneDegreesCollectionFileRead read
Read method used to read an item from file at an offset or index.
Definition: collection.h:443
fiftyoneDegreesCollectionHeader
Collection header structure which defines the size and location of the collection data.
Definition: collection.h:278
fiftyoneDegreesCollectionCache::cache
fiftyoneDegreesCache * cache
Loading cache to use as data source.
Definition: collection.h:456
fiftyoneDegreesCollectionHeader::startPosition
fiftyoneDegreesFileOffsetUnsigned startPosition
Start position in the data file of the entities.
Definition: collection.h:279
fiftyoneDegreesCollectionItem::collection
const fiftyoneDegreesCollection * collection
Collection the item came from which may not have been set.
Definition: collection.h:317
fiftyoneDegreesCollectionKeyType
Explains to a collection how to properly extract the requested value.
Definition: collectionKey.h:63
fiftyoneDegreesCollectionHeaderFromFile
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromFile(FILE *file, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
fiftyoneDegreesCollectionFile::collection
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:439
fiftyoneDegreesCollectionGetInteger32
int32_t fiftyoneDegreesCollectionGetInteger32(const fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesException *exception)
Returns a 32 bit integer from collections that provide such values.
fiftyoneDegreesCollectionIterateMethod
bool(* fiftyoneDegreesCollectionIterateMethod)(void *state, uint32_t key, void *data)
Method used to iterate over data held in a collection.
Definition: collection.h:392
fiftyoneDegreesCollectionItem
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
fiftyoneDegreesCollectionReleaseMethod
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:375
fiftyoneDegreesCollectionReadFilePosition
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...
fiftyoneDegreesMemoryReader
Used to read data from memory in a similar manner to a file handle.
Definition: memory.h:54
fiftyoneDegreesCache
Cache structure to store the root of the red black tree and a list of allocated cache nodes.
Definition: cache.h:187
fiftyoneDegreesCollection::freeCollection
fiftyoneDegreesCollectionFreeMethod freeCollection
Frees collection and all items retrieved from the collection will become invalid.
Definition: collection.h:409
fiftyoneDegreesCollectionReadFileVariable
void * fiftyoneDegreesCollectionReadFileVariable(const fiftyoneDegreesCollectionFile *file, fiftyoneDegreesData *data, const fiftyoneDegreesCollectionKey *key, void *initial, fiftyoneDegreesException *exception)
Reads a variable size item from the file where the initial bytes can be used to calculate the size of...
fiftyoneDegreesCollectionCreateFromFile
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.
fiftyoneDegreesFileOffsetUnsigned
uint32_t fiftyoneDegreesFileOffsetUnsigned
Type for collection start offset (in file).
Definition: fileOffset.h:61
fiftyoneDegreesCollection::count
uint32_t count
The number of items, or 0 if not available.
Definition: collection.h:417
fiftyoneDegreesCollectionFile
Type of collection where the collection is streamed from file.
Definition: collection.h:438
fiftyoneDegreesCollectionConfig::capacity
uint32_t capacity
Number of items the cache should store, 0 for no cache.
Definition: collection.h:291
fiftyoneDegreesCollectionMemory::firstByte
byte * firstByte
The first byte in memory of the collection.
Definition: collection.h:429
fiftyoneDegreesCollectionConfig::loaded
bool loaded
Collection is loaded entirely into memory.
Definition: collection.h:290
fiftyoneDegreesCollectionFile::offset
fiftyoneDegreesFileOffset offset
Offset to the collection in the source data structure.
Definition: collection.h:442
fiftyoneDegreesData
Data structure used for reusing memory which may have been allocated in a previous operation.
Definition: data.h:101
fiftyoneDegreesCollectionHeader::count
uint32_t count
Number of entities in the collection.
Definition: collection.h:281
fiftyoneDegreesCollectionHeaderFromMemory
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromMemory(fiftyoneDegreesMemoryReader *reader, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
fiftyoneDegreesCollectionItem::handle
void * handle
A handle that relates to the data.
Definition: collection.h:311
fiftyoneDegreesCollectionMemory::memoryToFree
void * memoryToFree
Memory to free when freeing the collection, or NULL if no memory to free.
Definition: collection.h:431
fiftyoneDegreesCollectionFile::reader
fiftyoneDegreesFilePool * reader
Reader used to load items into the cache, or NULL if no cache.
Definition: collection.h:440
fiftyoneDegreesCollection::typeName
const char * typeName
Name of collection type (vtable).
Definition: collection.h:421
fiftyoneDegreesCollectionBinarySearch
long fiftyoneDegreesCollectionBinarySearch(const fiftyoneDegreesCollection *collection, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesCollectionIndexOrOffset lowerKey, fiftyoneDegreesCollectionIndexOrOffset upperKey, const fiftyoneDegreesCollectionKeyType *keyType, 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...
fiftyoneDegreesCollectionConfig::concurrency
uint16_t concurrency
Expected number of concurrent requests, 1 or greater.
Definition: collection.h:293
fiftyoneDegreesFileOffset
long fiftyoneDegreesFileOffset
Type for file offset in API.
Definition: fileOffset.h:69
fiftyoneDegreesFileHandle
File handle node in the stack of handles.
Definition: file.h:221
fiftyoneDegreesCollection::elementSize
uint32_t elementSize
The size of each entry, or 0 if variable length.
Definition: collection.h:418
fiftyoneDegreesCollection::get
fiftyoneDegreesCollectionGetMethod get
Gets an entry into the item provided.
Definition: collection.h:403
fiftyoneDegreesCollectionGetMethod
void *(* fiftyoneDegreesCollectionGetMethod)(const fiftyoneDegreesCollection *collection, const fiftyoneDegreesCollectionKey *key, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
Gets an item from the collection.
Definition: collection.h:331
fiftyoneDegreesCollection::state
void * state
Pointer to data for memory, cache or file.
Definition: collection.h:413
fiftyoneDegreesCollectionConfig
Collection configuration structure which defines how the collection should be created by the create m...
Definition: collection.h:289
fiftyoneDegreesCollectionFreeMethod
void(* fiftyoneDegreesCollectionFreeMethod)(fiftyoneDegreesCollection *collection)
Frees all the memory and handles associated with the collection.
Definition: collection.h:382
fiftyoneDegreesCollectionIndexOrOffset
Location of the item within the Collection.
Definition: collectionKey.h:52
fiftyoneDegreesException
Structure used to represent a 51Degrees exception and passed into methods that might generate excepti...
Definition: exceptions.h:111
fiftyoneDegreesCollectionKey
Explains to a collection (or cache) what the consumer is looking for.
Definition: collectionKey.h:72
fiftyoneDegreesCollectionMemory
Type of collection where the collection is held in continuous memory.
Definition: collection.h:427
fiftyoneDegreesCollectionCreateFromMemory
fiftyoneDegreesCollection * fiftyoneDegreesCollectionCreateFromMemory(fiftyoneDegreesMemoryReader *reader, fiftyoneDegreesCollectionHeader header)
Creates the collection from a memory reader where the collection maps to the memory allocated to the ...
fiftyoneDegreesFilePool
Stack of handles used to read data from a single source file.
Definition: file.h:229
fiftyoneDegreesCollectionHeader::length
uint32_t length
Length in bytes of all the entities.
Definition: collection.h:280
fiftyoneDegreesCollection
All the shared methods and fields required by file, memory and cached collections.
Definition: collection.h:402
fiftyoneDegreesCollectionItem::data
fiftyoneDegreesData data
Item data including allocated memory.
Definition: collection.h:310
fiftyoneDegreesCollection::release
fiftyoneDegreesCollectionReleaseMethod release
Releases the item handle.
Definition: collection.h:407
fiftyoneDegreesCollectionMemory::lastByte
byte * lastByte
The last byte in memory of the collection.
Definition: collection.h:430
fiftyoneDegreesCollectionFileRead
void *(* fiftyoneDegreesCollectionFileRead)(const fiftyoneDegreesCollectionFile *collection, const fiftyoneDegreesCollectionKey *key, fiftyoneDegreesData *data, fiftyoneDegreesException *exception)
Reads the item from the underlying data file.
Definition: collection.h:347
fiftyoneDegreesCollectionReadFileFixed
void * fiftyoneDegreesCollectionReadFileFixed(const fiftyoneDegreesCollectionFile *file, const fiftyoneDegreesCollectionKey *key, fiftyoneDegreesData *data, fiftyoneDegreesException *exception)
Used with collections where each item is a fixed number of bytes recorded in elementSize.
fiftyoneDegreesCollectionMemory::collection
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:428
fiftyoneDegreesCollection::size
uint32_t size
Number of bytes in the source data structure containing the collection's data.
Definition: collection.h:419

Generated by doxygen 1.8.15