\hypertarget{group__keymeta}{}\doxysection{Meta Info Manipulation Methods}
\label{group__keymeta}\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}


Methods to do various operations on Key metadata.  


Collaboration diagram for Meta Info Manipulation Methods\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=281pt]{group__keymeta}
\end{center}
\end{figure}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{key\+Rewind\+Meta}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Rewind the internal iterator to the first entry in metadata keyset. \end{DoxyCompactList}\item 
const Key $\ast$ \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get the next metadata entry of a Key. \end{DoxyCompactList}\item 
const Key $\ast$ \mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns the metadata Key at the internal iterator\textquotesingle{}s current position. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{key\+Copy\+Meta}} (Key $\ast$dest, const Key $\ast$source, const char $\ast$meta\+Name)
\begin{DoxyCompactList}\small\item\em Do a shallow copy of metadata with name {\ttfamily meta\+Name} from source to dest. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{key\+Copy\+All\+Meta}} (Key $\ast$dest, const Key $\ast$source)
\begin{DoxyCompactList}\small\item\em Do a shallow copy of all metadata from source to dest. \end{DoxyCompactList}\item 
const Key $\ast$ \mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta}} (const Key $\ast$key, const char $\ast$meta\+Name)
\begin{DoxyCompactList}\small\item\em Returns the Key for a metadata entry with name {\ttfamily meta\+Name}. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta}} (Key $\ast$key, const char $\ast$meta\+Name, const char $\ast$new\+Meta\+String)
\begin{DoxyCompactList}\small\item\em Set a new metadata Key. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{key\+Meta}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns the Key\+Set holding the given Key\textquotesingle{}s metadata. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods to do various operations on Key metadata. 

To use them\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <kdb.h>}}

\end{DoxyCode}


Next to \mbox{\hyperlink{group__keyname}{Name (key and owner) }} and \mbox{\hyperlink{group__keyvalue}{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\+:
\begin{DoxyItemize}
\item no null values
\item no binary data
\item no modification of references (COW)
\item no guarantee of ordering
\end{DoxyItemize}\hypertarget{group__keymeta_autotoc_md0}{}\doxysubsubsection{Examples for metadata}\label{group__keymeta_autotoc_md0}
File system information (see stat(2) for more information)\+:
\begin{DoxyItemize}
\item uid\+: the user id (positive number)
\item gid\+: the group id (positive number)
\item mode\+: filesystem-\/like mode permissions (positive octal number)
\item atime\+: When was the key accessed the last time.
\item mtime\+: When was the key modified the last time.
\item ctime\+: When the uid, gid or mode of a key changes. (times are represented through a positive number as unix timestamp)
\end{DoxyItemize}

The comment can contain userdata which directly belong to that key. The name of the meta information is \char`\"{}comment\char`\"{} for a general purpose comment about the key. Multi-\/\+Language comments are also supported by appending \mbox{[}LANG\mbox{]} to the name.

Validators are regular expressions which are tested against the key value. The metakey \char`\"{}validator\char`\"{} can hold a regular expression which will be matched against.

Types can be expressed with the meta information \char`\"{}type\char`\"{}.

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 \char`\"{}version\char`\"{}. Its format is full.\+major.\+minor where all of these are integers.

The order inside a persistent storage can be described with the tag \char`\"{}order\char`\"{} which contains a positive number.

The metakey \char`\"{}app\char`\"{} describes to which application a key belongs. It can be used to remove keys from an application no longer installed.

The metakey \char`\"{}path\char`\"{} describes where the key is physically stored.

The \char`\"{}owner\char`\"{} 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. 

\doxysubsection{Function Documentation}
\mbox{\Hypertarget{group__keymeta_ga8e63720a65610a29597494d0671f9401}\label{group__keymeta_ga8e63720a65610a29597494d0671f9401}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyCopyAllMeta@{keyCopyAllMeta}}
\index{keyCopyAllMeta@{keyCopyAllMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyCopyAllMeta()}{keyCopyAllMeta()}}
{\footnotesize\ttfamily int key\+Copy\+All\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{dest,  }\item[{const Key $\ast$}]{source }\end{DoxyParamCaption})}



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 {\ttfamily dest} Key is read-\/only it will not be changed.

For example the metadata type is copied into the Key k\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} l (Key * k)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{comment}{// receive copy}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{keyCopyAllMeta}} (k, copy);}
\DoxyCodeLine{        \textcolor{comment}{// the caller will see the changed key k}}
\DoxyCodeLine{        \textcolor{comment}{// with all the metadata from copy}}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}
 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 \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} 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 \mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{key\+Copy\+All\+Meta()}} or \mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{key\+Copy\+Meta()}}\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} o (KeySet * ks)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * current;}
\DoxyCodeLine{        Key * shared = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}/"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}} (shared, \textcolor{stringliteral}{"{}shared1"{}}, \textcolor{stringliteral}{"{}this metadata should be shared among many keys"{}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}} (shared, \textcolor{stringliteral}{"{}shared2"{}}, \textcolor{stringliteral}{"{}this metadata should be shared among many keys also"{}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}} (shared, \textcolor{stringliteral}{"{}shared3"{}}, \textcolor{stringliteral}{"{}this metadata should be shared among many keys too"{}});}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (ks);}
\DoxyCodeLine{        \textcolor{keywordflow}{while} ((current = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}} (ks)) != 0)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                \textcolor{keywordflow}{if} (needsSharedData (current)) \mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{keyCopyAllMeta}} (current, shared);}
\DoxyCodeLine{        \}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (shared);}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}
 \begin{DoxyPostcond}{Postcondition}
for every meta\+Name present in source\+: key\+Get\+Meta(source, meta\+Name) == key\+Get\+Meta(dest, meta\+Name)
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em dest} & the destination where the metadata should be copied too \\
\hline
{\em source} & the key where the metadata should be copied from\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if metadata was successfully copied \\
\hline
{\em 0} & if source did not have any metadata \\
\hline
{\em -\/1} & on null pointer of dest or source \\
\hline
{\em -\/1} & on memory problems\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{key\+Copy\+Meta()}} for copying one metadata Key from {\ttfamily dest} to {\ttfamily source} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}\label{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyCopyMeta@{keyCopyMeta}}
\index{keyCopyMeta@{keyCopyMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyCopyMeta()}{keyCopyMeta()}}
{\footnotesize\ttfamily int key\+Copy\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{dest,  }\item[{const Key $\ast$}]{source,  }\item[{const char $\ast$}]{meta\+Name }\end{DoxyParamCaption})}



Do a shallow copy of metadata with name {\ttfamily meta\+Name} from source to dest. 

Afterwards {\ttfamily source} and {\ttfamily dest} will have the same metadata referred with {\ttfamily meta\+Name}. If the Key with name {\ttfamily meta\+Name} doesn\textquotesingle{}t exist in {\ttfamily src} -\/ it gets deleted in {\ttfamily dest}.

For example the metadata type is copied into the Key k.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} l(Key *k)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{comment}{// receive c}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{keyCopyMeta}}(k, c, \textcolor{stringliteral}{"{}type"{}});}
\DoxyCodeLine{        \textcolor{comment}{// the caller will see the changed key k}}
\DoxyCodeLine{        \textcolor{comment}{// with the metadata "{}type"{} from c}}
\DoxyCodeLine{\}}

\end{DoxyCode}


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 \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} 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 \mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{key\+Copy\+All\+Meta()}} or \mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{key\+Copy\+Meta()}}.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} o(KeySet *ks)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key *current;}
\DoxyCodeLine{        Key *shared = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}/"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}}(shared, \textcolor{stringliteral}{"{}shared"{}}, \textcolor{stringliteral}{"{}this metadata should be shared among many keys"{}});}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}}(ks);}
\DoxyCodeLine{        \textcolor{keywordflow}{while} ((current = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}}(ks)) != 0)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                \textcolor{keywordflow}{if} (needs\_shared\_data(current)) \mbox{\hyperlink{group__keymeta_ga9a22b992478e613c8788bd460b4a1f0c}{keyCopyMeta}}(current, shared, \textcolor{stringliteral}{"{}shared"{}});}
\DoxyCodeLine{        \}}
\DoxyCodeLine{\}}

\end{DoxyCode}


\begin{DoxyPostcond}{Postcondition}
key\+Get\+Meta(source, meta\+Name) == key\+Get\+Meta(dest, meta\+Name)
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em dest} & the destination where the metadata should be copied to \\
\hline
{\em source} & the key where the metadata should be copied from \\
\hline
{\em meta\+Name} & the name of the metadata Key which should be copied\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if was successfully copied \\
\hline
{\em 0} & if the metadata in dest was removed too \\
\hline
{\em -\/1} & on null pointers (source or dest) \\
\hline
{\em -\/1} & on memory problems \\
\hline
{\em -\/1} & if metadata is read-\/only\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga8e63720a65610a29597494d0671f9401}{key\+Copy\+All\+Meta()}} copies all metadata from {\ttfamily dest} to {\ttfamily src} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga74a273f529030f4947df52e14fdd2869}\label{group__keymeta_ga74a273f529030f4947df52e14fdd2869}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyCurrentMeta@{keyCurrentMeta}}
\index{keyCurrentMeta@{keyCurrentMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyCurrentMeta()}{keyCurrentMeta()}}
{\footnotesize\ttfamily const Key$\ast$ key\+Current\+Meta (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the metadata Key at the internal iterator\textquotesingle{}s current position. 

The returned pointer is NULL if the end has been reached or after calling \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}.

\begin{DoxyNote}{Note}
You must not delete or change the returned key, use \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} if you want to delete or change it.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & Key to get the current metadata from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a buffer to the value pointed by {\ttfamily key\textquotesingle{}s} cursor 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} for getting the next value 

\mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{key\+Rewind\+Meta()}} for rewinding the internal iterator 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} Key\+Sets\textquotesingle{}s equivalent function for getting the current Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}\label{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyGetMeta@{keyGetMeta}}
\index{keyGetMeta@{keyGetMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetMeta()}{keyGetMeta()}}
{\footnotesize\ttfamily const Key$\ast$ key\+Get\+Meta (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{const char $\ast$}]{meta\+Name }\end{DoxyParamCaption})}



Returns the Key for a metadata entry with name {\ttfamily meta\+Name}. 

You are not allowed to modify the resulting key.

If {\ttfamily meta\+Name} does not start with \textquotesingle{}meta\+:/\textquotesingle{}, it will be prefixed with \textquotesingle{}meta\+:/\textquotesingle{}.


\begin{DoxyCode}{0}
\DoxyCodeLine{Key metaData = \mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{keyGetMeta}}(k, \textcolor{stringliteral}{"{}type"{}})}
\DoxyCodeLine{\textcolor{comment}{// keyType == "{}boolean"{}}}
\DoxyCodeLine{char keyType[] = \mbox{\hyperlink{group__keyvalue_ga6f29609c5da53c6dc26a98678d5752af}{keyValue}}(metaData)}

\end{DoxyCode}


\begin{DoxyNote}{Note}
You must not delete or change the returned key, use \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} if you want to delete or change it.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the Key from which to get metadata \\
\hline
{\em meta\+Name} & the name of the meta information you want the Key from.\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
value of meta-\/information if meta-\/information is found 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if key or meta\+Name is NULL \\
\hline
{\em 0} & if no such meta\+Name is found\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} for setting metadata 

\mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{key\+Meta()}} for getting the Key\+Set containing metadata 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}\label{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyMeta@{keyMeta}}
\index{keyMeta@{keyMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyMeta()}{keyMeta()}}
{\footnotesize\ttfamily Key\+Set$\ast$ key\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the Key\+Set holding the given Key\textquotesingle{}s metadata. 

Use \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} to populate the metadata Key\+Set of a Key.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * key = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/test/key"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}} (key, \textcolor{stringliteral}{"{}meta1"{}}, \textcolor{stringliteral}{"{}value1"{}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{keySetMeta}} (key, \textcolor{stringliteral}{"{}meta2"{}}, \textcolor{stringliteral}{"{}value2"{}});}

\end{DoxyCodeInclude}
 Iterate the returned metadata Key\+Set like any other Key\+Set.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * cur;}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (\mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{keyMeta}} (key));}
\DoxyCodeLine{        \textcolor{keywordflow}{while} ((cur = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}} (\mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{keyMeta}} (key))) != NULL)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                printf (\textcolor{stringliteral}{"{}meta name: \%s, meta value: \%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (cur), \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (cur));}
\DoxyCodeLine{        \}}

\end{DoxyCodeInclude}
 Use \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} or \mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} to retrieve a single value for a given Key.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * lookupKey = \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName}} (\mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{keyMeta}} (key), \textcolor{stringliteral}{"{}meta2"{}}, 0);}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}meta name: \%s, meta value: \%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (lookupKey), \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (lookupKey));}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (key);}

\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
You are not allowed to modify the name of Key\+Set\textquotesingle{}s Keys or delete them. 

You must not delete the returned Key\+Set. 

Adding a key with metadata to the Key\+Set is an error.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the Key from which to get the metadata Key\+Set\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the Key\+Set holding the metadata 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if the Key is 0 \\
\hline
{\em 0} & if the Key has no metadata\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} for setting a metadata Key 

\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} for getting a metadata Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga4c88342f580a4291455a801af71ce048}\label{group__keymeta_ga4c88342f580a4291455a801af71ce048}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyNextMeta@{keyNextMeta}}
\index{keyNextMeta@{keyNextMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyNextMeta()}{keyNextMeta()}}
{\footnotesize\ttfamily const Key$\ast$ key\+Next\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Get the next metadata entry of a Key. 

Keys have an internal cursor that can be reset with \mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{key\+Rewind\+Meta()}}. Every time \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} is called the cursor is incremented and the new current Name of Meta Information is returned.

You\textquotesingle{}ll get a NULL pointer if the metadata after the end of the Key was reached. On subsequent calls of \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} it will still return the NULL pointer.

The {\ttfamily key} internal cursor will be changed, so it is not const.

\begin{DoxyNote}{Note}
That the resulting key is guaranteed to have a value, because meta information has no binary or null pointer semantics.

You must not delete or change the returned key, use \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} if you want to delete or change it.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the Key object to work with\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a key containing metadata 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & when the last Key has been reached \\
\hline
{\em 0} & when Key is a NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for pedant in iterator interface of Key\+Set 

\mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{key\+Rewind\+Meta()}} for rewinding the internal iterator 

\mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta()}} for getting the current metadata Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}\label{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keyRewindMeta@{keyRewindMeta}}
\index{keyRewindMeta@{keyRewindMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyRewindMeta()}{keyRewindMeta()}}
{\footnotesize\ttfamily int key\+Rewind\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Rewind the internal iterator to the first entry in metadata keyset. 

Use this function to set the cursor to the beginning of the Key Meta Infos. \mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta()}} will always return NULL after rewinding, so you need to call \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} first.


\begin{DoxyCode}{0}
\DoxyCodeLine{Key *key;}
\DoxyCodeLine{\textcolor{keyword}{const} Key *meta;}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{keyRewindMeta}} (key);}
\DoxyCodeLine{\textcolor{keywordflow}{while} ((meta = \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{keyNextMeta}} (key))!=0)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}name: \%s, value: \%s"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}}(meta), \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}}(meta));}
\DoxyCodeLine{\}}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em key} & Key whose internal iterator should be rewinded\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em 0} & if there is no metadata for that key (\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will always return 0 in that case) \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}}, \mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta()}} for iterating after rewinding 

\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}} Key\+Set\textquotesingle{}s equivalent function for rewinding 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}\label{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}} 
\index{Meta Info Manipulation Methods@{Meta Info Manipulation Methods}!keySetMeta@{keySetMeta}}
\index{keySetMeta@{keySetMeta}!Meta Info Manipulation Methods@{Meta Info Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keySetMeta()}{keySetMeta()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{meta\+Name,  }\item[{const char $\ast$}]{new\+Meta\+String }\end{DoxyParamCaption})}



Set a new metadata Key. 

Will set a new metadata pair with name {\ttfamily meta\+Name} and value {\ttfamily new\+Meta\+String}.

Will add a new metadata Key, if {\ttfamily meta\+Name} was unused until now.

It will modify an existing Pair of metadata if {\ttfamily meta\+Name} was already present.

It will remove a metadata Key if {\ttfamily new\+Meta\+String} is 0.

If {\ttfamily meta\+Name} does not start with \textquotesingle{}meta\+:/\textquotesingle{}, it will be prefixed with \textquotesingle{}meta\+:/\textquotesingle{}.


\begin{DoxyParams}{Parameters}
{\em key} & Key whose metadata should be set \\
\hline
{\em meta\+Name} & name of the metadata Key that should be set \\
\hline
{\em new\+Meta\+String} & new value for the metadata Key\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
size ($>$0) of {\ttfamily new\+Meta\+String} if metadata has been successfully added 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if the meta-\/information for meta\+Name was removed \\
\hline
{\em -\/1} & if key or meta\+Name is 0 \\
\hline
{\em -\/1} & if system is out of memory \\
\hline
{\em -\/1} & if {\ttfamily meta\+Name} is not a valid metadata name\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} for getting the value of a metadata Key 

\mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{key\+Meta()}} for getting the Key\+Set containing metadata 
\end{DoxySeeAlso}
