<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libnl: include/netlink/cache-api.h Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.3 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libnl <span id="projectnumber">1.1</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="files.html"><span>File List</span></a></li>
</ul>
</div>
<div class="header">
<div class="headertitle">
<h1>include/netlink/cache-api.h</h1> </div>
</div>
<div class="contents">
<div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="comment">/*</span>
<a name="l00002"></a>00002 <span class="comment"> * netlink/cache-api.h Caching API</span>
<a name="l00003"></a>00003 <span class="comment"> *</span>
<a name="l00004"></a>00004 <span class="comment"> * This library is free software; you can redistribute it and/or</span>
<a name="l00005"></a>00005 <span class="comment"> * modify it under the terms of the GNU Lesser General Public</span>
<a name="l00006"></a>00006 <span class="comment"> * License as published by the Free Software Foundation version 2.1</span>
<a name="l00007"></a>00007 <span class="comment"> * of the License.</span>
<a name="l00008"></a>00008 <span class="comment"> *</span>
<a name="l00009"></a>00009 <span class="comment"> * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch></span>
<a name="l00010"></a>00010 <span class="comment"> */</span>
<a name="l00011"></a>00011
<a name="l00012"></a>00012 <span class="preprocessor">#ifndef NETLINK_CACHE_API_H_</span>
<a name="l00013"></a>00013 <span class="preprocessor"></span><span class="preprocessor">#define NETLINK_CACHE_API_H_</span>
<a name="l00014"></a>00014 <span class="preprocessor"></span>
<a name="l00015"></a>00015 <span class="preprocessor">#include <netlink/netlink.h></span>
<a name="l00016"></a>00016
<a name="l00017"></a>00017 <span class="preprocessor">#ifdef __cplusplus</span>
<a name="l00018"></a>00018 <span class="preprocessor"></span><span class="keyword">extern</span> <span class="stringliteral">"C"</span> {
<a name="l00019"></a>00019 <span class="preprocessor">#endif</span>
<a name="l00020"></a>00020 <span class="preprocessor"></span><span class="comment"></span>
<a name="l00021"></a>00021 <span class="comment">/**</span>
<a name="l00022"></a>00022 <span class="comment"> * @ingroup cache</span>
<a name="l00023"></a>00023 <span class="comment"> * @defgroup cache_api Cache Implementation</span>
<a name="l00024"></a>00024 <span class="comment"> * @brief</span>
<a name="l00025"></a>00025 <span class="comment"> *</span>
<a name="l00026"></a>00026 <span class="comment"> * @par 1) Cache Definition</span>
<a name="l00027"></a>00027 <span class="comment"> * @code</span>
<a name="l00028"></a>00028 <span class="comment"> * struct nl_cache_ops my_cache_ops = {</span>
<a name="l00029"></a>00029 <span class="comment"> * .co_name = "route/link",</span>
<a name="l00030"></a>00030 <span class="comment"> * .co_protocol = NETLINK_ROUTE,</span>
<a name="l00031"></a>00031 <span class="comment"> * .co_hdrsize = sizeof(struct ifinfomsg),</span>
<a name="l00032"></a>00032 <span class="comment"> * .co_obj_ops = &my_obj_ops,</span>
<a name="l00033"></a>00033 <span class="comment"> * };</span>
<a name="l00034"></a>00034 <span class="comment"> * @endcode</span>
<a name="l00035"></a>00035 <span class="comment"> *</span>
<a name="l00036"></a>00036 <span class="comment"> * @par 2) </span>
<a name="l00037"></a>00037 <span class="comment"> * @code</span>
<a name="l00038"></a>00038 <span class="comment"> * // The simplest way to fill a cache is by providing a request-update</span>
<a name="l00039"></a>00039 <span class="comment"> * // function which must trigger a complete dump on the kernel-side of</span>
<a name="l00040"></a>00040 <span class="comment"> * // whatever the cache covers.</span>
<a name="l00041"></a>00041 <span class="comment"> * static int my_request_update(struct nl_cache *cache,</span>
<a name="l00042"></a>00042 <span class="comment"> * struct nl_handle *socket)</span>
<a name="l00043"></a>00043 <span class="comment"> * {</span>
<a name="l00044"></a>00044 <span class="comment"> * // In this example, we request a full dump of the interface table</span>
<a name="l00045"></a>00045 <span class="comment"> * return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP);</span>
<a name="l00046"></a>00046 <span class="comment"> * }</span>
<a name="l00047"></a>00047 <span class="comment"> *</span>
<a name="l00048"></a>00048 <span class="comment"> * // The resulting netlink messages sent back will be fed into a message</span>
<a name="l00049"></a>00049 <span class="comment"> * // parser one at a time. The message parser has to extract all relevant</span>
<a name="l00050"></a>00050 <span class="comment"> * // information from the message and create an object reflecting the</span>
<a name="l00051"></a>00051 <span class="comment"> * // contents of the message and pass it on to the parser callback function</span>
<a name="l00052"></a>00052 <span class="comment"> * // provide which will add the object to the cache.</span>
<a name="l00053"></a>00053 <span class="comment"> * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who,</span>
<a name="l00054"></a>00054 <span class="comment"> * struct nlmsghdr *nlh, struct nl_parser_param *pp)</span>
<a name="l00055"></a>00055 <span class="comment"> * {</span>
<a name="l00056"></a>00056 <span class="comment"> * struct my_obj *obj;</span>
<a name="l00057"></a>00057 <span class="comment"> *</span>
<a name="l00058"></a>00058 <span class="comment"> * obj = my_obj_alloc();</span>
<a name="l00059"></a>00059 <span class="comment"> * obj->ce_msgtype = nlh->nlmsg_type;</span>
<a name="l00060"></a>00060 <span class="comment"> *</span>
<a name="l00061"></a>00061 <span class="comment"> * // Parse the netlink message and continue creating the object.</span>
<a name="l00062"></a>00062 <span class="comment"> *</span>
<a name="l00063"></a>00063 <span class="comment"> * err = pp->pp_cb((struct nl_object *) obj, pp);</span>
<a name="l00064"></a>00064 <span class="comment"> * if (err < 0)</span>
<a name="l00065"></a>00065 <span class="comment"> * goto errout;</span>
<a name="l00066"></a>00066 <span class="comment"> * }</span>
<a name="l00067"></a>00067 <span class="comment"> *</span>
<a name="l00068"></a>00068 <span class="comment"> * struct nl_cache_ops my_cache_ops = {</span>
<a name="l00069"></a>00069 <span class="comment"> * ...</span>
<a name="l00070"></a>00070 <span class="comment"> * .co_request_update = my_request_update,</span>
<a name="l00071"></a>00071 <span class="comment"> * .co_msg_parser = my_msg_parser,</span>
<a name="l00072"></a>00072 <span class="comment"> * };</span>
<a name="l00073"></a>00073 <span class="comment"> * @endcode</span>
<a name="l00074"></a>00074 <span class="comment"> *</span>
<a name="l00075"></a>00075 <span class="comment"> * @par 3) Notification based Updates</span>
<a name="l00076"></a>00076 <span class="comment"> * @code</span>
<a name="l00077"></a>00077 <span class="comment"> * // Caches can be kept up-to-date based on notifications if the kernel</span>
<a name="l00078"></a>00078 <span class="comment"> * // sends out notifications whenever an object is added/removed/changed.</span>
<a name="l00079"></a>00079 <span class="comment"> * //</span>
<a name="l00080"></a>00080 <span class="comment"> * // It is trivial to support this, first a list of groups needs to be</span>
<a name="l00081"></a>00081 <span class="comment"> * // defined which are required to join in order to receive all necessary</span>
<a name="l00082"></a>00082 <span class="comment"> * // notifications. The groups are separated by address family to support</span>
<a name="l00083"></a>00083 <span class="comment"> * // the common situation where a separate group is used for each address</span>
<a name="l00084"></a>00084 <span class="comment"> * // family. If there is only one group, simply specify AF_UNSPEC.</span>
<a name="l00085"></a>00085 <span class="comment"> * static struct nl_af_group addr_groups[] = {</span>
<a name="l00086"></a>00086 <span class="comment"> * { AF_INET, RTNLGRP_IPV4_IFADDR },</span>
<a name="l00087"></a>00087 <span class="comment"> * { AF_INET6, RTNLGRP_IPV6_IFADDR },</span>
<a name="l00088"></a>00088 <span class="comment"> * { END_OF_GROUP_LIST },</span>
<a name="l00089"></a>00089 <span class="comment"> * };</span>
<a name="l00090"></a>00090 <span class="comment"> *</span>
<a name="l00091"></a>00091 <span class="comment"> * // In order for the caching system to know the meaning of each message</span>
<a name="l00092"></a>00092 <span class="comment"> * // type it requires a table which maps each supported message type to</span>
<a name="l00093"></a>00093 <span class="comment"> * // a cache action, e.g. RTM_NEWADDR means address has been added or</span>
<a name="l00094"></a>00094 <span class="comment"> * // updated, RTM_DELADDR means address has been removed.</span>
<a name="l00095"></a>00095 <span class="comment"> * static struct nl_cache_ops rtnl_addr_ops = {</span>
<a name="l00096"></a>00096 <span class="comment"> * ...</span>
<a name="l00097"></a>00097 <span class="comment"> * .co_msgtypes = {</span>
<a name="l00098"></a>00098 <span class="comment"> * { RTM_NEWADDR, NL_ACT_NEW, "new" },</span>
<a name="l00099"></a>00099 <span class="comment"> * { RTM_DELADDR, NL_ACT_DEL, "del" },</span>
<a name="l00100"></a>00100 <span class="comment"> * { RTM_GETADDR, NL_ACT_GET, "get" },</span>
<a name="l00101"></a>00101 <span class="comment"> * END_OF_MSGTYPES_LIST,</span>
<a name="l00102"></a>00102 <span class="comment"> * },</span>
<a name="l00103"></a>00103 <span class="comment"> * .co_groups = addr_groups,</span>
<a name="l00104"></a>00104 <span class="comment"> * };</span>
<a name="l00105"></a>00105 <span class="comment"> *</span>
<a name="l00106"></a>00106 <span class="comment"> * // It is now possible to keep the cache up-to-date using the cache manager.</span>
<a name="l00107"></a>00107 <span class="comment"> * @endcode</span>
<a name="l00108"></a>00108 <span class="comment"> * @{</span>
<a name="l00109"></a>00109 <span class="comment"> */</span>
<a name="l00110"></a>00110
<a name="l00111"></a>00111 <span class="keyword">enum</span> {
<a name="l00112"></a>00112 NL_ACT_UNSPEC,
<a name="l00113"></a>00113 NL_ACT_NEW,
<a name="l00114"></a>00114 NL_ACT_DEL,
<a name="l00115"></a>00115 NL_ACT_GET,
<a name="l00116"></a>00116 NL_ACT_SET,
<a name="l00117"></a>00117 NL_ACT_CHANGE,
<a name="l00118"></a>00118 __NL_ACT_MAX,
<a name="l00119"></a>00119 };
<a name="l00120"></a>00120
<a name="l00121"></a>00121 <span class="preprocessor">#define NL_ACT_MAX (__NL_ACT_MAX - 1)</span>
<a name="l00122"></a>00122 <span class="preprocessor"></span>
<a name="l00123"></a>00123 <span class="preprocessor">#define END_OF_MSGTYPES_LIST { -1, -1, NULL }</span>
<a name="l00124"></a>00124 <span class="preprocessor"></span><span class="comment"></span>
<a name="l00125"></a>00125 <span class="comment">/**</span>
<a name="l00126"></a>00126 <span class="comment"> * Message type to cache action association</span>
<a name="l00127"></a>00127 <span class="comment"> */</span>
<a name="l00128"></a><a class="code" href="structnl__msgtype.html">00128</a> <span class="keyword">struct </span><a class="code" href="structnl__msgtype.html" title="Message type to cache action association.">nl_msgtype</a>
<a name="l00129"></a>00129 {<span class="comment"></span>
<a name="l00130"></a>00130 <span class="comment"> /** Netlink message type */</span>
<a name="l00131"></a><a class="code" href="structnl__msgtype.html#a2b51527c3258ef4231b84d856a7c4164">00131</a> <span class="keywordtype">int</span> <a class="code" href="structnl__msgtype.html#a2b51527c3258ef4231b84d856a7c4164" title="Netlink message type.">mt_id</a>;
<a name="l00132"></a>00132 <span class="comment"></span>
<a name="l00133"></a>00133 <span class="comment"> /** Cache action to take */</span>
<a name="l00134"></a><a class="code" href="structnl__msgtype.html#a5d312dd2e16f5ef1301e9e59c9e14965">00134</a> <span class="keywordtype">int</span> <a class="code" href="structnl__msgtype.html#a5d312dd2e16f5ef1301e9e59c9e14965" title="Cache action to take.">mt_act</a>;
<a name="l00135"></a>00135 <span class="comment"></span>
<a name="l00136"></a>00136 <span class="comment"> /** Name of operation for human-readable printing */</span>
<a name="l00137"></a><a class="code" href="structnl__msgtype.html#a8a50cfe0a76d4bbe95473f5d2a3a5b96">00137</a> <span class="keywordtype">char</span> * <a class="code" href="structnl__msgtype.html#a8a50cfe0a76d4bbe95473f5d2a3a5b96" title="Name of operation for human-readable printing.">mt_name</a>;
<a name="l00138"></a>00138 };
<a name="l00139"></a>00139 <span class="comment"></span>
<a name="l00140"></a>00140 <span class="comment">/**</span>
<a name="l00141"></a>00141 <span class="comment"> * Address family to netlink group association</span>
<a name="l00142"></a>00142 <span class="comment"> */</span>
<a name="l00143"></a><a class="code" href="structnl__af__group.html">00143</a> <span class="keyword">struct </span><a class="code" href="structnl__af__group.html" title="Address family to netlink group association.">nl_af_group</a>
<a name="l00144"></a>00144 {<span class="comment"></span>
<a name="l00145"></a>00145 <span class="comment"> /** Address family */</span>
<a name="l00146"></a><a class="code" href="structnl__af__group.html#aee1cd56c66c286b0f1747a6b6c174099">00146</a> <span class="keywordtype">int</span> <a class="code" href="structnl__af__group.html#aee1cd56c66c286b0f1747a6b6c174099" title="Address family.">ag_family</a>;
<a name="l00147"></a>00147 <span class="comment"></span>
<a name="l00148"></a>00148 <span class="comment"> /** Netlink group identifier */</span>
<a name="l00149"></a><a class="code" href="structnl__af__group.html#a8b51cf29b78960889696f161d5a852f8">00149</a> <span class="keywordtype">int</span> <a class="code" href="structnl__af__group.html#a8b51cf29b78960889696f161d5a852f8" title="Netlink group identifier.">ag_group</a>;
<a name="l00150"></a>00150 };
<a name="l00151"></a>00151
<a name="l00152"></a>00152 <span class="preprocessor">#define END_OF_GROUP_LIST AF_UNSPEC, 0</span>
<a name="l00153"></a>00153 <span class="preprocessor"></span>
<a name="l00154"></a><a class="code" href="structnl__parser__param.html">00154</a> <span class="keyword">struct </span><a class="code" href="structnl__parser__param.html">nl_parser_param</a>
<a name="l00155"></a>00155 {
<a name="l00156"></a>00156 int (*pp_cb)(<span class="keyword">struct </span>nl_object *, <span class="keyword">struct </span><a class="code" href="structnl__parser__param.html">nl_parser_param</a> *);
<a name="l00157"></a>00157 <span class="keywordtype">void</span> * pp_arg;
<a name="l00158"></a>00158 };
<a name="l00159"></a>00159 <span class="comment"></span>
<a name="l00160"></a>00160 <span class="comment">/**</span>
<a name="l00161"></a>00161 <span class="comment"> * Cache Operations</span>
<a name="l00162"></a>00162 <span class="comment"> */</span>
<a name="l00163"></a><a class="code" href="structnl__cache__ops.html">00163</a> <span class="keyword">struct </span><a class="code" href="structnl__cache__ops.html" title="Cache Operations.">nl_cache_ops</a>
<a name="l00164"></a>00164 {
<a name="l00165"></a>00165 <span class="keywordtype">char</span> * co_name;
<a name="l00166"></a>00166
<a name="l00167"></a>00167 <span class="keywordtype">int</span> co_hdrsize;
<a name="l00168"></a>00168 <span class="keywordtype">int</span> co_protocol;
<a name="l00169"></a>00169 <span class="keyword">struct </span><a class="code" href="structnl__af__group.html" title="Address family to netlink group association.">nl_af_group</a> * co_groups;
<a name="l00170"></a>00170 <span class="comment"></span>
<a name="l00171"></a>00171 <span class="comment"> /**</span>
<a name="l00172"></a>00172 <span class="comment"> * Called whenever an update of the cache is required. Must send</span>
<a name="l00173"></a>00173 <span class="comment"> * a request message to the kernel requesting a complete dump.</span>
<a name="l00174"></a>00174 <span class="comment"> */</span>
<a name="l00175"></a><a class="code" href="structnl__cache__ops.html#a93ec4756f5c0ae7c105cf3b3b1473476">00175</a> int (*<a class="code" href="structnl__cache__ops.html#a93ec4756f5c0ae7c105cf3b3b1473476" title="Called whenever an update of the cache is required.">co_request_update</a>)(<span class="keyword">struct </span>nl_cache *, <span class="keyword">struct </span>nl_handle *);
<a name="l00176"></a>00176 <span class="comment"></span>
<a name="l00177"></a>00177 <span class="comment"> /**</span>
<a name="l00178"></a>00178 <span class="comment"> * Called whenever a message was received that needs to be parsed.</span>
<a name="l00179"></a>00179 <span class="comment"> * Must parse the message and call the paser callback function</span>
<a name="l00180"></a>00180 <span class="comment"> * (nl_parser_param) provided via the argument.</span>
<a name="l00181"></a>00181 <span class="comment"> */</span>
<a name="l00182"></a><a class="code" href="structnl__cache__ops.html#aeea6ef6813bb58a76c3d44454271678f">00182</a> int (*<a class="code" href="structnl__cache__ops.html#aeea6ef6813bb58a76c3d44454271678f" title="Called whenever a message was received that needs to be parsed.">co_msg_parser</a>)(<span class="keyword">struct </span><a class="code" href="structnl__cache__ops.html" title="Cache Operations.">nl_cache_ops</a> *, <span class="keyword">struct </span><a class="code" href="structsockaddr__nl.html" title="Netlink socket address.">sockaddr_nl</a> *,
<a name="l00183"></a>00183 <span class="keyword">struct </span><a class="code" href="structnlmsghdr.html" title="Netlink message header.">nlmsghdr</a> *, <span class="keyword">struct </span><a class="code" href="structnl__parser__param.html">nl_parser_param</a> *);
<a name="l00184"></a>00184
<a name="l00185"></a>00185 <span class="keyword">struct </span><a class="code" href="structnl__object__ops.html" title="Object Operations.">nl_object_ops</a> * co_obj_ops;
<a name="l00186"></a>00186
<a name="l00187"></a>00187 <span class="keyword">struct </span><a class="code" href="structnl__cache__ops.html" title="Cache Operations.">nl_cache_ops</a> *co_next;
<a name="l00188"></a>00188 <span class="keyword">struct </span>nl_cache *co_major_cache;
<a name="l00189"></a>00189 <span class="keyword">struct </span><a class="code" href="structgenl__ops.html" title="Generic Netlink Operations.">genl_ops</a> * co_genl;
<a name="l00190"></a>00190 <span class="keyword">struct </span><a class="code" href="structnl__msgtype.html" title="Message type to cache action association.">nl_msgtype</a> co_msgtypes[];
<a name="l00191"></a>00191 };
<a name="l00192"></a>00192 <span class="comment"></span>
<a name="l00193"></a>00193 <span class="comment">/** @} */</span>
<a name="l00194"></a>00194
<a name="l00195"></a>00195 <span class="preprocessor">#ifdef __cplusplus</span>
<a name="l00196"></a>00196 <span class="preprocessor"></span>}
<a name="l00197"></a>00197 <span class="preprocessor">#endif</span>
<a name="l00198"></a>00198 <span class="preprocessor"></span>
<a name="l00199"></a>00199 <span class="preprocessor">#endif</span>
</pre></div></div>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Mon Mar 21 2011 for libnl by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
</body>
</html>
