#ifndef MOBI_DA_DAC_H #define MOBI_DA_DAC_H /** * @file dac.h * @author Afilias Technologies * * @brief API main header file */ #include #include #include #include #include #ifndef __cplusplus #ifndef true #ifdef HAVE_NO_BUILTIN__BOOL typedef int _Bool; #endif #define bool _Bool #define true 1 #define false 0 #endif #endif #define MOBI_DA_MAJOR 2 #define MOBI_DA_MINOR 1 #define MOBI_DA_DUMMY_LIBRARY 1 /** * @brief All values returned by the API have one of these types. * da_getprop*() return data in the appropriate C type for the given da_type. */ 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 }; /** * Any method that returns a da_status may potentially fail for one of these reasons. * XXX: Error reporting needs to be improved. */ enum da_status { DA_OK, /* Success. */ DA_INVALID_JSON, /* The JSON format is invalid, or the content is unexpected in a given context. */ DA_OVERFLOW, /* Overflow occurred. Note this is used to indicate an unfinished string parse in JSON */ DA_FORMAT_ERROR, /* The data supplied is formatted incorrectly. */ DA_NOMEM, /* There was not enough space to complete the operation */ DA_SYS, /* A system error occurred - consult the OS for more details (eg, check errno) */ DA_NOTIMPL, /* This method is not implemented */ DA_NOTFOUND, /* The requested item was not found. */ DA_REGEXBAD, /* An invalid regex was provided. */ DA_NOMORE, /* Used to indicate the end of an iterator. */ DA_INVALID_COOKIE, /* Cookie value supplied was invalid */ DA_INVALID_TYPE, /* A value of an unexpected type was found. */ DA_INTERNAL_ERROR, DA_STATUS_LAST /* Placeholder to indicate highest possible error value. (value will change as API matures) */ }; enum da_severity { DA_SEV_FATAL, /* The operation will not continue, and the operation will return an error. */ DA_SEV_ERROR, /* An error occurred, but the API call will return at least some valid information */ DA_SEV_WARN, /* An unexpected event occurred, but the system dealt with it */ DA_SEV_INFO /* An informational message. */ }; /* Forward references to tagged types */ struct atlas_image; struct da_atlas; struct da_deviceinfo; struct da_jsonparser; struct da_node; struct da_propset; union da_value; struct da_evidence; struct da_bitset; struct da_allocator; struct da_config; /** * @brief Primary types of the interface. * Primary types used by API client. * Non-typedef structures and unions are considered private to the API. * */ typedef enum da_severity da_severity_t; /* A severity for the error callback. */ typedef enum da_status da_status_t; /* An error code - returned from most API calls. */ typedef da_status_t (*da_setpos_fn)(void *ctx, off_t off); /* callback provided to API to rewind input stream */ typedef enum da_type da_type_t; /* A value type (integer, string, etc) */ /** * @brief An operation on an atlas involves converting a set of evidence strings into a set of property/value pairs. * The ID for a particular type of evidence is extract from the atlas (eg, for a specific HTTP header, use: * * da_evidence_id_t evidence = da_atlas_header_evidence_id(atlas, "User-Agent"); * */ typedef int da_evidence_id_t; /** * @brief The search result encompasses a key/value set. Keys are handles retrieved via * _either_ da_atlas_getpropid() or da_getpropid(). * Some search results may have keys not available when the atlas is opened (eg, * when the name of the property itself is contained within the evidence) * Such properties by necessity are given a "local" da_propid_t * * You can ensure any properties you are interested in get a global propid by * passing a list of interesting named properties to da_atlas_open() */ typedef int da_propid_t; 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 struct da_config da_config_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); /* Manifest constants. */ enum { /* * used as the initial guess for the compiled size of an atlas. * If atlas sizes grow more beyond this, it can be expanded to avoid multiple scans of the data. */ DA_INITIAL_MEMORY_ESTIMATE = 1024 * 1024 * 14 }; struct da_config { unsigned int ua_props; unsigned int lang_props; unsigned int __reserved[14]; /* enough reserved keywords for future use */ }; /** * Functional interface. */ /** * @brief Initialize process to use the DA API. */ void da_init(void); /** * @brief Release all resources used by the API */ void da_fini(void); /** * @brief User-supplied callback to be invoked with information about an error. * Note this may use thread-local storage etc to store the info on return from the current call * It is guaranteed that an error-reporting function returning an error-code will have called * this function at least once. * @param callback function */ void da_seterrorfunc(da_errorfunc_t callback); /** * @brief Given a specific HTTP header, return the associated ID for that header. * When passing evidence to the API, its type is identified using its da_evidince_id_t. * @param atlas atlas instance * @param header_name Header's name * @return evidence id */ da_evidence_id_t da_atlas_header_evidence_id(const da_atlas_t *atlas, const char *header_name); /** * @brief Return the associated ID of the client side properties evidence * @param atlas Atlas instance * @return evidence id */ da_evidence_id_t da_atlas_clientprop_evidence_id(const da_atlas_t *atlas); /** * @brief Return the associated ID of the accept language header evidence * @param atlas Atlas instance * @return evidence id */ da_evidence_id_t da_atlas_accept_language_evidence_id(const da_atlas_t *atlas); /** * @brief readfn should present JSON content from ctx. * atlasp points to an uninitialized da_atlas structure. * Result is a compiled atlas at atlasp. * Result is allocated via normal memory-allocation methods, malloc/calloc/realloc, so should be * Free'd with free() * XXX TODO: Change this to take a da_allocator * @param ctx pointer given to read the json file * @param readfn function pointer, set accordingly to the attended given pointer * @param setposfn function pointer * @param ptr Pointer dynamically allocated if the json parsing happened normally * @param len size of the atlas image * @return status of atlas compilation */ da_status_t da_atlas_compile(void *ctx, da_read_fn readfn, da_setpos_fn setposfn, void **ptr, size_t *len); /** * @brief opens a previously compiled atlas for operations. extra_props will be available in calls to * da_getpropid on the atlas, and if generated by the search, the ID will be consistent across * different calls to search. * Properties added by a search that are neither in the compiled atlas, nor in the extra_props list * Are assigned an ID within the context that is not transferrable through different search results * within the same atlas. * @param atlas Atlas instance * @param extra_props properties * @param ptr given pointer from previously compiled atlas * @param pos atlas image size * @return status of atlas data opening */ da_status_t da_atlas_open(da_atlas_t *atlas, da_property_decl_t *extra_props, const void *ptr, size_t pos); /** * @brief Release any resources associated with the atlas structure atlas, which was previously generated from * da_read_atlas or da_compile_atlas. * @param atlas instance */ void da_atlas_close(da_atlas_t *atlas); /** * @brief Find device properties given a set of evidence. * Search results are returned in da_deviceinfo_t, and must be cleaned using da_close * "Evidence" is an array of length count, of string data tagged with an evidence ID. * @param atlas Atlas instance * @param info Device info * @param ev Array of evidences * @param count Number of evidence given * @return status of the search */ da_status_t da_searchv(const da_atlas_t *atlas, da_deviceinfo_t *info, da_evidence_t *ev, size_t count); /** * @brief As da_search, but unrolls the evidence array into variable arguments for simpler calling * convention with known evidence types. * varargs are pairs of (da_evidence_id, string), terminated with da_evidence_id DA_END * @code da_search(&myAtlas, &deviceInfo, da_get_header_evidence_id("User-Agent"), * "Mozilla/5.0 (Linux...", DA_END); * @endcode * @param atlas Atlas instance * @param info given device info which holds on device properties * @param pairs of evidence id / evidence value * @return status of the search */ da_status_t da_search(const da_atlas_t *atlas, da_deviceinfo_t *info, ...); /** * @brief After finishing with a search result, release resources associated with it. * @param info Device info previously allocated by search functions */ void da_close(da_deviceinfo_t *info); /** * @brief Given a property name (Eg, "displayWidth"), return the property ID associated with it for the * specified atlas. * @param atlas Atlas instance * @param propname Property name * @param propid Property id * @return status of the property id search */ da_status_t da_atlas_getpropid(const da_atlas_t *atlas, const char *propname, da_propid_t *propid); /** * @brief Given a property ID, return the type of that property. * @code * da_getproptype(&myAtlas, da_getpropid(&myAtlas, "displayWidth"), &propertyType); * assert(propertyType == DA_TYPE_INT); * @endcode * @param atlas Atlas instance * @param propid Property id * @param type Type id of the property * @return status of the type id search */ da_status_t da_atlas_getproptype(const da_atlas_t *atlas, da_propid_t propid, da_type_t *type); /** * @brief Given a property ID, return the name of that property. * @code * da_atlas_getpropname(&myAtlas, da_getpropid(&myAtlas, "displayWidth"), &propertyName); * assert(strcmp("displayWidth", propertyName) == 0); * @endcode * @param atlas Atlas instance * @param propid property id * @param propname property name returned * @return status of the property name search */ da_status_t da_atlas_getpropname(const da_atlas_t *atlas, da_propid_t propid, const char **propname); /** * @brief Given an atlas instance, return its counters + the builtins * @code * da_atlas_getpropcount(&myAtlas); * @endcode * @param atlas Atlas instance * @return counters */ size_t da_atlas_getpropcount(const da_atlas_t *atlas); /** * @brief Given an atlas instance, set the detection config * @param atlas Atlas instance * @param config instance */ void da_atlas_setconfig(da_atlas_t *atlas, da_config_t *config); /** * @brief Given a search result, find the value of a specific property. * @code * long displayWidth; // width of display in pixels. * da_getpropinteger(&deviceInfo, da_getpropid(&myAtlas, "displayWidth"), &displayWidth); * @endcode * String contents are owned by the search result, and are valid until the search is closed. */ /** * @brief returns a property value as a string from a given string typed property id * @param info Device info * @param propid Property id * @param value Value of the property * @return status of property value search */ da_status_t da_getpropstring(const da_deviceinfo_t *info, da_propid_t propid, const char **value); /** * @brief returns a property value as a long from a given long typed property id * @param info Device info * @param propid Property id * @param value Value of the property * @return status of property value search */ da_status_t da_getpropinteger(const da_deviceinfo_t *info, da_propid_t propid, long *value); /** * @brief returns a property value as a boolean from a given boolean typed property id * @param info Device info * @param propid Property id * @param value Value of the property * @return status of property value search */ da_status_t da_getpropboolean(const da_deviceinfo_t *info, da_propid_t propid, bool *value); /** * @brief returns a property value as a float from a given float typed property id * @param info Device info * @param propid Property id * @param value Value of the property * @return status of property value search */ da_status_t da_getpropfloat(const da_deviceinfo_t *info, da_propid_t propid, double *value); /** * @brief Some properties may not be not known to the atlas before the search commences. * Such properties cannot have a da_propid_t assigned to them on the atlas, but will * have a local property assigned during search. The name and type of such properties * can be discovered here. * * Properties that are used in the atlas source and properties specifically registered * with da_atlas_open() will always be assigned to a property discovered during search. * Therefore, if there are specific properties that you want to use, and are unsure * if they are in your device atlas source, registering them with da_atlas_open will * make access to them easier and more efficient */ /** * @brief returns the type of a given device property from the search functions * @param info Device info * @param propid Property id * @param type Type id * @return status of property type search */ da_status_t da_getproptype(const da_deviceinfo_t *info, da_propid_t propid, da_type_t *type); /** * @brief returns the name of a given device property from the search functions * @param info Device info * @param propid Property id * @param propname Property name * @return status of property type search */ da_status_t da_getpropname(const da_deviceinfo_t *info, da_propid_t propid, const char **propname); /** * @brief da_getfirstprop/da_getnextprop provide iteration over all properties * in a search result. * Both will return DA_OK if there is a result available, and DA_NOMORE * if the search is complete. * @code * * da_propid_t *propidp; * for (da_status_t status = da_getfirstprop(&result, &propidp); * status == DA_OK; * status = da_getnextprop(&result, &propidp)) { * const char *propname; * if (da_getpropname(&result, *propidp, &propname) == DA_OK) * fprintf("found property %s\n", propname); * } * @endcode */ /** * @brief returns the first property from device info * @param info Device info * @param propid Property * @return status */ da_status_t da_getfirstprop(const da_deviceinfo_t *info, da_propid_t **propid); /** * @brief device info properties iterator * @param info Device info * @param propid Property * @return status */ da_status_t da_getnextprop(const da_deviceinfo_t *info, da_propid_t **propid); /** * @brief Report an error, as per a report from the API to the user-callback. * @param severity Severity level of the error * @param fmt format error message * @param va_list * @return status */ da_status_t da_reporterror(da_status_t severity, const char *fmt, ...); /** * @brief returns a textual description of the type "type". * @param type Type id * @return type name */ const char *da_typename(da_type_t type); /** * @brief returns the version from the JSON in memory * @param atlas * @return version */ char *da_getdataversion(da_atlas_t *atlas); /** * @brief returns the date creation's timestamp from the JSON in memory * @param atlas * @return version */ time_t da_getdatacreation(da_atlas_t *atlas); /** * @brief returns the revision's number from the JSON in memory * @param atlas * @return version */ int da_getdatarevision(da_atlas_t *atlas); /** * @brief returns the name of a global property * @param atlas Atlas instance * @param propid Property id * @return property name */ const char *da_get_property_name(const da_atlas_t *atlas, da_propid_t propid); /** * @brief returns the number of properties in a result. * @param info Device info * @return properties count */ size_t da_getpropcount(const da_deviceinfo_t *info); /* * Details below should not be required for usage of the API */ /** * @brief Represents a usable device atlas interface. * * No user servicable parts inside: access should * be via the functional API. */ struct da_atlas { const struct atlas_image *image; struct header_evidence_entry *header_priorities; size_t header_evidence_count; struct pcre_regex_info *uar_regexes; size_t uar_regex_count; struct pcre_regex_info *replacement_regexes; size_t replacement_regex_count; da_evidence_id_t user_agent_evidence; da_evidence_id_t clientprops_evidence; da_evidence_id_t accept_language_evidence; da_evidence_id_t next_evidence; da_propset_t *properties; da_propid_t id_propid; da_propid_t id_proplang; da_propid_t id_proplang_locale; da_config_t config; da_deviceinfo_t **cpr_props; size_t cpr_count; }; /* fixed constants. */ enum { DA_BUFSIZE = 16000 }; /** * Represents a chunk of memory. See comments on da_deviceinfo. * This is presented here to allow aggregation in da_deviceinfo: * Not for public consumption. */ struct da_buf { struct da_buf *next; char *cur; char *limit; char buf[DA_BUFSIZE]; }; /** * A callback interface for allocating memory from some source * Not for public consumption. */ struct da_allocator { da_alloc_fn alloc; da_free_fn free; da_realloc_fn realloc; void *context; }; /** * 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. */ struct da_deviceinfo { struct da_allocator allocator; const da_atlas_t *atlas; /* reference to the atlas the search was carried out on. */ struct da_bitset *present; /* property received from tree */ struct da_bitset *localprop; /* property was received from UAR rule or CPR */ struct da_bitset *cprprop; /* property was received from CPR */ union da_value *properties; /* properties - indexed by property id. */ da_propid_t *proplist; /* list of properties present in this result. */ size_t propcount; /* size of proplist */ da_propset_t *local_types; /* property descriptors local to this search result. */ /** * 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 *heap; struct da_buf initial_heap; }; /** * Used to pass evidence to da_searchv() */ struct da_evidence { da_evidence_id_t key; char *value; }; /** * 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. */ struct da_property_decl { const char *name; da_type_t type; }; #endif /* DEVATLAS_DAC_H */