kdb.h.in

/**
 * @file
 *
 * @brief Exported methods of the Library
 *
 * The documentation is in source files, not in this header file.
 * Enum types and macros are documented in src/libs/elektra/kdbenum.c.
 *
 * For already rendered API documentation, see https://doc.libelektra.org/api/
 *
 * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
 */

// clang-format off

@DISCLAMER@

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the BSD License (revised).                      *
 *                                                                         *
 ***************************************************************************/

#ifndef KDB_H
#define KDB_H

#define ELEKTRA_SENTINEL // needed for SWIG
#define KDB_VERSION "@KDB_VERSION@"
#define KDB_VERSION_MAJOR @KDB_VERSION_MAJOR@
#define KDB_VERSION_MINOR @KDB_VERSION_MINOR@
#define KDB_VERSION_PATCH @KDB_VERSION_PATCH@
#define KDB_PATH_SEPARATOR '/'
#define KDB_PATH_ESCAPE '\\'
#cmakedefine ELEKTRA_ENABLE_OPTIMIZATIONS

#ifdef __cplusplus
extern "C" {
#endif

#include "kdbos.h"

#ifdef __cplusplus
}
#endif

enum {
	KEY_NAME=1,
	KEY_VALUE=1<<1,
	KEY_FLAGS=3,
	KEY_COMMENT=1<<3,
	KEY_BINARY=1<<4,
	KEY_SIZE=1<<11,
	KEY_FUNC=1<<12,
	KEY_META=1<<15,
	KEY_NULL=1<<16,
	KEY_LOCK_NAME=1<<17,
	KEY_LOCK_VALUE=1<<18,
	KEY_LOCK_META=1<<19,
};

#ifdef __cplusplus
#define KEY_END (static_cast<void *> (0))
#else
#define KEY_END ((void *) 0)
#endif

typedef int elektraLockFlags;
typedef int elektraKeyFlags;

enum {
	KEY_CP_NAME   = 1<<0,
	KEY_CP_STRING = 1<<1,
	KEY_CP_VALUE  = 1<<2,
	KEY_CP_META   = 1<<3,
	KEY_CP_ALL    = KEY_CP_NAME | KEY_CP_VALUE | KEY_CP_META,
};
typedef unsigned int elektraCopyFlags;

enum {
	KDB_O_NONE=0,
	KDB_O_DEL=1,
	KDB_O_POP=1<<1
};
typedef int elektraLookupFlags;

enum {
	KEY_NS_NONE=0,
	KEY_NS_CASCADING=1,
	KEY_NS_META=2,
	KEY_NS_SPEC=3,
	KEY_NS_PROC=4,
	KEY_NS_DIR=5,
	KEY_NS_USER=6,
	KEY_NS_SYSTEM=7,
	KEY_NS_DEFAULT=8,
};
typedef int elektraNamespace;

static const elektraNamespace KEY_NS_FIRST = KEY_NS_META;
static const elektraNamespace KEY_NS_LAST = KEY_NS_DEFAULT;

typedef ssize_t elektraCursor;


#ifdef __cplusplus
namespace ckdb {
extern "C" {
#endif

typedef struct _KDB	KDB;
typedef struct _Key	Key;
typedef struct _KeySet	KeySet;


/**************************************
 *
 * KDB methods
 *
 **************************************/

KDB * kdbOpen(const KeySet * contract, Key *parentKey);

int kdbClose(KDB *handle, Key *errorKey);

int kdbGet(KDB *handle, KeySet *returned,
	Key *parentKey);
int kdbSet(KDB *handle, KeySet *returned,
	Key *parentKey);

/**************************************
 *
 * Key methods
 *
 **************************************/

/* Basic Methods */
Key *keyNew(const char *keyname, ...) ELEKTRA_SENTINEL;
Key *keyVNew(const char *keyname, va_list ap);

Key * keyCopy(Key *dest, const Key *source, elektraCopyFlags flags);

int keyClear(Key *key);
int keyDel(Key *key);

ssize_t keyIncRef(Key *key);
ssize_t keyDecRef(Key *key);
ssize_t keyGetRef(const Key *key);

/* Meta Info */
int keyRewindMeta(Key *key);
const Key *keyNextMeta(Key *key);
const Key *keyCurrentMeta(const Key *key);

int keyCopyMeta(Key *dest, const Key *source, const char *metaName);
int keyCopyAllMeta(Key *dest, const Key *source);

const Key *keyGetMeta(const Key *key, const char* metaName);
ssize_t    keySetMeta(Key *key, const char* metaName,
	const char *newMetaString);
KeySet * keyMeta (Key * key);

/* Methods for Making Tests */
int keyCmp(const Key *k1, const Key *k2);

int keyNeedSync(const Key *key);

int keyIsBelow(const Key *key, const Key *check);
int keyIsBelowOrSame(const Key *key, const Key *check);
int keyIsDirectlyBelow(const Key *key, const Key *check);

int keyIsBinary(const Key *key);
int keyIsString(const Key *key);

/* Name Manipulation Methods */
const char *keyName(const Key *key);
ssize_t keyGetNameSize(const Key *key);
ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize);

ssize_t keySetName(Key *key, const char *newname);
ssize_t keyAddName(Key *key, const char *addName);

const void *keyUnescapedName(const Key *key);
ssize_t keyGetUnescapedNameSize(const Key *key);

const char *keyBaseName(const Key *key);
ssize_t keyGetBaseNameSize(const Key *key);
ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize);

ssize_t keySetBaseName(Key *key,const char *baseName);
ssize_t keyAddBaseName(Key *key,const char *baseName);

elektraNamespace keyGetNamespace(Key const* key);
ssize_t keySetNamespace(Key * key, elektraNamespace ns);

/* Value Manipulation Methods */
const void *keyValue(const Key *key);
ssize_t keyGetValueSize(const Key *key);

const char *keyString(const Key *key);
ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
ssize_t keySetString(Key *key, const char *newString);

ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);

int keyLock (Key * key, elektraLockFlags what);
int keyIsLocked (const Key * key, elektraLockFlags what);

static inline Key *keyDup (const Key *source, elektraCopyFlags flags)
{
	return keyCopy (keyNew ("/", KEY_END), source, flags);
}

/**************************************
 *
 * KeySet methods
 *
 **************************************/

KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL;
KeySet *ksVNew(size_t alloc, va_list ap);

KeySet *ksDup(const KeySet * source);
int ksCopy(KeySet *dest, const KeySet *source);

int ksClear(KeySet *ks);
int ksDel(KeySet *ks);

ssize_t ksGetSize(const KeySet *ks);

ssize_t ksAppendKey(KeySet *ks, Key *toAppend);

ssize_t ksAppend(KeySet *ks, const KeySet *toAppend);
KeySet *ksCut(KeySet *ks, const Key *cutpoint);

Key *ksPop(KeySet *ks);

int ksRewind(KeySet *ks);
Key *ksNext(KeySet *ks);
Key *ksCurrent(const KeySet *ks);

Key *ksHead(const KeySet *ks);
Key *ksTail(const KeySet *ks);

elektraCursor ksGetCursor(const KeySet *ks);
int ksSetCursor(KeySet *ks, elektraCursor cursor);
Key *ksAtCursor(KeySet *ks, elektraCursor cursor);

Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options);
Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options);

#ifdef __cplusplus
}
}
#endif


#endif /* KDB_H */