dlite-misc

dlite-misc#

Main header file for dlite.

Wrappers around error functions

The DLITE_NOERR() and DLITE_NOERR_END macros are intended to mark a code block in which the specified errors will not be printed. Use them as follows:

DLITE_NOERR(DLITE_ERRBIT(DLiteIOError) | DLITE_ERRBIT(DLiteRuntimeError));
  // code block where IO and runtime errors are ignored
  ...
DLITE_NOERR_END;

DLITE_ERRBIT(code)#

DLITE_NOERR(mask)#

DLITE_NOERR_END#

dlite_deprecation_warning(version_removed, descr)#

typedef int64_t DLiteErrMask#

DLiteErrMask *_dlite_err_mask_get(void)#

void _dlite_err_mask_set(DLiteErrMask mask)#

void dlite_err_ignored_set(DLiteErrCode code, int value)#: Set whether to ignore printing given error code.

int dlite_err_ignored_get(DLiteErrCode code)#: Return whether printing is ignored for given error code.

const char *dlite_errmsg(void)#: Return current error message.

void dlite_fatal(int eval, const char *msg, ...)#

void dlite_fatalx(int eval, const char *msg, ...)#

int dlite_err(int eval, const char *msg, ...)#

int dlite_errx(int eval, const char *msg, ...)#

int dlite_warn(const char *msg, ...)#

int dlite_warnx(const char *msg, ...)#

int dlite_info(const char *msg, ...)#

int dlite_debug(const char *msg, ...)#

void dlite_vfatal(int eval, const char *msg, va_list ap)#

void dlite_vfatalx(int eval, const char *msg, va_list ap)#

int dlite_verr(int eval, const char *msg, va_list ap)#

int dlite_verrx(int eval, const char *msg, va_list ap)#

int dlite_vwarn(const char *msg, va_list ap)#

int dlite_vwarnx(const char *msg, va_list ap)#

int dlite_vinfo(const char *msg, va_list ap)#

int dlite_vdebug(const char *msg, va_list ap)#

int dlite_errval(void)#

void dlite_errclr(void)#

FILE *dlite_err_get_stream(void)#

FILE *dlite_err_set_stream(FILE *stream)#

void dlite_err_set_file(const char *filename)#

int dlite_err_set_level(int level)#

int dlite_err_get_level(void)#

const char *dlite_err_set_levelname(const char *name)#

const char *dlite_err_get_levelname(void)#

int dlite_err_set_warn_mode(int mode)#

int dlite_err_get_warn_mode(void)#

int dlite_err_set_debug_mode(int mode)#

int dlite_err_get_debug_mode(void)#

int dlite_err_set_override_mode(int mode)#

int dlite_err_get_override_mode(void)#

int _dlite_deprecation_warning(const char *version_removed, const char *filepos, const char *func, const char *descr)#

General dlite utility functions

enum DLiteIdType#

Ways to express an instance ID.

Values:

enumerator dliteIdRandom#: new random version 4 UUID

enumerator dliteIdHash#: new version 5 UUID with DNS namespace

enumerator dliteIdCopy#: copy UUID

const char *dlite_get_version(void)#: Returns static pointer to a string with the current version of DLite.

FUPlatform dlite_get_platform(void)#: Returns current platform based on the DLITE_PLATFORM environment variable. Used when initiating paths.

int dlite_isuuid(const char *id)#: Returns non-zero if id is a valid UUID.

DLiteIdType dlite_idtype(const char *id)#: Returns the ID type of id.

DLiteIdType dlite_idtypen(const char *id, int len)#: Like dlite_idtype(), but takes the the length of id as an additional argument.

int dlite_normalise_id(char *buff, size_t n, const char *id, const char *uri)#

Write normalised id to buff, which is a buffer of size n.

The normalisation is done according to the following table:

ID	Normalised ID
NULL	NULL
uuid	ns / uuid
uri / uuid	uri / uuid
uri	uri
name	ns / name

where;

uuid is a valid UUID. Ex: “0a46cacf-ce65-5b5b-a7d7-ad32deaed748”
ns is the predefined namespace string “http://onto-ns.com/data”
uri is a valid URI with no query or fragment parts. Ex: “http://onto-ns.com/meta/0.1/MyDatamodel”
name is a string that is neither a UUID or a URL. Ex: “aa6060”

A final hash or slash in id is stripped off.

Return the number of bytes written buff (excluding the terminating NUL) or would have been written to buff if it is not large enough. A negative number is returned on error.

int dlite_normalise_idn(char *buff, size_t n, const char *id, size_t len, const char *uri)#: Like dlite_normalise_id(), but takes len, the the length of id as an additional argument.

DLiteIdType dlite_get_uuid(char *buff, const char *id)#

Writes instance UUID to buff based on id.

Length of buff must at least (DLITE_UUID_LENGTH + 1) bytes (36 bytes for UUID + NUL termination).

The UUID is calculated according to this table.

where:

uuid is a valid UUID. Ex: “0a46cacf-ce65-5b5b-a7d7-ad32deaed748”
ns is the predefined namespace string “http://onto-ns.com/data”
uri is a valid URI with no query or fragment parts. Ex: “http://onto-ns.com/meta/0.1/MyDatamodel”
name is a string that is neither a UUID or a URL. Ex: “aa6060”

A version 4 UUID is used for the random UUID and a version 5 UUID (with the DNS namespace) is used fhr the hash.

Returns the DLite ID type or a negative error code on error.

DLiteIdType dlite_get_uuidn(char *buff, const char *id, size_t len)#: Like dlite_get_uuid(), but takes the the length of id as an additional parameter.

DLiteIdType _dlite_get_uuidn(char *buff, const char *id, size_t len, int namespacedID)#

char *dlite_join_meta_uri(const char *name, const char *version, const char *namespace)#

Returns an unique uri for metadata defined by name, version and namespace as a newly malloc()’ed string or NULL on error.

The returned uri is constructed as follows:

namespace/version/name

int dlite_split_meta_uri(const char *uri, char **name, char **version, char **namespace)#

Splits metadata uri into its components. If name, version and/or namespace are not NULL, the memory they points to will be set to a pointer to a newly malloc()’ed string with the corresponding value.

Returns non-zero on error.

Parsing options

enum DLiteOptFlag#

Values:

enumerator dliteOptDefault#: Default option flags

enumerator dliteOptStrict#: Stict mode. Its an error if option is unknown

typedef struct _DLiteOpt DLiteOpt#: Struct used by dlite_getopt()

int dlite_option_parse(char *options, DLiteOpt *opts, DLiteOptFlag flags)#

Parses the options string options and assign corresponding values of the array opts. The options string should be a valid url query string of the form:

key1=value1;key2=value2...

where the values should be encoded with uri_encode() and terminated by NUL or any of the characters in “;&#”. A hash (#) terminates the options.

At return, options is modified. All values in the options string will be URI decoded and NUL-terminated.

opts should be a NULL-terminated DLiteOpt array initialised with default values. At return, the values of the provided options are updated.

flags should be zero or dliteOptStrict.

Returns non-zero on error.

Example

If the opts array only contains a few elements, accessing it by index is probably the most convinient. However, if it contains many elements, switch might be a better option using the following pattern:

int i;
DLiteOpt opts[] = {
  {'1', "key1", "default1", "description of key1..."},
  {'b', "key2", "default2", "description of key2..."},
  {NULL, NULL}
};
dlite_getopt(options, opts);
for (i=0; opts[i].key; i++) {
  switch (opts[i].c) {
  case '1':
    // process option key1
    break;
  case 'b':
    // process option key2
    break;
  }
}

Managing global state

typedef struct _Session DLiteGlobals#: Globals handle.

void dlite_init(void)#

void dlite_finalize(void)#

DLiteGlobals *dlite_globals_get(void)#: Returns reference to globals handle.

void dlite_globals_set(DLiteGlobals *globals_handler)#: Set globals handle.

int dlite_globals_add_state(const char *name, void *ptr, void (*free_fun)(void *ptr))#

Add global state with given name.

ptr is a pointer to the state and free_fun is a function that frees it. Returns non-zero on error.

int dlite_globals_remove_state(const char *name)#: Remove global state with the given name. Returns non-zero on error.

void *dlite_globals_get_state(const char *name)#: Returns global state with given name or NULL on error.

int dlite_globals_in_atexit(void)#: Returns non-zero if we are in an atexit handler.

void dlite_globals_set_atexit(void)#: Mark that we are in an atexit handler.

Path handling

char *dlite_join_url(const char *driver, const char *location, const char *options, const char *fragment)#

Returns a newly allocated url constructed from the arguments of the form

driver://location?options#fragment

The driver, options and fragment arguments may be NULL. Returns NULL on error.

int dlite_split_url(char *url, char **driver, char **location, char **options, char **fragment)#

Splits an url of the form

driver://location?options#fragment

into four parts: driver, location, options and fragment. For the arguments that are not NULL, the pointers they points to will be assigned to point to the corresponding section within url.

This function modifies url. Make a copy if you don’t want that.

Returns non-zero on error.

Note

: URLs are assumed to have the following syntax (ref. wikipedia):

URL = scheme:[//authority]path[?query][#fragment]

where the authority component divides into three subcomponents:

authority = [userinfo@]host[:port]

This function maps scheme to driver, [authority]path to location query to options and fragment to fragment.

int dlite_split_url_winpath(char *url, char **driver, char **location, char **options, char **fragment, int winpath)#

Like dlite_split_url(), but with one additional argument.

If winpath is non-zero and url

starts with “C:" or “C:/”, then

the initial “C” is not treated as a driver, but rather as a part of the location.

int dlite_use_build_root(void)#: Returns non-zero if paths should refer to build root instead of installation root.

void dlite_set_use_build_root(int v)#: Sets whether paths should refer to build root. Default is the installation root, unless the environment variable DLITE_USE_BUILD_ROOT is set and is not false.

const char *dlite_root_get(void)#: Returns pointer to installation root. It may be altered with environment variable DLITE_ROOT.

const char *dlite_pkg_root_get(void)#

Returns pointer to the DLite package installation root.

It may be altered with environment variable DLITE_PKG_ROOT. With Python, it defaults to the DLite Python root directory, otherwise it defaults to DLITE_ROOT.

int dlite_add_dll_path(void)#

On Windows, this function adds default directories to the DLL search path. Based on whether the DLITE_USE_BUILDROOT environment variable is defined, the library directories under either the build directory or the installation root (environment variable DLITE_ROOT) are added to the DLL search path using AddDllDirectory().

On Linux this function does nothing.

Returns non-zero on error.

Functions controlling whether to hide warnings

Warning parameters:

warnings_hide: whether to hide warnings (see below).
warnings_pattern: glob pattern matching the warning message.

If warnings_pattern is NULL, warnings are hidden if warnings_hide is non-zero.

If warnings_pattern is not NULL, then warnings are hidden if:

warnings_pattern match the warning message and warnings_hide is non-zero.
warnings_pattern don’t match the warning message and warnings_hide is zero.

int dlite_get_warnings_hide(const char **pattern)#

Return parameters controlling whether warnings should be hidden.

If *pattern is not NULL, it is assigned to a static pointer to warnings_pattern (owned by DLite).

Returns warnings_hide.

void dlite_set_warnings_hide(int hide, char *pattern)#: Set parameters controlling whether warnings should be hidden.

Defines

DLITE_UUID_LENGTH#: length of an uuid (excl. NUL-termination)

DLITE_DATA_NS#: Fallback namespace for data instances

struct _DLiteOpt#

#include <dlite-misc.h>

Struct used by dlite_getopt()

Public Members

int c#: Integer identifier for this option

const char *key#: Option key

const char *value#: Option value, initialised with default value

const char *descr#: Description of this option

dlite-misc

Contents

dlite-misc#