Elektra Projekt
Enumerations | Functions

Streaming

Methods to output, generate and toXML Keys and Keysets. More...

Enumerations

enum  KDBStream {
  KDB_O_SHOWMETA = 0xF0, KDB_O_SHOWFLAGS = 1<<14, KDB_O_SHOWINDICES = 1<<15, KDB_O_CONDENSED = 1<<16,
  KDB_O_NUMBER = 1<<17, KDB_O_HEADER = 1<<18, KDB_O_FULLNAME = 1<<19, KDB_O_HIER = 1<<20
}

Functions

int ksFromXMLfile (KeySet *ks, const char *filename)
int ksFromXML (KeySet *ks, int fd)
ssize_t keyToStream (const Key *key, FILE *stream, option_t options)
ssize_t keyToStreamBasename (const Key *key, FILE *stream, const char *parent, const size_t parentSize, option_t options)
ssize_t ksToStream (const KeySet *ks, FILE *stream, option_t options)
int keyOutput (const Key *k, FILE *stream, option_t options)
int ksOutput (const KeySet *ks, FILE *stream, option_t options)
int keyGenerate (const Key *key, FILE *stream, option_t options)
int ksGenerate (const KeySet *ks, FILE *stream, option_t options)

Detailed Description

Methods to output, generate and toXML Keys and Keysets.

Here are some functions that are in a separate library because they depend on non-basic libraries as libxml. Link against kdbtools library if your program won't be installed in /bin, or is not essential in early boot stages.

It is also possible to have a dynamic linkage, see the sourcecode from kdb-tool or testing framework how to achieve that.

Output prints keys line per line, meaned to be read by humans.

Generate prints keys and keysets as C-Structs, meaned to be read by a C-Compiler.

toXML prints keys and keysets as XML, meaned to be used as exchange format.

To use them:

#include <kdbtools.h>

Enumeration Type Documentation

enum KDBStream

Options to change the default behavior of streaming.

On default the streaming options only output the names of the given keysets. If you want more information, header, metainfo, compressed output, full names, values or comments you will find the appropriate options here.

For full influence of value, comment and metadata shown, use these options together with #keyswitch_t. All bits of meta-information ORed together are KDB_O_SHOWMETA.

For more information about the flags, consult the documentation of the streaming methods.

These options can be ORed. That is the |-Operator in C.

It uses the values defined in #keyswitch_t too, so it starts with 14.

See also:
kdbGetChildKeys()
ksToStream()
keyToStream()
Enumerator:
KDB_O_SHOWMETA 

Show all metadata (type, uid, gid, mode)

KDB_O_SHOWFLAGS 

Show all flags

KDB_O_SHOWINDICES 

Show the indices for the entries

KDB_O_CONDENSED 

Spare any whitespaces and do not group visually together.

KDB_O_NUMBER 

Use a number intead of user and group name.

KDB_O_HEADER 

Show also the header of the document.

KDB_O_FULLNAME 

Export user keys using full name.

KDB_O_HIER 

Export to the new hierarchical XML representation using key basename. See ksToStream().


Function Documentation

int keyGenerate ( const Key *  key,
FILE *  stream,
option_t  options 
)

Generate a C-Style key and stream it.

This keyset can be used to include as c-code for applikations using elektra.

Parameters:
keythe key object to work with
streamthe file pointer where to send the stream
optionsKDB_O_SHOWINDICES, KDB_O_IGNORE_COMMENT, KDB_O_SHOWINFO
Returns:
1 on success
int keyOutput ( const Key *  k,
FILE *  stream,
option_t  options 
)

Output every information of a single key depending on options.

The format is not very strict and only intend to be read by human eyes for debugging purposes. Don't rely on the format in your applications.

Parameters:
kthe key object to work with
streamthe file pointer where to send the stream
optionssee text above
See also:
ksOutput()
Returns:
1 on success
-1 on allocation errors
ssize_t keyToStream ( const Key *  key,
FILE *  stream,
option_t  options 
)

Prints an XML representation of the key.

String generated is of the form:

	<key name="system/sw/xorg/Monitor/Monitor0/Name"
		type="string" uid="root" gid="root" mode="0660">

		<value>Samsung TFT panel</value>
		<comment>My monitor</comment>
	</key>
	<key parent="system/sw/xorg/Monitor/Monitor0" basename="Name"
		type="string" uid="root" gid="root" mode="0660">

		<value>Samsung TFT panel</value>
		<comment>My monitor</comment>
	</key>
Parameters:
keythe key object to work with
streamwhere to write output: a file or stdout
optionsSome #option_t ORed:

  • option_t::KDB_O_NUMBERS
    Do not convert UID and GID into user and group names
  • option_t::KDB_O_CONDENSED
    Less human readable, more condensed output
  • option_t::KDB_O_FULLNAME
    The user keys are exported with their full names (including user domains)
See also:
ksToStream()
Returns:
number of bytes written to output
ssize_t keyToStreamBasename ( const Key *  key,
FILE *  stream,
const char *  parent,
const size_t  parentSize,
option_t  options 
)

Same as keyToStream() but tries to strip parentSize bytes from key name if it matches parent .

Taking the example from keyToStream(), if parent is "system/sw/xorg", the generated string is of the form:

	<key basename="Monitor/Monitor0/Name"
		type="string" uid="root" gid="root" mode="0660">

		<value>Samsung TFT panel</value>
		<comment>My monitor</comment>
	</key>

It usefull to produce more human readable XML output of a key when it is being represented in a context that defines the parent key name. For example:

	<keyset parent="user/sw">
		<key basename="kdbedit"..../>
		<key basename="phototools"..../>
		<key basename="myapp"..../>
	</keyset>

In the bove example, each <key> entry was generated by a call to keyToStreamBasename() having "user/sw" as parent .

This method is used when ksToStream() is called with KDBOption::KDB_O_HIER option.

Parameters:
keythe key object to work with
streamthe FILE where to send the stream
parentSizethe maximum size of parent that will be used. If 0, the entire parent will be used.
parentthe string (or part of it, defined by parentSize ) that will be used to strip from the key name.
optionsSome #option_t ORed:

  • option_t::KDB_O_NUMBERS
    Do not convert UID and GID into user and group names
  • option_t::KDB_O_CONDENSED
    Less human readable, more condensed output
  • option_t::KDB_O_FULLNAME
    The user keys are exported with their full names (including user domains)
Returns:
number of bytes written to output
int ksFromXML ( KeySet *  ks,
int  fd 
)

FIXME: not working when fd is stdin Given a file descriptor (that can be stdin) for an XML file, validate schema, process nodes, convert and save it in the ks KeySet.

Parameters:
kskeyset
fdFiledeskriptor?? should be FILE*
int ksFromXMLfile ( KeySet *  ks,
const char *  filename 
)

Given an XML filename, open it, validate schema, process nodes, convert and save it in the ks KeySet.

Currently, the XML file can have many root <keyset> and <key> nodes. They will all be reduced to simple keys returned in ks.

To check if the xml file is valid (best before you read from it):

#include 
char schemaPath[513];
schemaPath[0]=0;
ret=kdbGetString(handle, KDB_SCHEMA_PATH_KEY,schemaPath,sizeof(schemaPath));

if (ret==0) ret = isValidXML(filename,schemaPath);
else ret = isValidXML(filename,KDB_SCHEMA_PATH); 
Parameters:
ksthe keyset
filenamethe file to parse
int ksGenerate ( const KeySet *  ks,
FILE *  stream,
option_t  options 
)

Generate a C-Style keyset and stream it.

This keyset can be used to include as c-code for applikations using elektra.

The options takes the same options as kdbGet() and kdbSet().

Parameters:
ksthe keyset to work with
streamthe file pointer where to send the stream
optionswhich keys not to output
Returns:
1 on success
int ksOutput ( const KeySet *  ks,
FILE *  stream,
option_t  options 
)

Output all information of a keyset.

The format is not very strict and only intend to be read by human eyes for debugging purposes. Don't rely on the format in your applications.

Keys are printed line per line with keyOutput().

The same options as keyOutput() are taken and passed to them.

Additional KDB_O_HEADER will print the number of keys as first line.

Parameters:
ksthe keyset to work with
streamthe file pointer where to send the stream
options
See also:
keyOutput()
Returns:
1 on success
-1 on allocation errors
ssize_t ksToStream ( const KeySet *  ks,
FILE *  stream,
option_t  options 
)

Writes to stream an XML version of the ks object.

String generated is of the form:

<keyset>
<key name=...>...</key>
<key name=...>...</key>
<key name=...>...</key>

</keyset>
 * 

or if KDB_O_HIER is used, the form will be:

<keyset parent="user/smallest/parent/name">

<key basename=...>...</key>
<key name=...>...</key> <!-- a key thats not under this keyset's parent -->
<key basename=...>...</key>

</keyset>
 * 

KDB_O_HEADER will additionally generate a header like:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated by Elektra API. Total of n keys. -->
<keyset xmlns="http://www.libelektra.org"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.libelektra.org elektra.xsd">
 * 
Parameters:
ksthe KeySet to serialize
streamwhere to write output: a file or stdout
optionsaccepted #option_t ORed:

  • option_t::KDB_O_NUMBERS
    Do not convert UID and GID into user and group names.
  • option_t::KDB_O_FULLNAME
    The user keys are exported with their full names (including user domains)
  • option_t::KDB_O_CONDENSED
    Less human readable, more condensed output.
  • option_t::KDB_O_XMLHEADERS
    Exclude the correct XML headers in the output. If not used, the <?xml?> and schema info inside the <keyset> object will not be generated.
  • option_t::KDB_O_HIER
    Will generate a <keyset> node containing a parent attribute, and <key> nodes with a basename relative to that parent. The parent is calculated by taking the smallest key name in the keyset, so it is a good idea to have only related keys on the keyset. Otherwise, a valid consistent XML document still will be generated with regular absolute name attribute for the <key> nodes, due to a clever keyToStreamBasename() implementation.
See also:
keyToStream()
commandList() for usage example
Returns:
number of bytes written to output, or -1 if some error occurs
Parameters:
ksThe keyset to output
streamthe file pointer where to send the stream
optionssee above text