dac.h File Reference

API main header file. More...

Go to the source code of this file.

Data Structures
struct	da_atlas
	Represents a usable device atlas interface. More...
struct	da_buf
	Represents a chunk of memory. More...
struct	da_allocator
	A callback interface for allocating memory from some source Not for public consumption. More...
struct	da_deviceinfo
	Represents a search result Can be used to retrieve values of known properties discovered from the evidence, iterate over the properties with known values, and query property types that are local to this result. More...
struct	da_evidence
	Used to pass evidence to da_searchv() More...
struct	da_property_decl
	Used to pass properties the API intends to query to the da_atlas_open function This can be used to improve performance of lookup on properties well-known to the API user, but not present in the JSON database. More...

Typedefs
typedef enum da_severity	da_severity_t
	Primary types of the interface. More...
typedef enum da_status	da_status_t
typedef da_status_t(*	da_setpos_fn) (void *ctx, off_t off)
typedef enum da_type	da_type_t
typedef int	da_evidence_id_t
	An operation on an atlas involves converting a set of evidence strings into a set of property/value pairs. More...
typedef int	da_propid_t
	The search result encompasses a key/value set. More...
typedef size_t(*	da_read_fn) (void *ctx, size_t maxlen, char *ptr)
typedef struct da_atlas	da_atlas_t
typedef struct da_deviceinfo	da_deviceinfo_t
typedef struct da_evidence	da_evidence_t
typedef struct da_jsonparser	da_jsonparser_t
typedef struct da_node	da_node_t
typedef struct da_property_decl	da_property_decl_t
typedef struct da_propset	da_propset_t
typedef void *(*	da_alloc_fn) (void *ctx, size_t)
typedef void(*	da_free_fn) (void *ctx, void *)
typedef void *(*	da_realloc_fn) (void *ctx, void *, size_t)
typedef void(*	da_errorfunc_t) (da_severity_t severity, da_status_t status, const char *msg, va_list args)

Enumerations
enum	da_type {   DA_TYPE_NONE, DA_TYPE_BOOLEAN, DA_TYPE_INTEGER, DA_TYPE_NUMBER,   DA_TYPE_STRING, DA_TYPE_ARRAY, DA_TYPE_OBJECT, DA_TYPE_NULL }
	All values returned by the API have one of these types. More...
enum	da_status {   DA_OK, DA_INVALID_JSON, DA_OVERFLOW, DA_FORMAT_ERROR,   DA_NOMEM, DA_SYS, DA_NOTIMPL, DA_NOTFOUND,   DA_REGEXBAD, DA_NOMORE, DA_INVALID_COOKIE, DA_INVALID_TYPE,   DA_INTERNAL_ERROR, DA_STATUS_LAST }
	Any method that returns a da_status may potentially fail for one of these reasons. More...
enum	da_severity { DA_SEV_FATAL, DA_SEV_ERROR, DA_SEV_WARN, DA_SEV_INFO }
enum	{ DA_INITIAL_MEMORY_ESTIMATE = 1024 * 1024 * 30 }
enum	{ DA_BUFSIZE = 16000 }

Functions
void	da_init ()
	Functional interface. More...
void	da_fini ()
	Release all resources used by the API. More...
void	da_seterrorfunc (da_errorfunc_t callback)
	User-supplied callback to be invoked with information about an error. More...
da_evidence_id_t	da_atlas_header_evidence_id (const da_atlas_t *atlas, const char *header_name)
	Given a specific HTTP header, return the associated ID for that header. More...
da_evidence_id_t	da_atlas_clientprop_evidence_id (const da_atlas_t *atlas)
	Return the associated ID of the client side properties evidence. More...
da_status_t	da_atlas_compile (void *ctx, da_read_fn readfn, da_setpos_fn setposfn, void **ptr, size_t *len)
	readfn should present JSON content from ctx. More...
da_status_t	da_atlas_open (da_atlas_t *atlas, da_property_decl_t *extra_props, const void *ptr, size_t pos)
	opens a previously compiled atlas for operations. More...
void	da_atlas_close (da_atlas_t *atlas)
	Release any resources associated with the atlas structure atlas, which was previously generated from da_read_atlas or da_compile_atlas. More...
da_status_t	da_searchv (const da_atlas_t *atlas, da_deviceinfo_t *info, da_evidence_t *ev, size_t count)
	Find device properties given a set of evidence. More...
da_status_t	da_search (const da_atlas_t *atlas, da_deviceinfo_t *info,...)
	As da_search, but unrolls the evidence array into variable arguments for simpler calling convention with known evidence types. More...
void	da_close (da_deviceinfo_t *info)
	After finishing with a search result, release resources associated with it. More...
da_status_t	da_atlas_getpropid (const da_atlas_t *atlas, const char *propname, da_propid_t *propid)
	Given a property name (Eg, "displayWidth"), return the property ID associated with it for the specified atlas. More...
da_status_t	da_atlas_getproptype (const da_atlas_t *atlas, da_propid_t propid, da_type_t *type)
	Given a property ID, return the type of that property. More...
da_status_t	da_atlas_getpropname (const da_atlas_t *atlas, da_propid_t propid, const char **propname)
	Given a property ID, return the name of that property. More...
da_status_t	da_getpropstring (const da_deviceinfo_t *info, da_propid_t propid, const char **value)
	Given a search result, find the value of a specific property. More...
da_status_t	da_getpropinteger (const da_deviceinfo_t *info, da_propid_t propid, long *value)
	returns a property value as a long from a given long typed property id More...
da_status_t	da_getpropboolean (const da_deviceinfo_t *info, da_propid_t propid, bool *value)
	returns a property value as a boolean from a given boolean typed property id More...
da_status_t	da_getpropfloat (const da_deviceinfo_t *info, da_propid_t propid, double *value)
	returns a property value as a float from a given float typed property id More...
da_status_t	da_getproptype (const da_deviceinfo_t *info, da_propid_t propid, da_type_t *type)
	Some properties may not be not known to the atlas before the search commences. More...
da_status_t	da_getpropname (const da_deviceinfo_t *info, da_propid_t propid, const char **propname)
	returns the name of a given device property from the search functions More...
da_status_t	da_getfirstprop (const da_deviceinfo_t *info, da_propid_t **propid)
	da_getfirstprop/da_getnextprop provide iteration over all properties in a search result. More...
da_status_t	da_getnextprop (const da_deviceinfo_t *info, da_propid_t **propid)
	device info properties iterator More...
da_status_t	da_reporterror (da_status_t severity, const char *fmt,...)
	Report an error, as per a report from the API to the user-callback. More...
const char *	da_typename (da_type_t type)
	returns a textual description of the type "type". More...
const char *	da_atlas_get_property_name (const da_atlas_t *atlas, da_propid_t propid)
	returns the name of a global property More...
size_t	da_getpropcount (const da_deviceinfo_t *info)
	returns the number of properties in a result. More...

Detailed Description

API main header file.

Author

DeviceAtlas Limited

---

Data Structure Documentation

struct da_atlas

Represents a usable device atlas interface.

No user servicable parts inside: access should be via the functional API.

Data Fields
da_evidence_id_t	clientprops_evidence
size_t	cpr_count
da_deviceinfo_t **	cpr_props
size_t	header_evidence_count
struct header_evidence_entry *	header_priorities
da_propid_t	id_propid
const struct atlas_image *	image
da_evidence_id_t	next_evidence
da_propset_t *	properties
size_t	replacement_regex_count
struct pcre_regex_info *	replacement_regexes
size_t	uar_regex_count
struct pcre_regex_info *	uar_regexes
da_evidence_id_t	user_agent_evidence

struct da_buf

Represents a chunk of memory.

See comments on da_deviceinfo. This is presented here to allow aggregation in da_deviceinfo: Not for public consumption.

Data Fields
char	buf[DA_BUFSIZE]
char *	cur
char *	limit
struct da_buf *	next

struct da_allocator

A callback interface for allocating memory from some source Not for public consumption.

Data Fields
da_alloc_fn	alloc
void *	context
da_free_fn	free
da_realloc_fn	realloc

struct da_deviceinfo

Represents a search result Can be used to retrieve values of known properties discovered from the evidence, iterate over the properties with known values, and query property types that are local to this result.

The atlas the search is carried out on must survive any da_deviceinfo results it provides.

Data Fields
struct da_allocator	allocator
const da_atlas_t *	atlas
struct da_bitset *	cprprop
struct da_buf *	heap	The per-deviceinfo heap is stored here. Allocations for data in the result come from the raw data in these buffers. The size of the fixed-size buffer built in to da_buf is sized such that all known search results will not require memory allocation via malloc()
struct da_buf	initial_heap
da_propset_t *	local_types
struct da_bitset *	localprop
struct da_bitset *	present
size_t	propcount
union da_value *	properties
da_propid_t *	proplist

struct da_evidence

Used to pass evidence to da_searchv()

Data Fields
da_evidence_id_t	key
char *	value

struct da_property_decl

Used to pass properties the API intends to query to the da_atlas_open function This can be used to improve performance of lookup on properties well-known to the API user, but not present in the JSON database.

Data Fields
const char *	name
da_type_t	type