dlite-storage#

Opens and closes storages.

Querying content of a storage

void *dlite_storage_iter_create(DLiteStorage *s, const char *pattern)#

Returns a new iterator over all instances in storage s who’s metadata URI matches pattern.

Returns NULL on error.

int dlite_storage_iter_next(DLiteStorage *s, void *iter, char *buf)#

Writes the UUID to buffer pointed to by buf of the next instance in iter, where iter is an iterator created with dlite_storage_iter_create().

Returns zero on success, 1 if there are no more UUIDs to iterate over and a negative number on other errors.

void dlite_storage_iter_free(DLiteStorage *s, void *iter)#: Free’s iterator created with dlite_storage_iter_create().

int dlite_storage_delete(DLiteStorage *s, const char *id)#: Delete instance from storage s using the deleteInstance api. Returns non-zero on error or if deleteInstance is not supported.

char *dlite_storage_help(DLiteStorage *s)#: Returns a malloc’ed string with plugin documentation or NULL on error.

char **dlite_storage_uuids(const DLiteStorage *s, const char *pattern)#

Returns the UUIDs off all instances in storage s whos metadata URI matches the glob pattern pattern. If pattern is NULL, it matches all instances.

The UUIDs are returned as a NULL-terminated array of string pointers. The caller is responsible to free the returned array with dlite_storage_uuids_free().

Not all plugins may implement this function. In that case, NULL is returned.

void dlite_storage_uuids_free(char **uuids)#: Frees NULL-terminated array of instance names returned by dlite_storage_uuids().

Storage paths

FUPaths *dlite_storage_paths(void)#: Returns pointer to storage paths.a

void dlite_storage_paths_free(void)#: Free’s up memory used by storage paths.

int dlite_storage_paths_insert(int n, const char *path)#

Inserts path into storage paths before position n. If n is negative, it counts from the end (like Python).

Returns the index of the newly inserted element or -1 on error.

int dlite_storage_paths_append(const char *path)#

Appends path to storage paths.

Returns the index of the newly inserted element or -1 on error.

int dlite_storage_paths_remove_index(int index)#

Removes path with index n from storage paths. If n is negative, it counts from the end (like Python).

Returns non-zero on error.

const char **dlite_storage_paths_get()#

Returns a NULL-terminated array of pointers to paths/urls or NULL if no storage paths have been assigned.

The returned array is owned by DLite and should not be free’ed. It may be invalidated by further calls to dlite_storage_paths_insert() and dlite_storage_paths_append().

DLiteStoragePathIter *dlite_storage_paths_iter_start()#

Returns an iterator over all files in storage paths (with glob patterns in paths expanded).

Returns NULL on error.

Should be used together with dlite_storage_path_iter_next() and dlite_storage_path_iter_stop().

const char *dlite_storage_paths_iter_next(DLiteStoragePathIter *iter)#: Returns name of the next file in the iterator iter created with dlite_storage_paths_iter_start() or NULL if there are no more matches.

Note

The returned string is owned by the iterator. It will be overwritten by the next call to fu_nextmatch() and should not be changed. Use strdup() or strncpy() if a copy is needed.

int dlite_storage_paths_iter_stop(DLiteStoragePathIter *iter)#: Stops and deallocates iterator created with dlite_storage_paths_iter_start().

Hotlist of open storages for fast access to instances using

get_instance(). Mostly intended for internal use.

int dlite_storage_hotlist_clear()#

Clears the storage hotlist.

Returns non-zero on error.

int dlite_storage_hotlist_add(const DLiteStorage *s)#

Adds storage s to list of open storages for fast lookup of instances.

Returns non-zero on error.

int dlite_storage_hotlist_remove(const DLiteStorage *s)#

Remove storage s from hotlist.

Returns zero on success. One is returned if s is not in the hotlist. For other errors a negative number is returned.

int dlite_storage_hotlist_iter_init(DLiteStorageHotlistIter *iter)#

Initialise hotlist iterator iter.

Returns non-zero on error.

const DLiteStorage *dlite_storage_hotlist_iter_next(DLiteStorageHotlistIter *iter)#: Returns a pointer to next hotlisted storage or NULL if the iterator is exausted (or on other errors).

int dlite_storage_hotlist_iter_deinit(DLiteStorageHotlistIter *iter)#: Deinitialise hotlist iterator iter. Returns non-zero on error.

Typedefs

typedef struct _DLiteStorage DLiteStorage#

Opaque type for a DLiteStorage.

Nothing is actually declared to be a DLiteStorage, but all plugin data structures can be cast to DLiteStorage.

typedef struct _DLiteInstance DLiteInstance#: Opaque type for an instance.

typedef struct _DLiteStoragePathIter DLiteStoragePathIter#: Iterator over dlite storage paths.

typedef size_t DLiteStorageHotlistIter#: Iterator over hotlisted storages

typedef enum _DLiteIDFlag DLiteIDFlag#: Flags for how to handle instance IDs.

Enums

enum _DLiteIDFlag#

Flags for how to handle instance IDs.

Values:

enumerator dliteIDTranslateToUUID#: Translate id’s that are not a valid UUID to a (version 5) UUID (default).

enumerator dliteIDRequireUUID#: Require that id is a valid UUID.

enumerator dliteIDKeepID#: Store data under the given id, even if it is not a valid UUID. Not SOFT compatible, but may be useful for input files.

Functions

DLiteStorage *dlite_storage_open(const char *driver, const char *location, const char *options)#

Opens a storage located at location using driver. Returns a opaque pointer or NULL on error.

The options are passed to the driver. Options for known drivers are:

hdf5
  - rw   Read and write: open existing file or create new file (default)
  - r    Read-only: open existing file for read-only
  - w    Write: truncate existing file or create new file
  - a    Append: open existing file for read and write

DLiteStorage *dlite_storage_open_url(const char *url)#

Like dlite_storage_open(), but takes as input an url of the form driver://location?options. The question mark and options may be left out.

Returns a new storage, or NULL on error.

int dlite_storage_close(DLiteStorage *s)#: Closes storage s. Returns non-zero on error.

int dlite_storage_flush(DLiteStorage *s)#: Flush storage s. Returns non-zero on error.

DLiteIDFlag dlite_storage_get_idflag(const DLiteStorage *s)#: Returns the current mode of how to handle instance IDs.

void dlite_storage_set_idflag(DLiteStorage *s, DLiteIDFlag idflag)#: Sets how instance IDs are handled.

DLiteInstance *dlite_storage_load(const DLiteStorage *s, const char *id)#: Loads instance from storage s using the loadInstance api. Returns NULL on error or if loadInstance is not supported.

int dlite_storage_is_writable(const DLiteStorage *s)#: Returns non-zero if storage s is writable.

const char *dlite_storage_get_driver(const DLiteStorage *s)#: Returns name of driver associated with storage s.