From Elektra Initiative

Elektra's API consists of 3 classes of objects and methods to manipulate them. The main implementation of the library is written in C and is fully documented in Doxygen.

The classes are:

KeyDB

A class of static methods only. You can't instantiate an object of this class. All the business logic for retrieving and commiting key data to physical media is owned by this class. Example methods are kdbSetKey, kdbGetKey, kdbGetValue, kdbGet, kdbSet etc. This last is one of the most powerful, returning a KeySet containing all child keys of a folder key, with the option to retrieve them recursively, sorted, with or without folders, etc.

Key

The obvious entity class. Contains key's name, data and metadata. Example of its methods are keySetName, keySetUID, keyGetString, keyIsDir, etc.

KeySet

A group of Keys. Real applications use to get and set several keys, and this class is used to store corelated keys that were retrieved together in one shot. Example of its methods are ksAppend, ksAppendKey, ksPop etc.

Example Program

Here is an example of how to use the Elektra API. This program will get all keys that matter under system/sw/MyApp manipulate some, and re-save them.

/*********************************************************

To compile this example:

	$ cc `pkg-config --libs elektra` `pkg-config --cflags elektra` -o application application.c
		or static
	$ cc -c `pkg-config --cflags elektra` application.c

This application shows how to read (resp. update) and save
configuration using elektra.

**********************************************************/

#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <kdb.h>

#define MY_APP_ROOT   "/sw/MyApp/current"


/* Read config keys for this application */
int readConfig(KDB * handle, KeySet *myConfig)
{
	int rc = 0;
	int size = 0;

	/* Get all value keys for this application */
	if (kdbGetByName(handle, myConfig, "system" MY_APP_ROOT, 0) == -1)
	{
		rc = -1;
		perror("Couldn't get system configuration. Reason");
	} else {
		size = (int)ksGetSize(myConfig);
		printf("Retrieved %d keys\n", size);
	}

	if (kdbGetByName(handle, myConfig,"user" MY_APP_ROOT,  0) == -1)
	{
		rc = -1;
		perror("Couldn't get user configuration. Reason");
	} else {
		size = (int)ksGetSize(myConfig);
		printf("Retrieved %d keys\n", size);
	}

	if (rc == -1) return -1;
	return size;
}


/* Change some keys */
void changeConfig(KeySet *myConfig)
{
	Key *current;
	
	ksRewind(myConfig);
	while ((current=ksNext(myConfig))) {
		char keyName[MAX_KEY_LENGTH];
		char value[MAX_KEY_LENGTH];
		
		keyGetFullName(current,keyName,sizeof(keyName));
		keyGetString(current,value,sizeof(value));
		
		printf("Key %s was %s. ", keyName, value);
		
		/* Add "- modified" to the end of the string */
		strcat(value,"- modified");
		
		/* change the key value */
		keySetString(current,value);
		
		/* reget it, just as an example */
		keyGetString(current,value,sizeof(value));
		
		printf("Now is %s\n", value);
	}
}

/* Make keys empty */
void emptyConfig(KeySet *myConfig)
{
	ksRewind(myConfig);
	while (ksNext(myConfig))
	{
		keySetString(ksCurrent(myConfig), "");
	}
}



/* Save the modified keys */
int saveConfig(KDB * handle, KeySet *myConfig)
{
	return kdbSet(handle,myConfig,0,0);
}


int main(int argc, char **argv)
{
	int command;
	KeySet *myConfig=ksNew(0);
	KDB * handle=kdbOpen();

	while (1)
	{
		/* Get configuration values, and just continue if there is no error */
		readConfig(handle,myConfig);

		changeConfig(myConfig);
		saveConfig(handle,myConfig);

		command = fgetc (stdin);
		if (command == 'q') break;
		switch (command)
		{
			case 'e':
				emptyConfig(myConfig);
				saveConfig(handle, myConfig);
				break;
			case 'd':
				ksClear(myConfig);
				break;
		}
	}

	kdbClose(handle);

	/* Free all keys and resources in the key set */
	ksDel(myConfig);

	return 0;
}

Compiling and Linking

All Elektra methods are declared in the /usr/include/kdb.h file and defined in the /lib/libelektra.so library. So to compile it you simply need to:

  bash$ cc `pkg-config --libs elektra` -o myapp myapp.c

or, if you don't have pkg-config:

  bash$ cc -L /lib -lelektra -o myapp myapp.c