$darkmode
Elektra 0.11.0
|
Methods to do various operations on Key metadata. More...
Functions | |
const Key * | keyNextMeta (Key *key) |
Get the next metadata entry of a Key. More... | |
int | keyCopyMeta (Key *dest, const Key *source, const char *metaName) |
Do a shallow copy of metadata with name metaName from source to dest. More... | |
int | keyCopyAllMeta (Key *dest, const Key *source) |
Do a shallow copy of all metadata from source to dest. More... | |
const Key * | keyGetMeta (const Key *key, const char *metaName) |
Returns the Key for a metadata entry with name metaName . More... | |
ssize_t | keySetMeta (Key *key, const char *metaName, const char *newMetaString) |
Set a new metadata Key. More... | |
KeySet * | keyMeta (Key *key) |
Returns the KeySet holding the given Key's metadata. More... | |
Methods to do various operations on Key metadata.
To use them:
Next to Name (key and owner) and value (data and comment) there is the so called meta information inside every key.
Key meta information are an unlimited number of key/value pairs strongly related to a key. It main purpose is to give keys special semantics, so that plugins can treat them differently.
Metakey, as opposed to Key, deliberately has following limitations:
File system information (see stat(2) for more information):
The comment can contain userdata which directly belong to that key. The name of the meta information is "comment" for a general purpose comment about the key. Multi-Language comments are also supported by appending [LANG] to the name.
Validators are regular expressions which are tested against the key value. The metakey "validator" can hold a regular expression which will be matched against.
Types can be expressed with the meta information "type".
The relevance of the key can be tagged with a value from -20 to 20. Negative numbers are the more important and must be present in order to start the program.
A version of a key may be stored with "version". Its format is full.major.minor where all of these are integers.
The order inside a persistent storage can be described with the tag "order" which contains a positive number.
The metakey "app" describes to which application a key belongs. It can be used to remove keys from an application no longer installed.
The metakey "path" describes where the key is physically stored.
The "owner" is the user that owns the key. It only works for the user:/ hierarchy. It rather says where the key is stored and says nothing about the filesystem properties.
int keyCopyAllMeta | ( | Key * | dest, |
const Key * | source | ||
) |
Do a shallow copy of all metadata from source to dest.
The key dest will additionally have all metadata the source had. Metadata not present in source will not be changed. Metadata which was present in source and dest will be overwritten. If the dest
Key is read-only it will not be changed.
For example the metadata type is copied into the Key k:
The main purpose of this function is for plugins or applications which want to add the same metadata to n keys. When you do that with keySetMeta() it will take n times the memory for the key. This can be considerable amount of memory for many keys with some metadata for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta():
dest's
metadata is not read-only dest | the destination where the metadata should be copied too |
source | the key where the metadata should be copied from |
1 | if metadata was successfully copied |
0 | if source did not have any metadata |
-1 | on null pointer of dest or source |
-1 | on memory problems |
dest
to source
int keyCopyMeta | ( | Key * | dest, |
const Key * | source, | ||
const char * | metaName | ||
) |
Do a shallow copy of metadata with name metaName
from source to dest.
Afterwards source
and dest
will have the same metadata referred with metaName
. If the Key with name metaName
doesn't exist in source
- it gets deleted in dest
.
For example the metadata type is copied into the Key k.
The main purpose of this function is for plugins or applications, which want to add the same metadata to n keys. When you do that keySetMeta() will take n times the memory for the key. This can be a considerable amount of memory for many keys with some metadata for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta().
dest's
metadata is not read-only dest | the destination where the metadata should be copied to |
source | the key where the metadata should be copied from |
metaName | the name of the metadata Key which should be copied |
1 | if was successfully copied |
0 | if the metadata in dest was removed too |
-1 | on null pointers (source or dest) |
-1 | on memory problems |
-1 | if metadata is read-only |
dest
to src
const Key* keyGetMeta | ( | const Key * | key, |
const char * | metaName | ||
) |
Returns the Key for a metadata entry with name metaName
.
You are not allowed to modify the resulting key.
If metaName
does not start with 'meta:/', it will be prefixed with 'meta:/'.
key
contains metadata metaName
is prefixed with "meta:/"key | the Key from which to get metadata |
metaName | the name of the meta information you want the Key from. |
0 | if key or metaName is NULL |
0 | if no such metaName is found |
KeySet* keyMeta | ( | Key * | key | ) |
Returns the KeySet holding the given Key's metadata.
Use keySetMeta() to populate the metadata KeySet of a Key.
Iterate the returned metadata KeySet like any other KeySet.
Use ksLookup() or keyGetMeta() to retrieve a single value for a given Key.
key
contains a KeySet for the metadatakey | the Key from which to get the metadata KeySet |
0 | if the Key is 0 |
const Key* keyNextMeta | ( | Key * | key | ) |
Get the next metadata entry of a Key.
Keys have an internal cursor. Every time keyNextMeta() is called the cursor is incremented and the new current Name of Meta Information is returned.
You'll get a NULL pointer if the metadata after the end of the Key was reached. On subsequent calls of keyNextMeta() it will still return the NULL pointer.
The key
internal cursor will be changed, so it is not const.
key | the Key object to work with |
0 | when the last Key has been reached |
0 | when Key is a NULL pointer |
ssize_t keySetMeta | ( | Key * | key, |
const char * | metaName, | ||
const char * | newMetaString | ||
) |
Set a new metadata Key.
Will set a new metadata pair with name metaName
and value newMetaString
.
Will add a new metadata Key, if metaName
was unused until now.
It will modify an existing Pair of metadata if metaName
was already present.
It will remove a metadata Key if newMetaString
is 0.
If metaName
does not start with 'meta:/', it will be prefixed with 'meta:/'.
metaName
is prefixed with "meta:/" key's
metadata is not read-only key's
metadata Keyset for metaName
is newMetaString
key | Key whose metadata should be set |
metaName | name of the metadata Key that should be set |
newMetaString | new value for the metadata Key |
newMetaString
if metadata has been successfully added 0 | if the meta-information for metaName was removed |
-1 | if key or metaName is 0 |
-1 | if system is out of memory |
-1 | if metaName is not a valid metadata name |