C API#
Metkit also exposes a plain C interface, declared in metkit_c.h. It is a
thin wrapper over the C++ library and is the foundation the Python bindings
(pymetkit) build upon.
All functions return a metkit_error_values_t (with iterator stepping
reported via metkit_iterator_status_t); on failure, a human-readable
message can be retrieved with metkit_get_error_string(). Opaque request
and iterator types are created and released through their matching
_new/_delete functions.
Typedefs
-
typedef struct metkit_marsrequest_t metkit_marsrequest_t#
-
typedef struct metkit_requestiterator_t metkit_requestiterator_t#
RequestIterator for iterating over vector of Request instances
-
typedef struct metkit_paramiterator_t metkit_paramiterator_t#
Iterator for iterating over parameters in Request
-
typedef enum metkit_error_values_t metkit_error_t#
-
typedef enum metkit_iterator_status_t metkit_iterator_status_t
Enums
Functions
-
const char *metkit_get_error_string(enum metkit_error_values_t err)#
-
const char *metkit_version()#
Get metkit version.
- Returns:
const char* version string
-
const char *metkit_git_sha1()#
Get metkit git sha1 version.
- Returns:
const char* git sha1 version string
-
metkit_error_t metkit_initialise()#
Initialise Main() context.
Note
This is ONLY required when Main() is NOT initialised, such as loading the MetKit as shared library in Python.
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_parse_marsrequests(const char *str, metkit_requestiterator_t **requests, bool strict)#
Parse MARS requests into RequestIterator of Request instances. Resulting RequestIterator must be deallocated with metkit_delete_requestiterator
- Parameters:
str – MARS requests
requests – [out] Allocates RequestIterator object
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_parse_marsrequest(const char *str, metkit_marsrequest_t *request, bool strict)#
Parse MARS request into Request instance
Note
will error if request expands to multiple requests: use metkit_parse_marsrequests instead
- Parameters:
str – MARS request
request – [out] Request instance
strict – if true, raise error rather than warning on invalid values
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_new(metkit_marsrequest_t **request)#
Allocates new Request object. Must be deallocated with mekit_delete_request
- Parameters:
request – [out] new Request instance
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_delete(const metkit_marsrequest_t *request)#
Deallocates Request object and associated resources.
- Parameters:
request – Request instance
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_set(metkit_marsrequest_t *request, const char *param, const char *values[], int numValues)#
Add parameter and values to request
- Parameters:
request – Request instance
param – parameter name
values – array of values for parameter
numValues – number of values
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_set_one(metkit_marsrequest_t *request, const char *param, const char *value)#
Add parameter and values to request
- Parameters:
request – Request instance
param – parameter name
values – value to add
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_set_verb(metkit_marsrequest_t *request, const char *verb)#
Set verb in Request object
- Parameters:
request – Request instance
verb – verb to set
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_verb(const metkit_marsrequest_t *request, const char **verb)#
Returns the verb in Request object
- Parameters:
request – Request instance
verb – [out] verb in request
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_has_param(const metkit_marsrequest_t *request, const char *param, bool *has)#
Returns whether parameter is in Request object
- Parameters:
request – Request instance
param – parameter name
has – [out] whether parameter exists in request
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_params(const metkit_marsrequest_t *request, metkit_paramiterator_t **params)#
Returns parameter iterator for Request object Must be deallocated with metkit_paramiterator_delete
Note
: The strings obtained from next() are owned by the iterator and should be copied if they need to outlive it.
- Parameters:
request – Request instance
params – [out] parameter iterator
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_count_values(const metkit_marsrequest_t *request, const char *param, size_t *count)#
Returns number of values for specific parameter in Request object
- Parameters:
request – Request instance
param – parameter name in request
count – [out] number of values for param in request
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_value(const metkit_marsrequest_t *request, const char *param, int index, const char **value)#
Returns value for specific parameter and index in Request object
- Parameters:
request – Request instance
param – parameter name in request
index – index of value to retrieve for param in request
value – [out] retrieved value
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_expand(const metkit_marsrequest_t *request, bool inherit, bool strict, metkit_marsrequest_t *expandedRequest)#
Populates empty Request object by expanding existing request
- Parameters:
request – Request instance to be expanded
inherit – if true, populate expanded request with default values
strict – it true, raise error rather than warning on invalid values
expandedRequest – [out] empty Request instance to be populated
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_marsrequest_merge(metkit_marsrequest_t *request, const metkit_marsrequest_t *otherRequest)#
Merges other Request object into existing request
- Parameters:
request – Request instance to contain result of merge
otherRequest – other Request instance to merge
- Returns:
metkit_error_t Error code
-
metkit_error_t metkit_requestiterator_delete(const metkit_requestiterator_t *it)#
Deallocates RequestIterator object and associated resources.
- Parameters:
it – RequestIterator instance
- Returns:
metkit_error_t Error code
-
metkit_iterator_status_t metkit_requestiterator_next(metkit_requestiterator_t *it)#
Moves to the next Request element in RequestIterator
- Parameters:
it – RequestIterator instance
- Returns:
metkit_iterator_status_t Status of iterator
-
metkit_iterator_status_t metkit_requestiterator_current(metkit_requestiterator_t *it, metkit_marsrequest_t *request)#
Populates empty Request object with data from current element in RequestIterator
Example usage: while (metkit_requestiterator_next(it) == METKIT_ITERATOR_SUCCESS) { metkit_marsrequest_t* req{}; metkit_marsrequest_new(&req); metkit_requestiterator_current(it, req); // use req … }
Note
must call metkit_requestiterator_next before calling metkit_requestiterator_current.
- Parameters:
it – RequestIterator instance
request – empty Request instance to populate with data
- Returns:
metkit_iterator_status_t Status of iterator
-
metkit_error_t metkit_paramiterator_delete(const metkit_paramiterator_t *it)#
Deallocates ParamIterator object and the char* strings it owns.
- Parameters:
it – ParamIterator instance
- Returns:
metkit_error_t Error code
-
metkit_iterator_status_t metkit_paramiterator_next(metkit_paramiterator_t *it)#
Moves to the next parameter in ParamIterator
- Parameters:
it – ParamIterator instance
- Returns:
metkit_iterator_status_t Status of iterator
-
metkit_iterator_status_t metkit_paramiterator_current(const metkit_paramiterator_t *it, const char **param)#
Returns current parameter in ParamIterator
- Parameters:
it – ParamIterator instance
param – [out] current parameter
- Returns:
metkit_iterator_status_t Status of iterator