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

enum metkit_error_values_t#

Values:

enumerator METKIT_SUCCESS#
enumerator METKIT_ERROR#
enumerator METKIT_ERROR_UNKNOWN#
enumerator METKIT_ERROR_USER#
enumerator METKIT_ERROR_ASSERT#
enum metkit_iterator_status_t#

Values:

enumerator METKIT_ITERATOR_SUCCESS#
enumerator METKIT_ITERATOR_COMPLETE#
enumerator METKIT_ITERATOR_ERROR#

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