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"
#include <stdint.h>

#ifdef __cplusplus
}
#endif

enum {
	KEY_VALUE=1<<1,
	KEY_FLAGS=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);

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

/* Meta Info */
const Key *keyNextMeta (Key *key); /* TODO: remove, currently only needed for directoryvalue-plugin */
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);

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);

uint16_t ksIncRef (KeySet * ks);
uint16_t ksDecRef (KeySet * ks);
uint16_t ksGetRef (const KeySet * ks);

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);

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

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

ssize_t ksSearch (const KeySet * ks, const Key * toAppend);

#ifdef __cplusplus
}
}
#endif

#endif /* KDB_H */