\hypertarget{group__keymeta}{}\section{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}
\subsection*{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 first metadata. \end{DoxyCompactList}\item 
const Key $\ast$ \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Iterate to the next meta information. \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 value of a meta-\/information which is current. \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 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 value of a meta-\/information given by 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 meta-\/information. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keymeta_ga11706f1753e67933f7cffc5c0345cd29}{key\+Meta}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns the keyset holding the given key\textquotesingle{}s metadata. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{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 (C\+OW)
\item no guarantee of ordering
\end{DoxyItemize}

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{[}L\+A\+NG\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. 

\subsection{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}}
\subsubsection{\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. Meta data not present in source will not be changed. Meta data which was present in source and dest will be overwritten.

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}} (0);}
\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{DoxyRetVals}{Return values}
{\em 1} & if 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{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}
\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}}
\subsubsection{\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 from source to dest. 

The key dest will have the same metadata referred with meta\+Name afterwards then source.

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 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{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} o(KeySet *ks)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key *current;}
\DoxyCodeLine{        Key *shared = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (0);}
\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{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
\end{DoxyRetVals}

\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
{\em meta\+Name} & the name of the metadata which should be copied \\
\hline
\end{DoxyParams}
\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}}
\subsubsection{\texorpdfstring{keyCurrentMeta()}{keyCurrentMeta()}}
{\footnotesize\ttfamily const Key$\ast$ key\+Current\+Meta (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the value of a meta-\/information which is current. 

The pointer is N\+U\+LL if you reached the end or after \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} & the key object to work with \\
\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 N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}}, \mbox{\hyperlink{group__keymeta_ga5dbb669802eea27e106ee3a5e39717a9}{key\+Rewind\+Meta()}}

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} for pedant in iterator interface of Key\+Set 
\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}}
\subsubsection{\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 value of a meta-\/information given by name. 

You are not allowed to modify the resulting key.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} f(Key *k)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{keywordflow}{if} (!strcmp(\mbox{\hyperlink{group__keyvalue_ga6f29609c5da53c6dc26a98678d5752af}{keyValue}}(\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{keyGetMeta}}(k, \textcolor{stringliteral}{"type"})), \textcolor{stringliteral}{"boolean"}))}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                \textcolor{comment}{// the type of the key is boolean}}
\DoxyCodeLine{        \}}
\DoxyCodeLine{\}}
\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 object to work with \\
\hline
{\em meta\+Name} & the name of the meta information you want the value from \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & if the key or meta\+Name is 0 \\
\hline
{\em 0} & if no such meta\+Name is found \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
value of meta-\/information if meta-\/information is found 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} 
\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}}
\subsubsection{\texorpdfstring{keyMeta()}{keyMeta()}}
{\footnotesize\ttfamily Key\+Set$\ast$ key\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the keyset holding the given key\textquotesingle{}s metadata. 

Use \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}} to populate the meta-\/keyset of a key.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * key = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"user/test/key"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{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 meta-\/keyset 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_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}} or \mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} to retrieve a value for a given key.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * lookupKey = \mbox{\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{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 keyset\textquotesingle{}s keys or delete them. 

You must not delete the returned Key\+Set. 

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

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & if the key is 0 \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
the keyset holding the metakeys 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}}, \mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} 
\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}}
\subsubsection{\texorpdfstring{keyNextMeta()}{keyNextMeta()}}
{\footnotesize\ttfamily const Key$\ast$ key\+Next\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Iterate to the next meta information. 

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 N\+U\+LL pointer if the meta information 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 N\+U\+LL 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 representing meta information 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & when the end is reached \\
\hline
{\em 0} & on N\+U\+LL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for pedant in iterator interface of Key\+Set 
\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}}
\subsubsection{\texorpdfstring{keyRewindMeta()}{keyRewindMeta()}}
{\footnotesize\ttfamily int key\+Rewind\+Meta (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key }\end{DoxyParamCaption})}



Rewind the internal iterator to first metadata. 

Use it to set the cursor to the beginning of the Key Meta Infos. \mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta()}} will then always return N\+U\+LL afterwards. So you want to \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} & the key object to work with \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em 0} & if there is no meta information for that key (\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will always return 0 in that case) \\
\hline
{\em -\/1} & on N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}}, \mbox{\hyperlink{group__keymeta_ga74a273f529030f4947df52e14fdd2869}{key\+Current\+Meta()}} 

\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}} for pedant in iterator interface of Key\+Set 
\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}}
\subsubsection{\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 meta-\/information. 

Will set a new meta-\/information pair consisting of meta\+Name and new\+Meta\+String.

Will add a new Pair for meta-\/information if meta\+Name was not added up to now.

It will modify an existing Pair of meta-\/information if the meta\+Name was inserted already.

It will remove a meta information if new\+Meta\+String is 0.


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em meta\+Name} & the name of the meta information where you want to change the value \\
\hline
{\em new\+Meta\+String} & the new value for the meta information \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on error if key or meta\+Name is 0, out of memory or names are not valid \\
\hline
{\em 0} & if the meta-\/information for meta\+Name was removed \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
size ($>$0) of new\+Meta\+String if meta-\/information was successfully added 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{key\+Get\+Meta()}} 
\end{DoxySeeAlso}
